SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs/Installation - Installation.md Hit Total Coverage
Commit: 3c2e9d3ed337bca2146eee9de07432e292a38c3a Lines: 0 1 0.0 %
Date: 2024-06-11 22:56:19
Legend: Lines: hit not hit

          Line data    Source code
       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : # Installation {#installation}
       6             : 
       7             : \tableofcontents
       8             : 
       9             : This page details the installation procedure for SpECTRE on personal computers
      10             : using x86-64 processors. For instructions on installing SpECTRE on clusters
      11             : please refer to the \subpage installation_on_clusters page. For instructions on
      12             : installing SpECTRE on Apple Silicon Macs, please refer to the
      13             : \subpage installation_on_apple_silicon page. Refer to the
      14             : \subpage versioning_and_releases page for information on specific versions
      15             : to install.
      16             : 
      17             : ### Install a specific version with Spack
      18             : 
      19             : You can install SpECTRE with the [Spack](https://github.com/spack/spack) package
      20             : manager:
      21             : 
      22             : ```sh
      23             : git clone https://github.com/spack/spack
      24             : source ./spack/share/spack/setup-env.sh
      25             : spack compiler find
      26             : spack external find
      27             : spack install spectre executables=ExportCoordinates3D \
      28             :   ^charmpp backend=multicore
      29             : ```
      30             : 
      31             : You probably want to customize your installation, e.g., to select a particular
      32             : version of SpECTRE, the executables you want to install, additional options such
      33             : as Python bindings, or the Charm++ backend. You can display all possible options
      34             : with:
      35             : 
      36             : ```sh
      37             : spack info spectre  # or charmpp, etc.
      38             : ```
      39             : 
      40             : Refer to the [Spack documentation](https://spack.readthedocs.io/en/latest/) for
      41             : more information.
      42             : 
      43             : ### Quick-start guide for code development with Docker and Visual Studio Code
      44             : 
      45             : If you're new to writing code for SpECTRE and would like to jump right into a
      46             : working development environment, a good place to start is our
      47             : \subpage dev_guide_quick_start_docker_vscode. If you prefer setting up your
      48             : development environment differently, read on!
      49             : 
      50             : ### Dependencies
      51             : 
      52             : **Note**: You don't need to install any of these dependencies by hand,
      53             : or by using yum, apt, or other package managers; it is much easier
      54             : to instead use Singularity, Docker, or Spack (see the corresponding
      55             : sections below) to obtain an environment that includes
      56             : all of these dependencies.
      57             : 
      58             : #### Required:
      59             : 
      60             : * [GCC](https://gcc.gnu.org/) 9.1 or later,
      61             : [Clang](https://clang.llvm.org/) 13.0 or later (see
      62             : [here](https://apt.llvm.org/) for how to get newer versions of clang through
      63             : apt), or AppleClang 13.0.0 or later
      64             : * [CMake](https://cmake.org/) 3.18.0 or later
      65             : * [Charm++](http://charm.cs.illinois.edu/) 7.0.0, or later (experimental)
      66             :   \cite Charmpp1 \cite Charmpp2 \cite Charmpp3
      67             : * [Git](https://git-scm.com/)
      68             : * BLAS (e.g. [OpenBLAS](http://www.openblas.net))
      69             : * [Blaze](https://bitbucket.org/blaze-lib/blaze/overview) v3.8. It can be
      70             :   beneficial to install Blaze with CMake so some configuration options are
      71             :   determined automatically, such as cache sizes. \cite Blaze1 \cite Blaze2
      72             : * [Boost](http://www.boost.org/) 1.60.0 or later
      73             : * [Catch2](https://github.com/catchorg/Catch2) 3.4.0 or later. Install from your
      74             :   package manager or do a standard CMake build and installation (as detailed
      75             :   in the [Catch2 docs](https://github.com/catchorg/Catch2/blob/devel/docs/cmake-integration.md#installing-catch2-from-git-repository)).
      76             :   Compile with `CMAKE_POSITION_INDEPENDENT_CODE=ON`.
      77             : * [GSL](https://www.gnu.org/software/gsl/) \cite Gsl
      78             : * [HDF5](https://support.hdfgroup.org/HDF5/) (non-mpi version on macOS)
      79             :   \cite Hdf5
      80             : * [jemalloc](https://github.com/jemalloc/jemalloc)
      81             : * LAPACK
      82             : * [LIBXSMM](https://github.com/hfp/libxsmm) version 1.16.1 or later
      83             :   \cite Libxsmm
      84             : * [yaml-cpp](https://github.com/jbeder/yaml-cpp) version 0.6.3 or later.
      85             :   Building with shared library support is also recommended. \cite Yamlcpp
      86             : * [Python](https://www.python.org/) 3.8 or later.
      87             : * Python dependencies listed in `support/Python/requirements.txt`.
      88             :   Install with `pip3 install -r support/Python/requirements.txt`.
      89             :   Make sure you are working in a [Python venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
      90             :   before installing packages.
      91             :   Alternatively, you can set `BOOTSTRAP_PY_DEPS=ON` when configuring a build
      92             :   with CMake to install missing Python packages into the build directory
      93             :   automatically.
      94             :   <details>
      95             :   \include support/Python/requirements.txt
      96             :   </details>
      97             : 
      98             : #### Optional:
      99             : * [Pybind11](https://pybind11.readthedocs.io) 2.6.0 or later for SpECTRE Python
     100             :   bindings \cite Pybind11
     101             : * [Doxygen](https://www.doxygen.nl/index.html) 1.9.1 to 1.9.6 — to
     102             :   generate documentation
     103             : * Python dev dependencies listed in `support/Python/dev_requirements.txt`
     104             :   — for documentation pre- and post-processing, formatting code, etc.
     105             :   Install with `pip3 install -r support/Python/dev_requirements.txt`.
     106             :   Make sure you are working in a [Python venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
     107             :   before installing packages.
     108             :   <details>
     109             :   \include support/Python/dev_requirements.txt
     110             :   </details>
     111             : * [Google Benchmark](https://github.com/google/benchmark) - to do
     112             :   microbenchmarking inside the SpECTRE framework. v1.2 or newer is required
     113             : * [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) and
     114             :   [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) — to check code test
     115             :   coverage
     116             : * [PAPI](http://icl.utk.edu/papi/) — to access hardware performance counters
     117             : * [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) — to format C++
     118             :   code in a clear and consistent fashion
     119             : * [Clang-Tidy](http://clang.llvm.org/extra/clang-tidy/) — to "lint" C++ code
     120             : * [Scotch](https://gitlab.inria.fr/scotch/scotch) - to build the `ScotchLB`
     121             :   graph partition based load balancer in charm++.
     122             : * [ffmpeg](https://www.ffmpeg.org/) - for animating 1d simulations with
     123             :   matplotlib
     124             : * [xsimd](https://github.com/xtensor-stack/xsimd) 11.0.1 or newer - for manual
     125             :   vectorization
     126             : * [libbacktrace](https://github.com/ianlancetaylor/libbacktrace) - to show
     127             :   source files and line numbers in backtraces of errors and asserts. Available
     128             :   by default on many systems, so you may not have to install it at all. The
     129             :   CMake configuration will tell you if you have libbacktrace installed.
     130             : * [ParaView](https://www.paraview.org/) - for visualization \cite Paraview1
     131             :   \cite Paraview2 . Make sure your ParaView installation uses the same (major
     132             :   and minor) version of Python as the rest of the build.
     133             : * [SpEC](https://www.black-holes.org/code/SpEC.html) - to load SpEC data.
     134             :   Compile the exporter in SpEC's `Support/ApplyObservers/Exporter/` directory
     135             :   (see the `Makefile` in that directory). Also make sure to compile SpEC with
     136             :   the same compiler and MPI as SpECTRE to avoid compatibility issues.
     137             : 
     138             : #### Bundled:
     139             : * [Brigand](https://github.com/edouarda/brigand)
     140             : * [libsharp](https://github.com/Libsharp/libsharp)
     141             : 
     142             : ## Clone the SpECTRE repository
     143             : 
     144             : First, clone the [SpECTRE repository](https://github.com/sxs-collaboration/spectre)
     145             : to a directory of your choice. In the following we will refer to it as
     146             : SPECTRE_ROOT. You may `git clone` from GitHub, in which case SPECTRE_ROOT will
     147             : be `<your_current_directory>/spectre`. That is, inside SPECTRE_ROOT are `docs`,
     148             : `src`, `support`, `tests` etc. You can also download the source and extract them
     149             : to your desired working directory, making sure not to leave out hidden files
     150             : when you `cp` or `mv` the source files.
     151             : 
     152             : ## Using Docker to obtain a SpECTRE environment {#docker_install}
     153             : 
     154             : A [Docker](https://www.docker.com/) image is available from
     155             : [DockerHub](https://hub.docker.com/r/sxscollaboration/spectre/) and can
     156             : be used to build SpECTRE on a personal machine.
     157             : 
     158             : **Note**: The Docker image or the Singularity image (see below) are
     159             : the recommended ways of using SpECTRE on a personal
     160             : Linux machine. Because of the wide variety of operating systems available today
     161             : it is not possible for us to support all configurations. However, using Spack
     162             : as outlined below is a supported alternative to Docker or Singularity images.
     163             : 
     164             : **Note**: If you have SELinux active
     165             : on your system you must figure out how to enable sharing files with the host
     166             : OS. If you receive errors that you do not have permission to access a shared
     167             : directory it is likely that your system has SELinux enabled. One option is to
     168             : disable SELinux at the expense of reducing the security of your system.
     169             : 
     170             : To build with the Docker image:
     171             : 
     172             : 1. Install [Docker-Desktop](https://docs.docker.com/get-docker/). For Linux, if
     173             :    you want to be able to run the following steps without `sudo`, follow the
     174             :    [post-installation-guide](https://docs.docker.com/engine/install/linux-postinstall/)
     175             :    to add a non-root user.
     176             : 
     177             : 2. Retrieve the Docker image (you may need `sudo` in front of this command)
     178             :    ```
     179             :    docker pull sxscollaboration/spectre:dev
     180             :    ```
     181             : 3. Start the Docker container (you may need `sudo`)
     182             :    ```
     183             :    docker run -v $SPECTRE_ROOT/:$SPECTRE_ROOT/ --name spectre_dev \
     184             :               -i -t sxscollaboration/spectre:dev /bin/bash
     185             :    ```
     186             :    - `-v $SPECTRE_ROOT/:$SPECTRE_ROOT/` binds the directory `$SPECTRE_ROOT`
     187             :    (which is an environment variable you must set up or just use the actual
     188             :    path) outside the container to `$SPECTRE_ROOT` inside the container. In this
     189             :    way, files in the `$SPECTRE_ROOT` on your host system (outside the container)
     190             :    become accessible within the container through the directory SPECTRE_ROOT
     191             :    inside the container. If you wonder why the same SPECTRE_ROOT needs to be
     192             :    used for both inside and outside the container, which is why `$SPECTRE_ROOT`
     193             :    is repeated in the command above with separated by a colon, please see one of
     194             :    the notes below regarding `-v` flag.
     195             :    - The `--name spectre_dev` is optional. If you don't name your container,
     196             :    docker will generate an arbitrary name.
     197             :    - On macOS you can significantly increase the performance of file system
     198             :    operations by appending the flag `:delegated` to `-v`, e.g.
     199             :    `-v $SPECTRE_ROOT/:$SPECTRE_ROOT/:delegated` (see
     200             :    https://docs.docker.com/docker-for-mac/osxfs-caching/).
     201             :    - The `-i` flag is for interactive mode, which will drop you into the
     202             :    container.
     203             :    - It can be useful to expose a port to the host so you can run servers such
     204             :    as [Jupyter](https://jupyter.org/index.html) for accessing the Python
     205             :    bindings (see \ref spectre_using_python) or a Python web server to view the
     206             :    documentation. To do so, append the `-p` option, e.g. `-p 8000:8000`.
     207             : 
     208             :    You will end up in a bash shell in the docker container,
     209             :    as root (you need to be root).
     210             :    Within the container, the files in `$SPECTRE_ROOT` are available and Charm++
     211             :    is installed in `/work/charm_7_0_0`. For the following steps, stay inside the
     212             :    docker container as root.
     213             : 4. Proceed with [building SpECTRE](#building-spectre).
     214             : 
     215             : **Notes:**
     216             :   * Everything in your build directory is owned by root, and is
     217             :     accessible only within the container.
     218             :   * You should edit source files in SPECTRE_ROOT in a separate terminal
     219             :     outside the container, and use the container only for compiling and
     220             :     running the code.
     221             :   * If you exit the container (e.g. ctrl-d),
     222             :     your compilation directories are still saved, as are any other changes to
     223             :     the container that you have made.
     224             :     To restart the container, try the following commands
     225             :     (you may need `sudo`):
     226             :     1. `docker ps -a`,
     227             :       to list all containers with their CONTAINER_IDs and CONTAINER_NAMEs,
     228             :     2. `docker start -i CONTAINER_NAME` or `docker start -i CONTAINER_ID`,
     229             :       to restart your container (above, the CONTAINER_NAME was spectre_dev).
     230             :   * When the Docker container gets updated, you can stop it with
     231             :     `docker stop CONTAINER_NAME`, remove it with `docker rm CONTAINER_NAME`
     232             :     and then start at step 2 above to run it again.
     233             :   * You can run more than one shell in the same container, for instance
     234             :     one shell for compiling with gcc and another for compiling
     235             :     with clang.
     236             :     To add a new shell, run `docker exec -it CONTAINER_NAME /bin/bash`
     237             :     (or `docker exec -it CONTAINER_ID /bin/bash`) from
     238             :     a terminal outside the container.
     239             :   * In step 4 above, technically docker allows you to say
     240             :     `-v $SPECTRE_ROOT/:/my/new/path` to map `$SPECTRE_ROOT` outside the
     241             :     container to any path you want inside the container, but **do not do this**.
     242             :     Compiling inside the container sets up git hooks in SPECTRE_ROOT that
     243             :     contain hardcoded pathnames to SPECTRE_ROOT *as seen from inside the
     244             :     container*. So if your source paths inside and outside the container are
     245             :     different, commands like `git commit` run *from outside the container* will
     246             :     die with `No such file or directory`.
     247             :   * If you want to use Docker within VSCode, take a look at our
     248             :     [quick start guide](../DevGuide/QuickStartDockerVSCode.md) for using Docker
     249             :     with VSCode.
     250             : 
     251             : ## Using Singularity to obtain a SpECTRE environment
     252             : 
     253             : [Singularity](https://sylabs.io) is a container alternative
     254             : to Docker with better security and nicer integration.
     255             : 
     256             : To build SpECTRE with Singularity you must:
     257             : 
     258             : 1. Build [Singularity](https://sylabs.io) and add it to your
     259             :    `$PATH`
     260             : 2. `cd` to the directory where you want to store the SpECTRE Singularity image,
     261             :    source, and build directories, let's call it WORKDIR. The WORKDIR must be
     262             :    somewhere in your home directory. If this does not work for you, follow the
     263             :    Singularity instructions on setting up additional [bind
     264             :    points](https://sylabs.io/guides/3.7/user-guide/bind_paths_and_mounts.html)
     265             :    (version 3.7. For other versions, see the [docs](https://sylabs.io/docs/)).
     266             :    Once inside the WORKDIR, clone SpECTRE into `WORKDIR/SPECTRE_ROOT`.
     267             : 3. Run `sudo singularity build spectre.img
     268             :    docker://sxscollaboration/spectre:dev`.
     269             :    You can also use spectre:ci instead of spectre:dev if you want more
     270             :    compilers installed.
     271             : 
     272             :    If you get the error message that `makesquashfs` did not have enough space to
     273             :    create the image you need to set a different `SINGULARITY_TMPDIR`. This can
     274             :    be done by running: `sudo SINGULARITY_TMPDIR=/path/to/new/tmp singularity
     275             :    build spectre.img docker://sxscollaboration/spectre:dev`. Normally
     276             :    `SINGULARITY_TMPDIR` is `/tmp`, but building the image will temporarily need
     277             :    almost 8GB of space.
     278             : 
     279             :    You can control where Singularity stores the downloaded image files from
     280             :    DockerHub by specifying the `SINGULARITY_CACHEDIR` environment variable. The
     281             :    default is `$HOME/.singularity/`. Note that `$HOME` is `/root` when running
     282             :    using `sudo`.
     283             : 4. To start the container run `singularity shell spectre.img` and you
     284             :    will be dropped into a bash shell.
     285             : 5. Proceed with [building SpECTRE](#building-spectre).
     286             : 
     287             : **Notes:**
     288             : - You should edit source files in SPECTRE_ROOT in a separate terminal
     289             :   outside the container, and use the container only for compiling and running
     290             :   the code.
     291             : - If you don't have the same Python version in your environment outside the
     292             :   container as the version inside the container, this will create problems
     293             :   with git hooks. The Singularity container uses python3.8 by default. Thus, it
     294             :   is up to the user to ensure that they are using the same Python version inside
     295             :   and outside the container. To use a different Python version in the container
     296             :   add `-D Python_EXECUTABLE=/path/to/python` to the cmake command where
     297             :   `/path/to/python` is usually `/usr/bin/pythonX` and `X` is the version you
     298             :   want.
     299             : - Unlike Docker, Singularity does not keep the state between runs. However, it
     300             :   shares the home directory with the host OS so you should do all your work
     301             :   somewhere in your home directory.
     302             : - To run more than one container just do `singularity shell spectre.img` in
     303             :   another terminal.
     304             : - Since the data you modify lives on the host OS there is no need to worry about
     305             :   losing any data, needing to clean up old containers, or sharing data between
     306             :   containers and the host.
     307             : 
     308             : ## Using Spack to set up a SpECTRE environment
     309             : 
     310             : SpECTRE's dependencies can be installed with
     311             : [Spack](https://github.com/spack/spack), a package manager tailored for HPC use.
     312             : [Install Spack](https://spack.readthedocs.io/en/latest/getting_started.html) by
     313             : cloning it into `SPACK_DIR` (a directory of your choice). Then, enable Spack's
     314             : shell support with `source SPACK_DIR/share/spack/setup-env.sh`. Consider adding
     315             : this line to your `.bash_profile`, `.bashrc`, or similar. Refer to [Spack's
     316             : getting started guide](https://spack.readthedocs.io/en/latest/getting_started.html)
     317             : for more information.
     318             : 
     319             : Once you have Spack installed, one way to install the SpECTRE dependencies is
     320             : with a [Spack environment](https://spack.readthedocs.io/en/latest/environments.html):
     321             : 
     322             : \include support/DevEnvironments/spack.yaml
     323             : 
     324             : You can also install the Spack packages listed in the environment file above
     325             : with a plain `spack install` if you prefer.
     326             : 
     327             : **Notes:**
     328             : - Spack allows very flexible configurations and we recommended you read the
     329             :   [documentation](https://spack.readthedocs.io) if you require features such as
     330             :   packages installed with different compilers.
     331             : - For security, it is good practice to make Spack [use the system's
     332             :   OpenSSL](https://spack.readthedocs.io/en/latest/getting_started.html#openssl)
     333             :   rather than allow it to install a new copy.
     334             : - To avoid reinstalling lots of system-provided packages with Spack, use the
     335             :   `spack external find` feature and the `--reuse` flag to `spack concretize` (or
     336             :   `spack install`). You can also install some of the dependencies with your
     337             :   system's package manager in advance, e.g., with `apt` or `brew`. If they are
     338             :   not picked up by `spack external find` automatically, register them with Spack
     339             :   manually. See the [Spack documentation on external
     340             :   packages](https://spack.readthedocs.io/en/latest/build_settings.html#external-packages)
     341             :   for details.
     342             : - Spack works well with a module environment, such as
     343             :   [LMod](https://github.com/TACC/Lmod). See the [Spack documentation on
     344             :   modules](https://spack.readthedocs.io/en/latest/module_file_support.html) for
     345             :   details.
     346             : - On macOS:
     347             :   - Brigand has an issue with AppleClang 13 when compiling tests (see
     348             :     https://github.com/edouarda/brigand/issues/274). Since it is header-only,
     349             :     you can simply clone the [Brigand repository](https://github.com/edouarda/brigand)
     350             :     instead of installing it with Spack.
     351             : 
     352             : ## Building Charm++ {#building-charm}
     353             : 
     354             : If you are not using a container, haven't installed Charm++ with Spack, or want
     355             : to install Charm++ manually for other reasons, follow the installation
     356             : instructions in the [Charm++ repository](https://github.com/UIUC-PPL/charm)
     357             : and in their [documentation](https://charm.readthedocs.io/en/latest/quickstart.html#installing-charm).
     358             : Here are a few notes:
     359             : 
     360             : - Once you cloned the [Charm++ repository](https://github.com/UIUC-PPL/charm),
     361             :   run `git checkout v7.0.0` to switch to a supported, stable release of
     362             :   Charm++.
     363             : - Apply the appropriate patch (if there is one) for the version from
     364             :   `${SPECTRE_ROOT}/support/Charm`. For example, if you have Charm++ v7.0.0
     365             :   then the patch will be `v7.0.0.patch`.
     366             : - Choose the `LIBS` target to compile. This is needed so that we can support the
     367             :   more sophisticated load balancers in SpECTRE executables.
     368             : - On a personal machine the correct target architecture is likely
     369             :   `multicore-linux-x86_64`, or `multicore-darwin-x86_64` on macOS. On an HPC
     370             :   system the correct Charm++ target architecture depends on the machine's
     371             :   inter-node communication architecture. It might take some experimenting to
     372             :   figure out which Charm++ configuration provides the best performance.
     373             : - Compile Charm++ with support for shared libraries by appending the option
     374             :   `--build-shared` to the `./build` command or pass `BUILD_SHARED=ON` to the
     375             :   CMake configuration (see the [Charm++ installation
     376             :   instructions](https://github.com/UIUC-PPL/charm#building-dynamic-libraries)).
     377             : - When compiling Charm++ you can specify the compiler using, for example,
     378             :   ```
     379             :   ./build LIBS ARCH clang
     380             :   ```
     381             : 
     382             : ## Building SpECTRE {#building-spectre}
     383             : 
     384             : Once you have set up your development environment you can compile SpECTRE.
     385             : Follow these steps:
     386             : 
     387             : 1. Create a build directory where you would like to compile SpECTRE. In the
     388             :    Docker container you could create, e.g., `/work/spectre-build`. It can be
     389             :    useful to add a descriptive label to the name of the build directory since
     390             :    you may create more later, e.g., `build-clang-Debug`. Then, `cd` into the
     391             :    build directory.
     392             : 2. Determine the location of your Charm++ installation. In the Docker container
     393             :    it is `/work/charm_7_0_0/multicore-linux-x86_64-gcc` for GCC builds and
     394             :    `/work/charm_7_0_0/mpi-linux-x86_64-smp-clang` for clang builds. For Spack
     395             :    installations you can determine it with
     396             :    `spack location --install-dir charmpp`. We refer to the install directory as
     397             :    `CHARM_ROOT` below.
     398             : 3. In your new SpECTRE build directory, configure the build with CMake:
     399             :    ```
     400             :    cmake -D CHARM_ROOT=$CHARM_ROOT SPECTRE_ROOT
     401             :    ```
     402             :    Add options to the `cmake` command to to configure the build, select
     403             :    compilers, etc. For instance, to build with clang you may run:
     404             :    ```
     405             :    cmake -D CMAKE_CXX_COMPILER=clang++ \
     406             :          -D CMAKE_C_COMPILER=clang \
     407             :          -D CMAKE_Fortran_COMPILER=gfortran \
     408             :          -D CHARM_ROOT=$CHARM_ROOT \
     409             :          SPECTRE_ROOT
     410             :    ```
     411             :    See \ref common_cmake_flags for documentation on possible configuration
     412             :    options.
     413             : 4. When cmake configuration is done, you are ready to build target executables.
     414             :    - You can see the list of available targets by running `make list` (or `ninja
     415             :      list` if you are using the Ninja generator) or by using tab completion.
     416             :      Compile targets with `make -jN TARGET` (or `ninja -jN TARGET`), where `N`
     417             :      is the number of cores to build on in parallel (e.g. `-j4`). Note that the
     418             :      Ninja generator allows you to compile individual source files too.
     419             :    - Compile the `unit-tests` target and run `ctest -L unit` to run unit tests.
     420             :      Compile `test-executables` and run `ctest` to run all tests, including
     421             :      executables. To compile `test-executables` you may have to reduce the
     422             :      number of cores you build on in parallel to avoid running out of memory.
     423             :    - To use the command-line interface (CLI), compile the `cli` target (see
     424             :      \ref tutorial_cli).
     425             :    - To use the Python bindings, compile the `all-pybindings` target (see
     426             :      \ref spectre_using_python).
     427             : 
     428             : ## Code Coverage Analysis
     429             : 
     430             : For any coverage analysis you will need to have LCOV installed on the system.
     431             : For documentation coverage analysis you will also need to install
     432             : [coverxygen](https://github.com/psycofdj/coverxygen) and for test coverage
     433             : analysis [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html).
     434             : 
     435             : If you have these installed (which is already done if
     436             : you are using the docker container), you can look at code coverage as follows:
     437             : 
     438             : 1. On a gcc build, pass `-D COVERAGE=ON` to `cmake`
     439             : 2. `make unit-test-coverage`
     440             : 3. The output is in `docs/html/unit-test-coverage`.

Generated by: LCOV version 1.14