Dependency management¶
Arbor relies on a (small) number of dependencies. We can distinguish three kinds of deps:
Source management dependencies: Git.
Build dependencies. E.g. CMake, compilers like GCC or CUDA.
Linking dependencies. E.g. MPI.
Source dependencies. These are present as git submodules or as copy in
ext/
. Their use is optional: users who need integration with their package manager (e.g. apt, spack, yum) can link to those versions instead.
Note that the actual dependencies of your build configuration may vary.
In addition, spack/package.py
contains a copy of the Spack package definition upstream. Here instructions for both in-repo and configure-time dependencies are defined.
This document contains rules for when and how to update dependencies, and what to be mindful of when you do.
List of dependencies¶
A full list of dependencies is maintained at doc/dependencies.csv
:
Build option/target |
Tool name |
Minimum version |
Notes |
Update criteria |
---|---|---|---|---|
– |
CMake |
3.19 |
|
|
– |
C++ compiler |
C++17 support. See below |
||
– |
GCC |
9.0.0 |
|
|
– |
Clang |
10.0 |
Needs GCC 9 or later for standard library. |
|
– |
Apple Clang |
11 |
Apple LLVM version 11.0.0 (clang-1100.0.33.8) |
|
ARB_GPU |
Hip Clang |
ROCm 3.9 |
HIP support is currently experimental. |
|
ARB_GPU |
CUDA |
11.0 |
|
|
ARB_WITH_MPI |
MPI |
Many MPI implementations are supported. |
||
ARB_WITH_MPI, ARB_WITH_PYTHON |
mpi4py |
3.1.0 |
Minimum version depends on compatiblity with your Python and MPI versions. 3.1.0 is the first release to support Python > 3.8. |
|
html |
sphinx>=2.4.0
svgwrite
docutils >= 0.17
|
See |
||
unit |
googletest |
1.12.1 |
submodule |
|
bench |
Google-benchmark |
submodule |
||
– |
json |
3.11.2 |
submodule |
|
– |
pugi |
1.13 |
submodule |
|
– |
random123 |
1.14.0 |
submodule |
|
– |
fmt |
10.0.0 |
submodule |
|
– |
tinyopt |
source copy |
||
ARB_WITH_PYTHON |
pybind11 |
2.10.1 |
submodule |
|
ARB_WITH_PYTHON |
Python |
3.8 |
Python compatiblity is the range between the latest officially released point version and the minimum here specified. |
|
Note
CMake can generate an overview of the dependency tree. Run the following in the build dir:
cmake --graphviz=graphviz/arbor-dep-graph.dot . && dot graphviz/arbor-dep-graph.dot -T png -o graphviz/arbor-dep-graph.png
This plot can be tweaked with the CMakeGraphVizOptions.cmake
file in the root of the project, which currently excludes tests, the lmorpho
morphology generator and all C++ examples.
User platforms¶
Although Arbor should in principle run everywhere modern compilers are found, a couple of user platforms are essential. These environments must be able to build Arbor without issue, if not we consider this a bug. Also, build instructions for each of them must be given in the documentation.
Dependency update rules¶
doc/dependencies.csv
, git submodules andspack/package.py
shall be in sync.Dependencies shall be set to a (commit hash corresponding to a) specific version tag. (All current dependencies use semver.)
The version shall be compatible with the user platforms (see above).
The version shall be compatible with the requirements in
doc/dependencies.csv
.The version shall be the lowest possible, to facilitate building of complex environments.
The submodule shall be set to the highest version provided by the latest Spack release (“Spack stable”). Spack CI tests both Spack stable and develop.
Moreover, dependencies shall not be updated past the most recent version of the dependency in Spack.
This prevents Spack builds from pulling in
master
, when a more recent version than available is required. See here.This is a manual check, e.g. for pybind: see pybind package.py
Actually updating shall remain a manual process. Update may require nontrivial updates to Arbor, and updates to Spack upstream (e.g. make PR for pybind update).
A dependency update shall have a separate PR, and such a PR updates a single dependency at a time, unless the dependency update requires other dependencies to be updated.
This PR requires review by at least two reviewers.
There appears to be no way to enforce that, unless we enforce it for all PRs.
Optionally we could have a PR template auto-assigning to some or all of us, which means we’ll at least be notified.
We will try to keep compatible to a wide range in dependency versions.
This includes making other components in ext git submodules, such that updates are more easily tracked.