README

*************************************************************************
1. INTRODUCTION

A. Stereo Pipeline

The NASA Ames Stereo Pipeline (ASP) is a suite of free and open source
automated geodesy and stereogrammetry tools designed for processing
planetary and Earth imagery captured from satellites and robotic
rovers. It produces cartographic products, including digital elevation
models (DEMs), ortho-projected imagery, and 3D models. These data
products are suitable for science analysis, mission planning, and
public outreach.

B. Binary Builder

The Binary Builder is a collection of scripts for building the release
binaries for the NASA Ames Stereo Pipeline (ASP). Binary Builder
downloads and builds all dependencies of ASP including the
dependencies of Vision Workbench and USGS's Integrated Software for
Imagers and Spectrometers (ISIS).

Building release binaries is a very difficult and fragile
process. Never can we guarantee that this code works as it will break
on changes made by our dependencies. This code will break on server
URL changes, build system changes, and just generally unsupported
environments. You use this software at your own risk.

************************************************************************
2. LICENSE

A. Copyright and License Summary

Copyright (c) 2009-2012, United States Government as represented by
the Administrator of the National Aeronautics and Space
Administration. All rights reserved.

ASP is licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You
may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.

************************************************************************
3. DOCUMENTATION

A. Produce a Complete Binary Build

All the ASP dependencies can be fetched with conda. If necessary, conda
can also be used to rebuild them. This is described at

  https://stereopipeline.readthedocs.io/en/latest/building_asp.html

Then, VisionWorkbench and Stereo Pipeline can be built either as
described there, or using the the scripts in this repository. 
The last step will be packaging the build, which is described later
in this section.

Building VisionWorkbench and Stereo Pipeline using build.py
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Having installed the asp_deps conda environment per the above
documentation, clone this repository and set up the environment:

    cd $HOME 
    mkdir projects
    cd projects
    git clone https://github.com/NeoGeographyToolkit/BinaryBuilder.git
    cd BinaryBuilder
    conda activate asp_deps

Build using the command:

    /path/to/python3                                \
      ./build.py                                    \
      --cc <path to C comipler>                     \
      --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

The most-up-to-date documentation for building ASP is in:

  https://stereopipeline.readthedocs.io/en/latest/building_asp.html

Due to the amount of code that must be downloaded and built,
BinaryBuilder will take quite a while to finish.  If you see the
message "All done!" then it has succeeded.  Otherwise something has
gone wrong and must be fixed before the build can continue.

If the build failed and you need to restart it after finding a fix,
the name of the individual package that needs to be built can be
passed to ``build.py`` as an argument. Note that this tool keeps track of
built packages in::

    build_asp/done.txt

so to force one to rebuild one can remove its entry from there.

Packaging the build
~~~~~~~~~~~~~~~~~~~

Once the build is successful you should make a distribution tarball to
store the completed build. 

ASP has to ship a full Python runtime which ISIS depends on. That has
to be prepared before the build is packaged. How to do that is
explained in:

    https://stereopipeline.readthedocs.io/en/latest/building_asp.html

Then package the build by running from the BinaryBuilder directory::

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

If the conda packages were installed in a location other than
``$HOME/miniconda3/envs/asp_deps``, the path to that directory should be
set via ``--asp-deps-dir``.

The files to be shipped as part of the distribution should be listed
in the file named ``whitelist``.

For packaging to succeed on Linux, the additional tool named
``chrpath`` is needed, which can be installed in your conda
environment with the command::

    conda install -c conda-forge chrpath

We strongly encourage you to read the output from ./build.py --help and
./make-dist.py --help. There are more features not talked about here.

B. Produce a VW only build

BinaryBuilder now supports the option to build only for Vision Workbench,
saving the time of building the extensive libraries needed only for ASP.
These options work similarly to the ASP methods described above.

For a complete VW build, run build.py with the argument: --build-goal 2

For a VW only development environment, run build.py with the argument: --build-goal 3

Other than using these flag values you can use the make-dist.py and
deploy-base.py tools in the same manner as if building ASP.

Nightly regressions
~~~~~~~~~~~~~~~~~~~

See auto_build/README

************************************************************************
4. ADDITIONAL BUILD OPTIONS

The list of packages that were already built is stored in
<build-root>/done.txt (default: ./build_asp/done.txt). On each line is
the package name and the hash tag for that package. To force a package
to be rebuilt, remove its entry from the list. A package will be
rebuilt in either case if the hash tag changes.

To avoid building a package even if it was not built yet, invoke
build.py with the option _<package name>, i.e., ./build.py _isis.