# Developer Installation

Here we will discuss several specific system configurations that are
known to work. The best one for you will depend on your OS and
preferences.

## Ubuntu Linux

You can install all but one required TOAST dependency using packages
provided by the OS. Note that this assumes a recent version of ubuntu
(tested on 19.04):

    apt update
    apt install \
        cmake \
        build-essential \
        gfortran \
        libopenblas-dev \
        libmpich-dev \
        liblapack-dev \
        libfftw3-dev \
        libsuitesparse-dev \
        python3-dev \
        libpython3-dev \
        python3-scipy \
        python3-matplotlib \
        python3-healpy \
        python3-astropy \
        python3-pyephem

NOTE: if you are using another package on your system that requires
OpenMPI, then you may get a conflict installing libmpich-dev. In that
case, just install libopenmpi-dev instead.

Next, download a [release of
libaatm](https://github.com/hpc4cmb/libaatm/releases) and install it.
For example:

    cd libaatm
    mkdir build
    cd build
    cmake \
        -DCMAKE_INSTALL_PREFIX=/usr/local \
        ..
    make -j 4
    sudo make install

You can also install it to the same prefix as TOAST or to a separate
location for just the TOAST dependencies. If you install it somewhere
other than /usr/local then make sure it is in your environment search
paths (see the \"installing TOAST\" section).

You can also now install the optional dependencies if you wish:

> -   [libconviqt](https://github.com/hpc4cmb/libconviqt) for 4PI beam
>     convolution.
> -   [libmadam](https://github.com/hpc4cmb/libmadam) for optimized
>     destriping mapmaking.

## Other Linux

If you have a different distro or an older version of Ubuntu, you should
try to install at least these packages with your OS package manager:

    gcc
    g++
    mpich or openmpi
    lapack
    fftw
    suitesparse
    python3
    python3 development library (e.g. libpython3-dev)
    virtualenv (e.g. python3-virtualenv)

Then you can create a python3 virtualenv, activate it, and then use pip
to install these packages:

    pip install \
        numpy \
        scipy \
        matplotlib \
        healpy \
        astropy \
        pyephem \
        mpi4py

Then install libaatm as discussed in the previous section.

## OS X with MacPorts

```{admonition} To-Do
Document using macports to get gcc and installing optional dependencies.
```

## OS X with Homebrew

```{admonition} To-Do
Document installing compiled dependencies and using a virtualenv.
```

## Custom Install with CMBENV

The [cmbenv package](https://github.com/hpc4cmb/cmbenv) can generate an
install script that selectively compiles packages using specified
compilers. This allows you to \"pick and choose\" what packages are
installed from the OS versus being built from source. See the example
configs in that package and the README. For example, there is an
\"ubuntu-21.04\" config that gets everything from OS packages but also
compiles the optional dependencies like libconviqt and libmadam.

## Installing TOAST with CMake

Decide where you want to install your development copy of TOAST. I
recommend picking a standalone directory somewhere. For this example, we
will use `${HOME}/software/toast`. This should **NOT** be the same
location as your git checkout.

We want to define a small shell function that will load this directory
into our environment. You can put this function in your shell resource
file (`~/.bashrc` or `~/.profile`):

    load_toast () {
        dir="${HOME}/software/toast"
        export PATH="${dir}/bin:${PATH}"
        export CPATH="${dir}/include:${CPATH}"
        export LIBRARY_PATH="${dir}/lib:${LIBRARY_PATH}"
        export LD_LIBRARY_PATH="${dir}/lib:${LD_LIBRARY_PATH}"
        pysite=$(python3 --version 2>&1 | awk '{print $2}' | sed -e "s#\(.*\)\.\(.*\)\..*#\1.\2#")
        export PYTHONPATH="${dir}/lib/python${pysite}/site-packages:${PYTHONPATH}"
    }

When installing dependencies, you may have chosen to install libaatm,
libconviqt, and libmadam into this same location. If so, load this
location into your search paths now, before installing TOAST:

    load_toast

TOAST uses CMake to configure, build, and install both the compiled code
and the python tools. Within the `toast` git checkout, run the following
commands:

    mkdir -p build && cd build
    cmake -DCMAKE_INSTALL_PREFIX=$HOME/software/toast ..
    make -j 2 install

This will compile and install TOAST in the folder `~/software/toast`.
Now, every time you want to use toast, just call the shell function:

    load_toast

If you need to customize the way TOAST gets compiled, the following
variables can be defined in the invocation to `cmake` using the `-D`
flag:

`CMAKE_INSTALL_PREFIX`

:   Location where TOAST will be installed. (We used it in the example
    above.)

`CMAKE_C_COMPILER`

:   Path to the C compiler

`CMAKE_C_FLAGS`

:   Flags to be passed to the C compiler (e.g., `-O3`)

`CMAKE_CXX_COMPILER`

:   Path to the C++ compiler

`CMAKE_CXX_FLAGS`

:   Flags to be passed to the C++ compiler

`PYTHON_EXECUTABLE`

:   Path to the Python interpreter

`BLAS_LIBRARIES`

:   Full path to the BLAS dynamical library

`LAPACK_LIBRARIES`

:   Full path to the LAPACK dynamical library

`FFTW_ROOT`

:   The install prefix of the FFTW package

`AATM_ROOT`

:   The install prefix of the libaatm package

`SUITESPARSE_INCLUDE_DIR_HINTS`

:   The include directory for SuiteSparse headers

`SUITESPARSE_LIBRARY_DIR_HINTS`

:   The directory containing SuiteSparse libraries

See the top-level \"platforms\" directory for other examples of running
CMake.

## Installing TOAST with Pip / setup.py

The setup.py that comes with TOAST is just a wrapper around the cmake
build system. You can pass options to the underlying cmake call by
setting environment variables prefixed with \"TOAST\_BUILD\_\". For
example, if you want to pass the location of the libaatm installation to
cmake when using setup.py, you can set the \"TOAST\_BUILD\_AATM\_ROOT\"
environment variable. This will get translated to \"-DAATM\_ROOT\" when
cmake is invoked by setup.py