Developing a single package

For quick modifications, such as updating a single package, you can source the stack from cvmfs, compile a local version of the selected package, and export specific environment variables to ensure the local package is used instead of the one from cvmfs.

Building a local version

All Key4hep software packages can be built using cmake. The minimal way to do this at the top level of the package directory:

cmake -B build -S . -DCMAKE_INSTALL_PREFIX=./install
cmake --build build --target install

This assumes that you don’t need to pass any additional configuration arguments to cmake. It will also install the results into ./install, which is the conventional place in Key4hep.

If you want to check whether your local version of the package still passes all tests, you can run:

ctest --test-dir build

Building with multiple processes can either be done simply by passing -G Ninja to the first cmake command, or via passing -- -j<N> to the cmake --build command at the very end (replace <N> by the number of processes you want).

Adapt the environment with k4_local_repo

k4_local_repo is a helper command to simplify setting up the environment for single package development. This command becomes available immediately after sourcing the environment. To use it, navigate to the root directory of the package you want to develop and execute the command:

k4_local_repo [<install_location>]

where, <install_location> refers to the directory where the package will be installed. If not specified, the default ./install/ directory is assumed. This should match the location specified during cmake configuration with -DCMAKE_INSTALL_PREFIX=<install_location>.

Afterwards, the environment will be updated to automatically pick up the installed package.

When working with multiple local packages it might be beneficial to write a helper script to execute k4_local_repo for each locally developed package.

Adapt the environment manually

While the k4_local_repo is the preferred method, it’s also possible to set up the environment variables manually. To do so, execute the following commands:

export PATH=<install_location>/bin:$PATH
export LD_LIBRARY_PATH=<install_location>/lib:<install_location>/lib64:$LD_LIBRARY_PATH
export ROOT_INCLUDE_PATH=<install_location>/include:$ROOT_INCLUDE_PATH
export PYTHONPATH=<install_location>/python:$PYTHONPATH

where <install_location> should match the install location specified during cmake configuration with -DCMAKE_INSTALL_PREFIX=<install_location>. It’s possible some packages may require specifying some extra environmental variables beside these, for example replacing some libraries with local libraries in MARLIN_DLL if needed.

While this approach works and any number of packages can be built this way, it is cumbersome and error-prone to do so for many packages. In such cases using k4_local_repo is strongly recommended.