Installation

cacao does not build on its own. It is a plugin of milk: the cacao sources are placed in milk/plugins/cacao-src/ and compiled as part of milk.

cacao targets Linux. It is built and tested on Ubuntu 24.04.

Prerequisites

On Ubuntu/Debian:

sudo apt-get install \
    git cmake make pkg-config gcc g++ gfortran \
    bison flex libbison-dev libfl-dev \
    libcfitsio-dev libgsl-dev libfftw3-dev libncurses-dev libreadline-dev \
    libopenblas-dev liblapacke-dev \
    python3-dev pybind11-dev python3-pybind11

This is the same list the repository’s Dockerfile installs, which CI builds on every change.

Optional:

• CUDA toolkit, for GPU computation (configure with -DUSE_CUDA=ON)

• MAGMA, for GPU linear algebra (-DUSE_MAGMA=ON, requires CUDA)

• Intel MKL, used instead of OpenBLAS when found by pkg-config (mkl-sdl)

• tmux, used by the cacao loop setup scripts

Build and install

git clone https://github.com/milk-org/milk.git
cd milk
git clone https://github.com/CaltechOpticalObservatories/cacao.git plugins/cacao-src

cmake -S . -B _build -DCMAKE_BUILD_TYPE=Release -DINSTALLMAKEDEFAULT=ON
cmake --build _build -j "$(nproc)"
sudo cmake --install _build

Important

Run cmake from the milk source root, as shown. milk finds plugins with a find plugins relative to the directory cmake is run from, so configuring from inside _build/ (cd _build; cmake .., which is what milk’s compile.sh does) silently builds milk without cacao.

milk installs to /usr/local/milk-<version>. -DINSTALLMAKEDEFAULT=ON also points the symlink /usr/local/milk at that version.

milk’s fetch_cacao_dev.sh script can clone cacao for you. By default it clones the upstream cacao-org/cacao dev branch. To use this fork instead:

CACAO_REPOSITORY=https://github.com/CaltechOpticalObservatories/cacao.git \
CACAO_BRANCH=dev \
./fetch_cacao_dev.sh

The script only clones when plugins/cacao-src does not exist. Otherwise it runs git pull in the existing checkout.

Environment

Add to ~/.bashrc (or equivalent):

export MILK_ROOT=$HOME/src/milk          # milk source directory (edit as needed)
export MILK_INSTALLDIR=/usr/local/milk
export PATH=${PATH}:${MILK_INSTALLDIR}/bin
export PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:${MILK_INSTALLDIR}/lib/pkgconfig

MILK_ROOT must be set. cacao-loop-deploy reads the example configurations from $MILK_ROOT/plugins/cacao-src.

Shared memory directory

Image streams and their semaphores are files in a shared-memory directory. The directory is chosen in this order:

1. $MILK_SHM_DIR, if it is set and exists

2. /milk/shm

3. /tmp

For real-time use, mount a tmpfs at /milk/shm:

sudo mkdir -p /milk/shm
echo "tmpfs /milk/shm tmpfs rw,nosuid,nodev" | sudo tee -a /etc/fstab
sudo mount /milk/shm

Docker

The repository’s Dockerfile builds milk with the cacao sources from the current checkout:

docker build -t cacao .
docker run --rm -it cacao

Build against a different milk branch with --build-arg MILK_REF=<branch>.

Check the installation

milk-check
cacao-loop-deploy -h