25. Building and releasing ASP

This chapter will describe how ASP can be built from source and with conda, how to build the documentation, and how to prepare a new ASP release. This is focused towards the developer. Users should read instead the installation guide in Section 2.

25.1. Building ASP from source

All dependencies for the latest development version of ASP are available as a binary tarball.

The dependencies for the latest stable version of ASP are in the stereopipeline-feedstock repository (Section 25.2.3).

Assume that all dependencies, including the development tools, are installed in the asp_deps conda environment and the PATH variable is set up to use them.

Create a work directory:

workDir=$HOME/build_asp
mkdir -p $workDir

Build VisionWorkbench and Stereo Pipeline version <asp version>:

cd $workDir
envPath=$HOME/miniconda3/envs/asp_deps
$envPath/bin/git clone                            \
    git@github.com:visionworkbench/visionworkbench.git
cd visionworkbench
# Build a specific version
git checkout <asp version>
mkdir -p build
cd build
$envPath/bin/cmake ..                             \
  -DASP_DEPS_DIR=$envPath                         \
  -DCMAKE_INSTALL_PREFIX=$workDir/install
make -j10 && make install

cd $workDir
envPath=$HOME/miniconda3/envs/asp_deps
$envPath/bin/git clone                            \
git@github.com:NeoGeographyToolkit/StereoPipeline.git
cd StereoPipeline
# Build a specific version
git checkout <asp version>
mkdir -p build
cd build
$envPath/bin/cmake ..                             \
  -DASP_DEPS_DIR=$envPath                         \
  -DCMAKE_INSTALL_PREFIX=$workDir/install         \
  -DVISIONWORKBENCH_INSTALL_DIR=$workDir/install
make -j10 && make install

Check that the compilers were picked up correctly.

25.2. Building ASP and its dependencies with conda

This page is meant for advanced users of ASP and maintainers who would like to use conda to rebuild ASP and all its dependencies. It is suggested to carefully read Section 2.2 before this page.

To simplify maintenance, ASP and its dependencies are built upon ISIS and its dependencies. The process for this is outlined below.

25.2.1. Setting up the ISIS environment

Search for the latest available ISIS conda package:

conda search -c usgs-astrogeology --override-channels isis

Use the latest version found above. See Section 2.3.1 for more about ISIS and how to fetch its data.

Create and activate a conda environment for ISIS:

conda create -n isis
conda activate isis

Add these channels to conda:

conda config --env --add channels conda-forge
conda config --env --add channels usgs-astrogeology

Run:

conda config --show channels

and verify that usgs-astrogeology and conda-forge are in this order and above all other channels, except perhaps the nasa-ames-stereo-pipeline channel.

Install ISIS:

conda install                 \
  -c usgs-astrogeology        \
  -c conda-forge              \
  --channel-priority flexible \
  isis

Flexible channel priority may be necessary for successful installation.

Save the current environment for reference as follows:

conda env export > isis.yaml

25.2.2. Build tools

We will create a new tools environment to have all the tools we will need. These could be appended to the earlier environment, but keeping them separate is less likely to cause dependency conflicts.

conda create -n tools
conda activate tools
conda install -c conda-forge anaconda-client conda-build

25.2.3. Build recipe

ASP has many dependencies that are source code, rather than pre-existing packages.

Producing a separate conda package for each turned out to be laborious, because conda is slow and fragile. The current approach is to build all these packages and ASP itself in a single script, available at

To reduce the chance of failures, the process is first tested by building these packages manually, using the same steps and environment as in the script.

That environment is produced by adding dependencies to the installed ISIS package.

The ASP version in this feedstock needs to be updated for each release.

Build command:

conda activate tools
conda config --set channel_priority flexible
conda build                    \
  -c nasa-ames-stereo-pipeline \
  -c usgs-astrogeology         \
  -c conda-forge               \
  stereopipeline-feedstock

The developers can upload the produced packages to the nasa-ames-stereo-pipeline channel.

After a package is uploaded, it can be installed in the desired environment as:

conda install                  \
  -c nasa-ames-stereo-pipeline \
  -c usgs-astrogeology         \
  -c conda-forge               \
  -n myEnv                     \
  myPackage=myVersion=myBuildNo

If this is slow, check if the solver is set to libmamba.

To list all packages in the channel, do:

conda search -c nasa-ames-stereo-pipeline --override-channels

To delete a package from this channel, run:

anaconda remove nasa-ames-stereo-pipeline/myPackage/myVersion

If adding an updated package with the same version, increment the build number. Otherwise the new package may be confused with a cached version of a prior build.

25.2.4. Helper scripts

The .github/workflows directory in the StereoPipeline repository has a few scripts that show in detail the commands that are run to build ASP daily in the cloud (macOS Intel, macOS ARM64, and Linux ARM64).

25.2.5. Building the documentation

The ASP documentation is written in ReStructured Text and is built with Sphinx and sphinxcontrib-bibtex.

See the online ASP documentation.

To build the documentation locally, install the required packages, for example:

conda create -n sphinx -c conda-forge sphinx sphinxcontrib-bibtex
conda activate sphinx

Note that we used a separate conda environment to minimize the chance of conflict with other dependencies.

The docs directory contains the root of the documentation. Running make html there will create the HTML version of the documentation in the _build subdirectory.

Building the PDF documentation is no longer supported.

If the documentation builds well locally but fails to update on the web, see the cloud build status page.

25.3. Releasing a new version of ASP

This section is for ASP maintainers.

25.3.1. Update the version number

