Developer Guide¶
Generating CHAI host-config files¶
This mechanism will generate a cmake configuration file that reproduces the configuration Spack <https://github.com/spack/spack> would have generated in the same context. It will contain all the information necessary to build CHAI with the described toolchain.
In particular, the host config file will setup: * flags corresponding with the target required (Release, Debug). * compilers path, and other toolkits (cuda if required), etc. * paths to installed dependencies.
This provides an easy way to build CHAI based on Spack <https://github.com/spack/spack> itself driven by Uberenv.
Uberenv role¶
Uberenv helps by doing the following:
- Pulls a blessed version of Spack locally
- If you are on a known operating system (like TOSS3), we have defined compilers and system packages so you don’t have to rebuild the world (CMake typically in CHAI).
- Overrides CHAI Spack packages with the local one if it exists. (see
scripts/uberenv/packages
). - Covers both dependencies and project build in one command.
Uberenv will create a directory uberenv_libs
containing a Spack instance with the required CHAI dependencies installed. It then generates a host-config file (<config_dependent_name>.cmake
) at the root of CHAI repository.
Using Uberenv to generate the host-config file¶
$ python scripts/uberenv/uberenv.py
Note
On LC machines, it is good practice to do the build step in parallel on a compute node. Here is an example command: srun -ppdebug -N1 --exclusive python scripts/uberenv/uberenv.py
Unless otherwise specified Spack will default to a compiler. It is recommended to specify which compiler to use: add the compiler spec to the --spec
Uberenv command line option.
On blessed systems, compiler specs can be found in the Spack compiler files in our repository: scripts/uberenv/spack_configs/<System type>/compilers.yaml
.
Some examples uberenv options:
--spec=%clang@4.0.0
--spec=%clang@4.0.0+cuda
--prefix=<Path to uberenv build directory (defaults to ./uberenv_libs)>
It is also possible to use the CI script outside of CI:
$ SPEC="%clang@9.0.0 +cuda" scripts/gitlab/build_and_test.sh --deps-only
Building dependencies can take a long time. If you already have a Spack instance you would like to reuse (in supplement of the local one managed by Uberenv), you can do so changing the uberenv command as follow:
$ python scripts/uberenv/uberenv.py --upstream=<path_to_my_spack>/opt/spack
Using host-config files to build CHAI¶
When a host-config file exists for the desired machine and toolchain, it can easily be used in the CMake build process:
$ mkdir build && cd build
$ cmake -C <path_to>/lassen-blueos_3_ppc64le_ib_p9-clang@9.0.0.cmake ..
$ cmake --build -j .
$ ctest --output-on-failure -T test
It is also possible to use the CI script outside of CI:
$ HOST_CONFIG=<path_to>/<host-config>.cmake scripts/gitlab/build_and_test.sh
Testing new dependencies versions¶
CHAI depends on Umpire, and optionally RAJA. Testing with newer versions of both is made straightforward with Uberenv and Spack:
$ python scripts/uberenv/uberenv.py --spec=%clang@9.0.0 ^umpire@develop
$ python scripts/uberenv/uberenv.py --spec=%clang@9.0.0+raja ^raja@develop
Those commands will install respectively umpire@develop and raja@develop locally, and generate host-config files with the corresponding paths.
Again, the CI script can be used directly to install, build and test in one command:
$ SPEC="%clang@9.0.0 ^umpire@develop" scripts/gitlab/build_and_test.sh