docs: Add documentation on Spack builds (#3550)

This commit adds a new section to the "getting started" section of the documentation detailing how Spack can be used to install the dependencies of ACTS.

docs/getting_started.md

@@ -184,9 +184,11 @@ container $ cmake --build build
 ### On your local machine
 
 Building and running ACTS on your local machine is not officially supported.
-However, if you have the necessary prerequisites installed it is possible to use
-it locally. ACTS developers regularly use different Linux distributions
-and macOS to build and develop ACTS.
+However, if you have the necessary prerequisites installed it is possible to
+use it locally. ACTS developers regularly use different Linux distributions and
+macOS to build and develop ACTS. It is possible to use Spack to more easily
+install ACTS' dependencies; see the [building with Spack](misc/spack) page for
+more information.
 
 (build_docs)=
 ## Building the documentation

docs/index.rst

@@ -38,6 +38,7 @@ Key features:
    versioning
    formats/formats
    codeguide
+   misc/misc
    authors
    license
 

docs/misc/misc.rst

@@ -0,0 +1,10 @@
+Miscellaneous topics
+====================
+
+This section of the documentation covers miscellaneous topics which do not fit
+elsewhere, but which may still prove useful to the reader.
+
+.. toctree::
+   :maxdepth: 1
+
+   spack

docs/misc/spack.md

@@ -0,0 +1,68 @@
+# Building with Spack
+
+[Spack](https://spack.io/) is a package manager designed to handle software
+used in scientific computing, including computing in high-energy physics. The
+Spack package manager can be used to more easily install ACTS' dependencies.
+Builds using Spack are not officially supported. In order to start using Spack,
+follow the instructions on the [official Spack
+documentation](https://spack.readthedocs.io/en/latest/getting_started.html).
+
+## Installing dependencies
+
+Once Spack has been installed, we are ready to create a development
+environment; for example:
+
+```console
+$ spack env create acts
+```
+
+This new environment can then be activated and deactivated as follows:
+
+```console
+$ spack env activate acts
+$ despacktivate
+```
+
+:::{tip}
+The creation of a Spack environment is persistent, i.e. you should only need to
+create your environment once. The activation of the environment, on the other
+hand, affects only your current shell. As a result, you will need to activate
+the environment every time you open a new shell.
+:::
+
+With the Spack environment activated, you are ready to install ACTS'
+dependencies. You can either do this manually, or you can rely on Spack's
+definition of how to do this. To use the Spack definition, execute the
+following command (tuned for ACTS version 36.1.0):
+
+```console
+$ spack install --add --only dependencies "[email protected]+tgeo+geomodel+podio+edm4hep+examples+odd+fatras+json+dd4hep+geant4+fatras_geant4+hepmc3+pythia8+python+svg+traccc"
+```
+
+The string starting with `acts` in the command above is the so-called _spec_,
+and it consists of three parts. The first part is the name of the package,
+which is `acts`. The second part is the version of the package, in this case
+`36.1.0`; Spack will pull in a set of dependencies suitable for that given
+version, so it is recommended to tune the version number to match the version
+of ACTS you want to build. The final part is a series of variants, marked with
+the `+` symbol. The command above allows you to build virtually all components
+of ACTS, but it also pulls in a large number of dependencies. You can
+optionally remove variants you do not need in order to speed up the Spack
+build.
+
+Once Spack has concretized and installed the ACTS dependencies, you can build
+ACTS as normal using CMake.
+
+
+## Build caches
+
+Work on build caches for ACTS is in progress.
+
+## Support
+
+Spack support is experimental and not officially supported. Because ACTS'
+dependencies are constantly changing, it is possible that Spack's database may
+at times be out of date. If you encounter any problems using Spack to build
+ACTS, unofficial support is available in the
+[#Spack](https://mattermost.web.cern.ch/acts/channels/spack) channel on the
+ACTS Mattermost.