Fermitools

This meta-package of the user-facing Fermitools employs git submodules to link to component packages. A git submodule is another git repository which is linked to by this repo.

To also fetch these submodules on clone run: git clone --recurse-submodules https://github.com/fermi-lat/ScienceTools.git

If you have cloned the top level repo already you can also grab all the repositories with: git submodule update --init .

Building the tools

The Fermitools has moved to using CMAKE for its build system. When paired with conda for dependency package management this provides robust and well-supported system for cross-compliling the tools on differing host and target systems.

Requirements

With a fully set up conda installation you can install the needed development dependencies for your operating system from the provided conda environment files in environments/.

For example on linux:

conda env create -n fermi-dev -f environments/fermitools-develop-linux.yml
conda activate fermi-dev

Build-only dependencies.

System specific environment files also exist for just building the tools, but neither running nor testing them once built.

conda env create -n fermi-build -f environments/fermitools-build-linux-x86.yml
conda activate fermi-build

MacOS: If you are building the Fermitools on a MacOS machine you will need to install llvm via Homebrew if you have not done so already with the command

brew install llvm

Generating dependency environment files.

A new environment file candidate can be created from the command line. I say candidate because the YAML needs to me modified to actually be installable. You need to remove the 'prefix:' seciton and probably add a '-fermi' to the channel list.

conda env export -n fermi-build --from-history >  environments/fermitools-build.yml

CMake Builds

The build process is split into two steps. Generation is similar to a configure step; The host system is polled for needed attributes, programs, and libraries and a Makefile system is created. The Build stage then executes the generated Makefile system to compile all the Fermitools targets.

Assuming your dependencies are installed you can generate a build system by executing the following command from within the ScienceTools directory:

cmake -S . \
-B RelWithDebInfo \
-DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_TOOLCHAIN_FILE=cmake/<os>-toolchain.cmake \
-DCMAKE_INSTALL_PREFIX="</install/destination/path>" \
-DCMAKE_PREFIX_PATH="</dependency/search/path/>"

where <os> is either linux or macos, depending on what operating system you are building the tools on.

If your CMAKE_INSTALL_PREFIX is the location of your dependencies you can optionally exclude CMAKE_PREFIX_PATH.

This locates needed dependencies and prepares a release build with debug symbols in the 'RelWithDebInfo' directory. To compile the system now run:

cmake --build RelWithDebInfo --parallel

Optionally you can install the tools in your CMAKE_INSTALL_PREFIX with

cmake --build RelWithDebInfo --parallel --target=install

Shell Environment Setup.

The Fermitools relies on a properly setup shell environment to populate needed path information for certain directories. In a conda build this is handled by the activate function, but as a developer working without conda you can instead you the provided scripts/activate.sh. Simply source that file with the argument for your cmake build directory like so:

source scripts/activate.sh RelWithDebInfo

Conda Builds

The sibling repository for this package is https://github.com/fermi-lat/Fermitools-conda

Once checked out it can be used to trigger a conda build with conda build

Tips for Git Submodules

To run a branch and some parallel clone jobs run something like: git clone -b branchname --recurse-submodules -j8 [email protected]:fermi-lat/ScienceTools.git

The metadata for the included submodules is found in the top level .gitmodules file.

The operate on all the submodules as a group, use the git submodule foreach command.

Examples:

1. Checkout a branch or recover from a detached head: git submodule foreach 'git checkout branchname ||:'
2. Add a commit: git submodule foreach 'git checkout branchname ||:'
3. Switch to ssh protocol: git submodule foreach 'git remote -v set-url origin [email protected]:fermi-lat/$(basename $(pwd)).git ||:'
4. Submodule update alias git config alias.supdate 'submodule update --remote --merge'
5. Submodule Push alias git config alias.spush 'push --recurse-submodules=on-demand'