Environment Setup
This guide walks you through preparing your machine to build and develop ChronoLog. Choose the method that best fits your workflow:
- Build from Source
- Docker
Prerequisites
- Operating System: Linux (Ubuntu 20.04+, CentOS 7+, or equivalent)
- C++17 Compiler: GCC 9+ or Clang 10+
- Git: 2.x+
- Python: 3.6+ (required by Spack)
- Fortran compiler:
gfortran(see below)
Spack
ChronoLog requires various packages managed by Spack. Use Spack v1.2.2 (2026-07-20).
Spack needs a few system packages, among them a Fortran compiler: Spack builds py-scikit-build-core, a build dependency of py-pybind11, only when one is installed. On Debian or Ubuntu:
sudo apt install file bzip2 ca-certificates g++ gcc gfortran git gzip lsb-release patch python3 tar unzip xz-utils zstd
Clone Spack v1.2.2:
git clone --depth 1 --branch v1.2.2 https://github.com/spack/spack.git
Load Spack into your shell environment:
source /path-to-where-spack-was-cloned/spack/share/spack/setup-env.sh
Add the source command to your ~/.bashrc (or ~/.zshrc) so Spack is available in every new shell session.
ChronoLog 3.4.0 and older build with Spack v0.21.2, not v1.2.2: their spack.yaml pins versions that the recipes of v1.2.2 no longer have (concretizing fails on its cmake@3.25.1 ^openssl@3.0), and v0.21.2 cannot read the spack.yaml of 3.5.0. To build an older version, clone --branch v0.21.2 into another directory and source its setup-env.sh instead, including in ~/.bashrc if you put it there. 3.5.0 and older components cannot exchange RPCs, so do not mix the builds.
Checkout ChronoLog
Clone the ChronoLog repository:
git clone https://github.com/grc-iit/ChronoLog.git
Installing Dependencies
Enter the repository and check out the development branch:
cd ChronoLog
git checkout develop
The develop branch contains the latest in-progress work. Use main for the current stable release.
Activate the Spack environment defined in the repository:
spack env activate -p .
The repository's spack.yaml pins the package recipes to a commit of the releases/v2026.10 branch of spack-packages and takes Margo 0.24.4 from its own recipe in tools/spack/. Spack clones the pinned recipes into .spack-env/ the first time the environment is used, so that step needs network access.
Install all required dependencies:
spack install -v
Installation can take more than 30 minutes. All dependencies are defined in the repository's spack.yaml.
Verify the Environment
Confirm that Spack installed the dependencies and that CMake is available:
spack find
which cmake
spack find should list all installed packages. which cmake should point to the Spack-installed CMake inside the environment view.
IDE Setup (Optional)
CLion
- Open the
ChronoLogdirectory as a CMake project. - Go to Settings → Build, Execution, Deployment → CMake.
- Set CMake options to:
Alternatively, launch CLion from a terminal where the Spack environment is already activated — CLion will inherit the environment variables and find all dependencies automatically.
-DCMAKE_PREFIX_PATH=$(spack location -i cmake)/..
VS Code
- Install the CMake Tools extension.
- Open the
ChronoLogdirectory. - In
.vscode/settings.json, add:Or simply open VS Code from a terminal with the Spack environment activated.{
"cmake.configureArgs": [
"-DCMAKE_PREFIX_PATH=${env:SPACK_ENV}/.spack-env/view"
]
}
Prerequisites
Ensure Docker is installed and the Docker daemon is running:
docker --version
Pull the ChronoLog Dev Image
docker pull ghcr.io/grc-iit/chronolog-dev:develop
The image is automatically published on every push to the develop branch by the CI pipeline. It comes with:
- All Spack dependencies pre-installed
- A Debug build of ChronoLog compiled and installed at
/home/grc-iit/chronolog-install/chronolog - The full source tree at
/home/grc-iit/chronolog-src PATH,LD_LIBRARY_PATH, andCHRONOLOG_HOMEalready configured
No additional setup is required to start building or running.
Run the Container
docker run -it --rm ghcr.io/grc-iit/chronolog-dev:develop bash
This opens an interactive shell as the grc-iit user, starting in /home/grc-iit/chronolog-src with ChronoLog already built and installed.
Mount Local Source (Recommended for Active Development)
To develop with your own local edits — edit on the host, build inside the container — bind-mount your local ChronoLog checkout over the baked-in source:
docker run -it --rm \
-v $(pwd):/home/grc-iit/chronolog-src \
ghcr.io/grc-iit/chronolog-dev:develop bash
Run this from the root of your cloned ChronoLog repository. Your local changes are immediately visible inside the container. After editing, run the build and install scripts to apply them (see Building for Development).
Next Steps
Your environment is ready. Head to Building for Development for build, install, and run instructions.