How to get started using the CMake build system

The following documentation gives a step-by-step introduction how to initially set up a SIFT development environment from scratch using the CMake-based build system.

The description is platform independent [1] but based on the usual Linux workflows. Experienced users may change single steps to better fit their workflows of course.

It is assumed that the reader knows how to install and initialize a Conda environment (refer to Python Package Installation otherwise) and how to get the SIFT sources from the Git repository or from an archive.

Bootstrapping

This procedure is (only) necessary as long as there is no Conda package uwsift-devel-deps available for the current platform. When the package is available you may skip this part and jump instead to For Developers and then continue with Building Conda and PyInstaller Packages.

Prerequisites

Only a few preparatory steps need to be done outside the build system.

It is assumed that a Conda system is installed and properly initialized for your shell [2]. Because it uses the quicker Mamba and sets up environments with the conda-forge repository as default channel the recommended system is Mambaforge, but also Miniforge3, Miniconda3 or Anaconda3 should work.

Install CMake and Make [3] into your base environment.

On Linux this step may be optional - if any of these tools is already available in your shell in a suitably recent version (CMake: version 3.14 at least) there is no need to install it into the base environment.

On Windows you should perform this step in any case, unless you know how to perform the following steps analogously using a different build system combination than CMake with “Unix Makefiles”.

%> conda install --name base cmake make

CMake-guided System Setup

Activate the base environment:

%> conda activate base

In the top-level directory of the SIFT sources run cmake with a generator for the chosen build system:

(base)%> cmake -G "Unix Makefiles" .

Then follow the advice given by the messages showing up. When doing so, a new Conda environment devel-<python version> (by default devel-3.10) [4] will be created and populated with all packages necessary for SIFT development and packaging:

(base)%> make devel-bootstrap

Please also execute the steps printed out at the end of building this meta-target devel-bootstrap [5]

Building Conda and PyInstaller Packages

If not already done, execute the steps:

(base)%> conda activate devel-3.10
(devel-3.10)%> conda config --env --add channels conda-forge
(devel-3.10)%> conda config --env --set channel_priority strict
(devel-3.10)%> cmake -G "Unix Makefiles" .

The system is now ready to create Conda and PyInstaller packages for SIFT. The according targets can be found in the target lists printed by running:

(devel-3.10)%> make help
 The following are some of the valid targets for this Makefile:
 [...]
 ... conda-packages
 ... pyinstaller-package
 [...]

Each of these package-targets can be build by running:

(devel-3.10)%> make <package-target>

The Target conda-packages

The target conda-packages creates three Conda packages: uwsift, uwsift-devel-deps and uwsift-deps.

Only uwsift and uwsift-devel-deps are meant to be directly installed from an appropriate Conda channel sift-channel [6]. However, the two packages should not be installed into the same Conda environment together.

The third one is a meta-package which only pulls common dependencies for two others and is automatically installed when any of them is installed. Please refer to Python Package Installation regarding how to install and use them.

The three Conda packages are created in a directory, by default ~/conda-channels/uwsift/ [7]. This directory is also indexed as a Conda repository thus it can be used as a local Conda channel in each Conda environment from which the path is accessible:

(MY_ENV)%> conda config --add channels ~/conda-channels/uwsift/

The target pyinstaller-package

Using this target you can create an executable which allow to run SIFT without any additional installation of dependencies. All dependencies are provided.

Footnotes

[1]

Tested on Linux and Windows at the time of writing.

[2]

Please refer to the according documentation.

[3]

You may use another build tool supported by CMake as e.g. Ninja or MSBuild.exe.

[4]

The name of the environment can be changed in the CMake configuring step.

[5]

Refer to the steps printed by CMake since they may differ from those listed in this document.

[6]

How to provide and populate such a Conda channel is not part of this documentation.

[7]

The path of the Conda packages directory of the environment can be changed in the CMake configuring step.