Inside both the VisionWorkbench and ASP repositories, edit src/CMakeLists.txt and set the new version, which should be the same for both packages, and in the format x.y.z. If the value there is x.y.z-alpha, which is used to tag a pre-release, remove the -alpha part. Increment one of these digits, depending on whether this is a major, minor, or bugfix release. See https://semver.org for guidance.

25.3.2. Update the documentation

Search all documentation for the old version numbers for ASP and ISIS and replace them with the new version numbers. This includes files in the base directory, not just in docs.

Update NEWS.rst. Add the release date on top, along the lines of prior releases (see further down in that file). This file must have a detailed log of all changes, especially those that result in changed behavior or options, and it should be incrementally updated as changes are made during development.

Update the copyright year in the README.rst and docs/conf.py files.

25.3.3. Commit and tag

Commit all changes. Tag the release in both the VisionWorkbench and StereoPipeline repos. Example:

git tag <asp version>
git push origin <asp version> # commit to your branch
git push god    <asp version> # commit to main branch

(Here it is assumed that origin points to your own fork and god points to the parent repository.)

If more commits were made and it is desired to apply this tag to a different commit, first remove the existing tag with:

git tag -d <asp version>
git push origin :refs/tags/<asp version>
git push god    :refs/tags/<asp version>

25.3.4. Build ASP with conda

See Section 25.2.

25.3.5. Building self-contained binaries

In addition to creating a conda package, it is also convenient to ship a zipped package having all ASP tools and needed libraries (this includes the ISIS libraries but not the ISIS tools).

Such a build is created for each release and also daily. These are posted on the GitHub release page (Section 2.1).

ASP uses a custom build system. It can be downloaded with git from:

Create a conda environment that has the dependencies for building ASP, as described in Section 25.1. Assume it is called asp_deps.

Install the C, C++, and Fortran compilers (same versions as for ISIS), cmake>=3.15.5, pbzip2, parallel, and for Linux also the chrpath tool, as outlined on that page. The full list of dependencies is in the stereopipeline-feedstock repository (Section 25.2.3).

Go to the directory BinaryBuilder, and run:

/path/to/python3                                \
  ./build.py                                    \
  --cc <path to C compiler>                     \
  --cxx <path to C++ compiler>                  \
  --gfortran <path to Fortran compiler>         \
  --asp-deps-dir $HOME/miniconda3/envs/asp_deps \
  --build-root build_asp                        \
  --skip-tests                                  \
  visionworkbench stereopipeline

This will fetch and build the latest VisionWorkbench and Stereo Pipeline in build_asp/build, and will install them in build_asp/install.

See Section 25.2.4 for scripts illustrating this process.

25.3.6. Create a conda environment for the bundled Python

ISIS expects a full Python distribution to be shipped. Rather than ship the entire asp_deps environment, which is large, we create a small separate environment with only the modules that ASP’s Python tools need, and ship that. Letting conda build this self-contained mini environment, which is then archived with conda pack and bundled by make-dist.py, is more reliable than having the packaging script hunt for a standalone Python’s dependencies.

The needed modules are numpy, scipy, and gdal. The latter two are used by sparse_disp (Section 16.69). Use the same versions as in asp_deps. In particular, gdal must match, so its Python bindings agree with the shipped gdal library. Run, for example:

conda create -c conda-forge -n python_isis10 \
  python=3.13.13 numpy=2.4.6 scipy=1.17.1 gdal=3.12.2

Note that different versions may be needed for Linux and OSX. The conda list command within the asp_deps environment looks up the desired versions.

25.3.7. Package the build

Run in BinaryBuilder the command:

/path/to/python3                                  \
  ./make-dist.py build_asp/install                \
  --asp-deps-dir $HOME/miniconda3/envs/asp_deps   \
  --python-env $HOME/miniconda3/envs/python_isis10

Building and packaging should be done separately for each platform (Linux x86_64, Linux ARM64, macOS Intel, macOS ARM64).

25.3.8. Test ASP

The script auto_build/launch_master.sh in BinaryBuilder can be invoked to build and test ASP. This script and also auto_build/utils.sh need to be read carefully and some variables adjusted.

The StereoPipeline test suite is run. It has comprehensive tests for the ASP tools.

This functionality creates the daily builds, which are then uploaded to the GitHub release page (Section 2.1).

25.3.9. Prepare the documentation

Follow the instructions in Section 25.2.5.

25.3.10. Push the release to GitHub

Create a release on GitHub. Use the tag for the current release. Add to the release notes a link to the appropriate NEWS section of the documentation (Section 23). Only after this save the release.

Do not delete and recreate the release (Section 25.3.11). It is fine to upload the binaries after a release is created, and delete and re-upload them.

The GitHub gh program can be invoked to push the binaries to the release. Example:

cd BinaryBuilder/asp_tarballs
for file in                                                  \
  StereoPipeline-<asp version>-<date>-x86_64-Linux.tar.bz2   \
  StereoPipeline-<asp version>-<date>-aarch64-Linux.tar.bz2  \
  StereoPipeline-<asp version>-<date>-x86_64-OSX.tar.bz2     \
  StereoPipeline-<asp version>-<date>-arm64-OSX.tar.bz2; do

  gh release upload <asp version> $file \
    -R git@github.com:NeoGeographyToolkit/StereoPipeline.git
done

Alternatively, these can be uploaded from a web browser.

25.3.12. Announce the release

Send an announcement of the new release to the mailing list, with a link to the NEWS section for the current release from the documentation.

25.3.13. Post-release work

In anticipation of the next feature release, increment the version number in src/CMakeLists.txt in both the VisionWorkbench and ASP repositories, and append -alpha to it. See https://semver.org for guidance on versions.