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 how to install SpECTRE on personal machines and on clusters
10 : that have no official support (yet).
11 :
12 : - For details on installing SpECTRE on a number of clusters that we support
13 : please refer to:
14 : \subpage installation_on_clusters
15 : - For configuring SpECTRE please refer to:
16 : \subpage spectre_build_system
17 : - For instructions on installing SpECTRE on Apple Silicon Macs please refer to:
18 : \subpage installation_on_apple_silicon
19 : - For information on our versioning scheme and public releases please refer to:
20 : \subpage versioning_and_releases
21 :
22 : ### Running containerized releases
23 :
24 : #### CLI Entrypoint
25 :
26 : A quick way to run the code without installing anything at all is with our
27 : containerized releases:
28 :
29 : ```
30 : docker run sxscollaboration/spectre --help
31 : ```
32 :
33 : You can also use [Apptainer/Singularity](https://apptainer.org) instead of
34 : Docker, which works better on computing clusters and is more convenient because
35 : it shares the host's file system:
36 :
37 : ```
38 : apptainer run docker://sxscollaboration/spectre --help
39 : ```
40 :
41 : The entrypoint to this container is the SpECTRE
42 : \ref tutorial_cli "command-line interface (CLI)".
43 : For example, you can generate initial data for a simulation of merging black
44 : holes and plot the result like this:
45 :
46 : ```
47 : apptainer run docker://sxscollaboration/spectre bbh generate-id \
48 : -q 1 --chi-A 0 0 0 --chi-B 0 0 0 -D 16 -w 0.015 -a 0 -o ./bbh_id
49 : apptainer run docker://sxscollaboration/spectre plot slice \
50 : bbh_id/BbhVolume*.h5 -C 0,0,0 -n 0,0,1 -u 0,1,0 -X 24 24 \
51 : -y ConformalFactor -o plot.pdf
52 : ```
53 :
54 : The containers currently have precompiled code only for Linux x86_64 platforms,
55 : and only have a limited set of executables precompiled. The supported features
56 : available in the precompiled containers are:
57 :
58 : - Generating initial data
59 : - Running CCE (see \ref tutorial_cce)
60 : - Running Python support code with the SpECTRE CLI (see \ref tutorial_cli)
61 :
62 : #### Starting a container {#start_deploy_container}
63 :
64 : If you'd rather use an image to start a container, you can run
65 :
66 : ```
67 : docker run --name spectre -i --entrypoint /bin/bash
68 : -t sxscollaboration/spectre:deploy
69 : ```
70 :
71 : \note The `--entrypoint /bin/bash` is important so you don't run the CLI.
72 :
73 : ### Running static binaries
74 :
75 : Another way of running the code without installing anything is with our
76 : precompiled static binaries, which are published on GitHub:
77 :
78 : - Releases with precompiled executables:
79 : https://github.com/sxs-collaboration/spectre/releases
80 :
81 : These are currently compiled only for Linux x86_64 platforms and for Intel
82 : Haswell architecture, so they should be compatible with machines newer than mid
83 : 2013.
84 :
85 : We only publish a limited set of precompiled static binaries that are useful as
86 : stand-alone tools, such as the CCE executables (see \ref tutorial_cce).
87 :
88 : ### Quick-start guide for code development with Docker and Visual Studio Code
89 :
90 : If you're new to writing code for SpECTRE and would like to jump right into a
91 : working development environment, a good place to start is our
92 : \subpage dev_guide_quick_start_docker_vscode.
93 :
94 : ### Quick-start installation {#quick_start_install}
95 :
96 : The easiest way of installing SpECTRE natively on a new machine is this:
97 :
98 : 1. Collect dependencies. You need a C++ compiler (GCC or Clang), CMake,
99 : BLAS/LAPACK, Boost, GSL, HDF5, and Python installed. For details on these
100 : required dependencies see \ref build_dependencies. On many computing clusters
101 : they are available as modules. On personal machines you can install them with
102 : a package manager.
103 :
104 : 2. Clone the SpECTRE repository:
105 :
106 : ```sh
107 : git clone git@github.com:sxs-collaboration/spectre.git
108 : export SPECTRE_HOME=$PWD/spectre
109 : ```
110 :
111 : 3. Install Charm++:
112 :
113 : ```sh
114 : git clone https://github.com/UIUC-PPL/charm
115 : cd charm
116 : git checkout v8.0.0
117 : ./build charm++ <version> --with-production --build-shared --disable-tls
118 : export CHARM_ROOT=$PWD/<version>
119 : ```
120 :
121 : Choose the `<version>` from [this list in the Charm++
122 : documentation](https://github.com/charmplusplus/charm?tab=readme-ov-file#how-to-choose-a-version).
123 : For example, choose `multicore-linux-x86_64` on a Linux laptop,
124 : `multicore-darwin-arm8` on an Apple Silicon laptop, and `mpi-linux-x86_64` on
125 : a standard computing cluster (you will also need MPI for this). See
126 : \ref building-charm for details.
127 :
128 : 4. Configure and build SpECTRE:
129 :
130 : ```sh
131 : cd $SPECTRE_HOME
132 : mkdir build
133 : cd build
134 : cmake \
135 : -D CMAKE_C_COMPILER=<clang or gcc> \
136 : -D CMAKE_CXX_COMPILER=<clang++ or g++> \
137 : -D CMAKE_Fortran_COMPILER=gfortran \
138 : -D CMAKE_BUILD_TYPE=<Debug or Release> \
139 : -D CHARM_ROOT=$CHARM_ROOT \
140 : -D SPECTRE_FETCH_MISSING_DEPS=ON \
141 : -D MEMORY_ALLOCATOR=SYSTEM \
142 : $SPECTRE_HOME
143 : ```
144 :
145 : See \ref building-spectre for details and \ref common_cmake_flags for a list
146 : of possible configuration options. For example, set `-D ENABLE_OPENMP=ON`
147 : to enable OpenMP-parallelization for the exporter library.
148 :
149 : Now you can compile executables (again, see \ref building-spectre for
150 : details). For example:
151 :
152 : ```sh
153 : make -j12 cli
154 : make -j12 BundledExporter
155 : ```
156 :
157 : ### Installation with Spack
158 :
159 : You can also install SpECTRE with the [Spack](https://github.com/spack/spack)
160 : package manager:
161 :
162 : ```sh
163 : git clone https://github.com/spack/spack
164 : source ./spack/share/spack/setup-env.sh
165 : spack compiler find
166 : spack external find
167 : spack install spectre executables=ExportCoordinates3D \
168 : ^charmpp backend=multicore
169 : ```
170 :
171 : You probably want to customize your installation, e.g., to select a particular
172 : version of SpECTRE, the executables you want to install, additional options such
173 : as Python bindings, or the Charm++ backend. You can display all possible options
174 : with:
175 :
176 : ```sh
177 : spack info spectre # or charmpp, etc.
178 : ```
179 :
180 : Refer to the [Spack documentation](https://spack.readthedocs.io/en/latest/) for
181 : more information.
182 :
183 : \warning We have not found the Spack installation particularly stable since the
184 : Spack package manager is still in development.
185 :
186 : ## Detailed installation instructions
187 :
188 : This remainder of this page details the installation procedure for SpECTRE.
189 :
190 : ### Dependencies {#build_dependencies}
191 :
192 : \note You don't need to install any of these dependencies by hand if you
193 : use a container or follow the \ref quick_start_install.
194 :
195 : #### Required:
196 :
197 : * [GCC](https://gcc.gnu.org/) 10.0 or later,
198 : [Clang](https://clang.llvm.org/) 13.0 or later (see
199 : [here](https://apt.llvm.org/) for how to get newer versions of clang through
200 : apt), or AppleClang 13.0.0 or later
201 : * [CMake](https://cmake.org/) 3.18.0 or later
202 : * [Git](https://git-scm.com/)
203 : * BLAS & LAPACK (e.g. [OpenBLAS](http://www.openblas.net))
204 : * [Boost](http://www.boost.org/) 1.60.0 or later
205 : * [GSL](https://www.gnu.org/software/gsl/) \cite Gsl
206 : * [GNU make](https://www.gnu.org/software/make/)
207 : * [HDF5](https://support.hdfgroup.org/HDF5/) (non-mpi version on macOS)
208 : \cite Hdf5
209 : * [Python](https://www.python.org/) 3.10 or later.
210 : * [Charm++](http://charm.cs.illinois.edu/) 7.0.0, or later (8 preferred).
211 : See also \ref building-charm. \cite Charmpp1 \cite Charmpp2 \cite Charmpp3
212 :
213 : The following dependencies will be fetched automatically if you set
214 : `SPECTRE_FETCH_MISSING_DEPS=ON`:
215 :
216 : * [Blaze](https://bitbucket.org/blaze-lib/blaze/overview) v3.8.
217 : When installing manually, it can be beneficial to install Blaze with CMake so
218 : some configuration options are determined automatically, such as cache sizes.
219 : \cite Blaze1 \cite Blaze2
220 : * [Catch2](https://github.com/catchorg/Catch2) 3.4.0 or later.
221 : You can also install Catch2 from your package manager or do a standard CMake
222 : build and installation (as detailed in the [Catch2
223 : docs](https://github.com/catchorg/Catch2/blob/devel/docs/cmake-integration.md#installing-catch2-from-git-repository)).
224 : Compile with `CMAKE_POSITION_INDEPENDENT_CODE=ON`.
225 : * [LIBXSMM](https://github.com/libxsmm/libxsmm) version 1.16.1 or later. Some
226 : configurations of LIBXSMM build incorrectly against pthreads, causing
227 : ``undefined reference to 'pthread_yield'`` when building SpECTRE. It is
228 : unclear what conditions trigger the problem, but it is fixed in versions
229 : newer than 1.17. (As of this writing, there are no newer releases and
230 : affected systems must build from git.) \cite Libxsmm
231 : * [yaml-cpp](https://github.com/jbeder/yaml-cpp) version 0.7.0 or later.
232 : Building with shared library support is recommended when installing from
233 : source. \cite Yamlcpp
234 : * Python dependencies listed in `support/Python/requirements.txt`.
235 : Install with `pip3 install -r support/Python/requirements.txt`.
236 : 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)
237 : before installing packages.
238 : Alternatively, you can set `BOOTSTRAP_PY_DEPS=ON` when configuring a build
239 : with CMake to install missing Python packages into the build directory
240 : automatically.
241 : <details>
242 : \include support/Python/requirements.txt
243 : </details>
244 :
245 : #### Optional:
246 :
247 : * [Pybind11](https://pybind11.readthedocs.io) 2.7.0 or later for SpECTRE Python
248 : bindings. Included in `support/Python/requirements.txt`. \cite Pybind11
249 : * [jemalloc](https://github.com/jemalloc/jemalloc)
250 : * [Doxygen](https://www.doxygen.nl/index.html) 1.9.1 to 1.9.6 — to
251 : generate documentation
252 : * Python dev dependencies listed in `support/Python/dev_requirements.txt`
253 : — for documentation pre- and post-processing, formatting code, etc.
254 : Install with `pip3 install -r support/Python/dev_requirements.txt`.
255 : 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)
256 : before installing packages.
257 : <details>
258 : \include support/Python/dev_requirements.txt
259 : </details>
260 : * [Kokkos](https://github.com/kokkos/kokkos) (experimental) - for GPU support.
261 : See \ref gpu_support for details.
262 : * [Google Benchmark](https://github.com/google/benchmark) - to do
263 : microbenchmarking inside the SpECTRE framework. v1.2 or newer is required
264 : * [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) and
265 : [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) — to check code test
266 : coverage
267 : * [PAPI](http://icl.utk.edu/papi/) — to access hardware performance counters
268 : * [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) — to format C++
269 : code in a clear and consistent fashion
270 : * [Clang-Tidy](http://clang.llvm.org/extra/clang-tidy/) — to "lint" C++ code
271 : * [Scotch](https://gitlab.inria.fr/scotch/scotch) - to build the `ScotchLB`
272 : graph partition based load balancer in charm++.
273 : * [ffmpeg](https://www.ffmpeg.org/) - for animating 1d simulations with
274 : matplotlib
275 : * [xsimd](https://github.com/xtensor-stack/xsimd) 11.0.1 or newer - for manual
276 : vectorization
277 : * [autodiff](https://github.com/autodiff/autodiff/) commit cc2aa5726fdbb258d097f87b97da3d1022f8394e
278 : or newer - for automatic differentiation
279 : * [libbacktrace](https://github.com/ianlancetaylor/libbacktrace) - to show
280 : source files and line numbers in backtraces of errors and asserts. Available
281 : by default on many systems, so you may not have to install it at all. The
282 : CMake configuration will tell you if you have libbacktrace installed.
283 : * [ParaView](https://www.paraview.org/) - for visualization \cite Paraview1
284 : \cite Paraview2 . Make sure your ParaView installation uses the same (major
285 : and minor) version of Python as the rest of the build.
286 : * [SpEC](https://www.black-holes.org/code/SpEC.html) - to load SpEC data.
287 : Compile the exporter in SpEC's `Support/ApplyObservers/Exporter/` directory
288 : (see the `Makefile` in that directory). Also make sure to compile SpEC with
289 : the same compiler and MPI as SpECTRE to avoid compatibility issues.
290 :
291 : #### Bundled:
292 :
293 : * [Brigand](https://github.com/edouarda/brigand)
294 : * [libsharp](https://github.com/Libsharp/libsharp) \cite Libsharp
295 :
296 : ## Clone the SpECTRE repository
297 :
298 : First, clone the [SpECTRE repository](https://github.com/sxs-collaboration/spectre)
299 : to a directory of your choice. In the following we will refer to it as
300 : SPECTRE_ROOT. You may `git clone` from GitHub, in which case SPECTRE_ROOT will
301 : be `<your_current_directory>/spectre`. That is, inside SPECTRE_ROOT are `docs`,
302 : `src`, `support`, `tests` etc. You can also download the source and extract them
303 : to your desired working directory, making sure not to leave out hidden files
304 : when you `cp` or `mv` the source files.
305 :
306 : ## Using Docker to obtain a SpECTRE environment {#docker_install}
307 :
308 : A [Docker](https://www.docker.com/) image is available from
309 : [DockerHub](https://hub.docker.com/r/sxscollaboration/spectre/) and can
310 : be used to build SpECTRE on a personal machine.
311 :
312 : **Note**: If you have SELinux active
313 : on your system you must figure out how to enable sharing files with the host
314 : OS. If you receive errors that you do not have permission to access a shared
315 : directory it is likely that your system has SELinux enabled. One option is to
316 : disable SELinux at the expense of reducing the security of your system.
317 :
318 : To build with the Docker image:
319 :
320 : 1. Install [Docker-Desktop](https://docs.docker.com/get-docker/). For Linux, if
321 : you want to be able to run the following steps without `sudo`, follow the
322 : [post-installation-guide](https://docs.docker.com/engine/install/linux-postinstall/)
323 : to add a non-root user.
324 :
325 : 2. Retrieve the Docker image (you may need `sudo` in front of this command)
326 : ```
327 : docker pull sxscollaboration/spectre:dev
328 : ```
329 : 3. Start the Docker container (you may need `sudo`)
330 : ```
331 : docker run -v $SPECTRE_ROOT/:$SPECTRE_ROOT/ --name spectre_dev \
332 : -i -t sxscollaboration/spectre:dev /bin/bash
333 : ```
334 : - `-v $SPECTRE_ROOT/:$SPECTRE_ROOT/` binds the directory `$SPECTRE_ROOT`
335 : (which is an environment variable you must set up or just use the actual
336 : path) outside the container to `$SPECTRE_ROOT` inside the container. In this
337 : way, files in the `$SPECTRE_ROOT` on your host system (outside the container)
338 : become accessible within the container through the directory SPECTRE_ROOT
339 : inside the container. If you wonder why the same SPECTRE_ROOT needs to be
340 : used for both inside and outside the container, which is why `$SPECTRE_ROOT`
341 : is repeated in the command above with separated by a colon, please see one of
342 : the notes below regarding `-v` flag.
343 : - The `--name spectre_dev` is optional. If you don't name your container,
344 : docker will generate an arbitrary name.
345 : - On macOS you can significantly increase the performance of file system
346 : operations by appending the flag `:delegated` to `-v`, e.g.
347 : `-v $SPECTRE_ROOT/:$SPECTRE_ROOT/:delegated` (see
348 : https://docs.docker.com/docker-for-mac/osxfs-caching/).
349 : - The `-i` flag is for interactive mode, which will drop you into the
350 : container.
351 : - It can be useful to expose a port to the host so you can run servers such
352 : as [Jupyter](https://jupyter.org/index.html) for accessing the Python
353 : bindings (see \ref spectre_using_python) or a Python web server to view the
354 : documentation. To do so, append the `-p` option, e.g. `-p 8000:8000`.
355 :
356 : You will end up in a bash shell in the docker container,
357 : as root (you need to be root).
358 : Within the container, the files in `$SPECTRE_ROOT` are available and Charm++
359 : is installed in `/work/charm_7_0_0`. For the following steps, stay inside the
360 : docker container as root.
361 : 4. Proceed with [building SpECTRE](#building-spectre).
362 :
363 : **Notes:**
364 : * Everything in your build directory is owned by root, and is
365 : accessible only within the container.
366 : * You should edit source files in SPECTRE_ROOT in a separate terminal
367 : outside the container, and use the container only for compiling and
368 : running the code.
369 : * If you exit the container (e.g. ctrl-d),
370 : your compilation directories are still saved, as are any other changes to
371 : the container that you have made.
372 : To restart the container, try the following commands
373 : (you may need `sudo`):
374 : 1. `docker ps -a`,
375 : to list all containers with their CONTAINER_IDs and CONTAINER_NAMEs,
376 : 2. `docker start -i CONTAINER_NAME` or `docker start -i CONTAINER_ID`,
377 : to restart your container (above, the CONTAINER_NAME was spectre_dev).
378 : * When the Docker container gets updated, you can stop it with
379 : `docker stop CONTAINER_NAME`, remove it with `docker rm CONTAINER_NAME`
380 : and then start at step 2 above to run it again.
381 : * You can run more than one shell in the same container, for instance
382 : one shell for compiling with gcc and another for compiling
383 : with clang.
384 : To add a new shell, run `docker exec -it CONTAINER_NAME /bin/bash`
385 : (or `docker exec -it CONTAINER_ID /bin/bash`) from
386 : a terminal outside the container.
387 : * Compiling inside the container sets up git hooks that contain paths to
388 : tools like Python *as seen from inside the container*, so `git commit` run
389 : *from outside the container* may fail with `No such file or directory`.
390 : Pass `-D USE_GIT_HOOKS=OFF` to CMake to avoid this.
391 : * If you want to use Docker within VSCode, take a look at our
392 : [quick start guide](../DevGuide/QuickStartDockerVSCode.md) for using Docker
393 : with VSCode.
394 :
395 : ## Using Singularity to obtain a SpECTRE environment
396 :
397 : [Singularity](https://sylabs.io) is a container alternative
398 : to Docker with better security and nicer integration.
399 :
400 : To build SpECTRE with Singularity you must:
401 :
402 : 1. Build [Singularity](https://sylabs.io) and add it to your
403 : `$PATH`
404 : 2. `cd` to the directory where you want to store the SpECTRE Singularity image,
405 : source, and build directories, let's call it WORKDIR. The WORKDIR must be
406 : somewhere in your home directory. If this does not work for you, follow the
407 : Singularity instructions on setting up additional [bind
408 : points](https://sylabs.io/guides/3.7/user-guide/bind_paths_and_mounts.html)
409 : (version 3.7. For other versions, see the [docs](https://sylabs.io/docs/)).
410 : Once inside the WORKDIR, clone SpECTRE into `WORKDIR/SPECTRE_ROOT`.
411 : 3. Run `sudo singularity build spectre.img
412 : docker://sxscollaboration/spectre:dev`.
413 : You can also use spectre:ci instead of spectre:dev if you want more
414 : compilers installed.
415 :
416 : If you get the error message that `makesquashfs` did not have enough space to
417 : create the image you need to set a different `SINGULARITY_TMPDIR`. This can
418 : be done by running: `sudo SINGULARITY_TMPDIR=/path/to/new/tmp singularity
419 : build spectre.img docker://sxscollaboration/spectre:dev`. Normally
420 : `SINGULARITY_TMPDIR` is `/tmp`, but building the image will temporarily need
421 : almost 8GB of space.
422 :
423 : You can control where Singularity stores the downloaded image files from
424 : DockerHub by specifying the `SINGULARITY_CACHEDIR` environment variable. The
425 : default is `$HOME/.singularity/`. Note that `$HOME` is `/root` when running
426 : using `sudo`.
427 : 4. To start the container run `singularity shell spectre.img` and you
428 : will be dropped into a bash shell.
429 : 5. Proceed with [building SpECTRE](#building-spectre).
430 :
431 : **Notes:**
432 : - You should edit source files in SPECTRE_ROOT in a separate terminal
433 : outside the container, and use the container only for compiling and running
434 : the code.
435 : - If you don't have the same Python version in your environment outside the
436 : container as the version inside the container, this will create problems
437 : with git hooks. The Singularity container uses python3.8 by default. Thus, it
438 : is up to the user to ensure that they are using the same Python version inside
439 : and outside the container. To use a different Python version in the container
440 : add `-D Python_EXECUTABLE=/path/to/python` to the cmake command where
441 : `/path/to/python` is usually `/usr/bin/pythonX` and `X` is the version you
442 : want.
443 : - Unlike Docker, Singularity does not keep the state between runs. However, it
444 : shares the home directory with the host OS so you should do all your work
445 : somewhere in your home directory.
446 : - To run more than one container just do `singularity shell spectre.img` in
447 : another terminal.
448 : - Since the data you modify lives on the host OS there is no need to worry about
449 : losing any data, needing to clean up old containers, or sharing data between
450 : containers and the host.
451 :
452 : ## Using Spack to set up a SpECTRE environment
453 :
454 : SpECTRE's dependencies can be installed with
455 : [Spack](https://github.com/spack/spack), a package manager tailored for HPC use.
456 : [Install Spack](https://spack.readthedocs.io/en/latest/getting_started.html) by
457 : cloning it into `SPACK_DIR` (a directory of your choice). Then, enable Spack's
458 : shell support with `source SPACK_DIR/share/spack/setup-env.sh`. Consider adding
459 : this line to your `.bash_profile`, `.bashrc`, or similar. Refer to [Spack's
460 : getting started guide](https://spack.readthedocs.io/en/latest/getting_started.html)
461 : for more information.
462 :
463 : Once you have Spack installed, one way to install the SpECTRE dependencies is
464 : with a [Spack environment](https://spack.readthedocs.io/en/latest/environments.html):
465 :
466 : \include support/DevEnvironments/spack.yaml
467 :
468 : You can also install the Spack packages listed in the environment file above
469 : with a plain `spack install` if you prefer.
470 :
471 : **Notes:**
472 : - Spack allows very flexible configurations and we recommended you read the
473 : [documentation](https://spack.readthedocs.io) if you require features such as
474 : packages installed with different compilers.
475 : - For security, it is good practice to make Spack [use the system's
476 : OpenSSL](https://spack.readthedocs.io/en/latest/getting_started.html#openssl)
477 : rather than allow it to install a new copy.
478 : - To avoid reinstalling lots of system-provided packages with Spack, use the
479 : `spack external find` feature and the `--reuse` flag to `spack concretize` (or
480 : `spack install`). You can also install some of the dependencies with your
481 : system's package manager in advance, e.g., with `apt` or `brew`. If they are
482 : not picked up by `spack external find` automatically, register them with Spack
483 : manually. See the [Spack documentation on external
484 : packages](https://spack.readthedocs.io/en/latest/build_settings.html#external-packages)
485 : for details.
486 : - Spack works well with a module environment, such as
487 : [LMod](https://github.com/TACC/Lmod). See the [Spack documentation on
488 : modules](https://spack.readthedocs.io/en/latest/module_file_support.html) for
489 : details.
490 :
491 : ## Building Charm++ {#building-charm}
492 :
493 : If you are not using a container, haven't installed Charm++ with Spack, or want
494 : to install Charm++ manually for other reasons, follow the installation
495 : instructions in the [Charm++ repository](https://github.com/UIUC-PPL/charm)
496 : and in their [documentation](https://charm.readthedocs.io/en/latest/quickstart.html#installing-charm).
497 : Here are a few notes:
498 :
499 : - Once you cloned the [Charm++ repository](https://github.com/UIUC-PPL/charm),
500 : run `git checkout v8.0.0` to switch to a supported, stable release of
501 : Charm++.
502 : - Apply the appropriate patch (if there is one) for the version from
503 : `${SPECTRE_ROOT}/support/Charm`. For example, if you have Charm++ v7.0.0
504 : then the patch will be `v7.0.0.patch`.
505 : - Choose the `LIBS` target to compile. This is needed so that we can support the
506 : more sophisticated load balancers in SpECTRE executables.
507 : - On a personal machine the correct target architecture is likely
508 : `multicore-linux-x86_64`, or `multicore-darwin-x86_64` on macOS. On an HPC
509 : system the correct Charm++ target architecture depends on the machine's
510 : inter-node communication architecture. It might take some experimenting to
511 : figure out which Charm++ configuration provides the best performance.
512 : - Compile Charm++ with support for shared libraries by appending the option
513 : `--build-shared` to the `./build` command or pass `BUILD_SHARED=ON` to the
514 : CMake configuration (see the [Charm++ installation
515 : instructions](https://github.com/UIUC-PPL/charm#building-dynamic-libraries)).
516 : - Passing the `--disable-tls` option to `build` or `-D DISABLE_TLS=ON` to
517 : cmake is required for SpECTRE's Python bindings to work.
518 : - When compiling Charm++ you can specify the compiler using, for example,
519 : ```
520 : ./build LIBS ARCH clang
521 : ```
522 :
523 : ## Building SpECTRE {#building-spectre}
524 :
525 : Once you have set up your development environment you can compile SpECTRE.
526 : Follow these steps:
527 :
528 : 1. Create a build directory where you would like to compile SpECTRE. In the
529 : Docker container you could create, e.g., `/work/spectre-build`. It can be
530 : useful to add a descriptive label to the name of the build directory since
531 : you may create more later, e.g., `build-clang-Debug`. Then, `cd` into the
532 : build directory.
533 : 2. Determine the location of your Charm++ installation. In the Docker container
534 : it is `/work/charm_7_0_0/multicore-linux-x86_64-gcc` for GCC builds and
535 : `/work/charm_7_0_0/mpi-linux-x86_64-smp-clang` for clang builds. For Spack
536 : installations you can determine it with
537 : `spack location --install-dir charmpp`. We refer to the install directory as
538 : `CHARM_ROOT` below.
539 : 3. In your new SpECTRE build directory, configure the build with CMake:
540 : ```
541 : cmake -D CHARM_ROOT=$CHARM_ROOT SPECTRE_ROOT
542 : ```
543 : Add options to the `cmake` command to configure the build, select
544 : compilers, etc. For instance, to build with clang you may run:
545 : ```
546 : cmake -D CMAKE_CXX_COMPILER=clang++ \
547 : -D CMAKE_C_COMPILER=clang \
548 : -D CMAKE_Fortran_COMPILER=gfortran \
549 : -D CHARM_ROOT=$CHARM_ROOT \
550 : SPECTRE_ROOT
551 : ```
552 : See \ref common_cmake_flags for documentation on possible configuration
553 : options.
554 : 4. When cmake configuration is done, you are ready to build target executables.
555 : - You can see the list of available targets by running `make list` (or `ninja
556 : list` if you are using the Ninja generator) or by using tab completion.
557 : Compile targets with `make -jN TARGET` (or `ninja -jN TARGET`), where `N`
558 : is the number of cores to build on in parallel (e.g. `-j4`). Note that the
559 : Ninja generator allows you to compile individual source files too.
560 : - Compile the `unit-tests` target and run `ctest -L unit` to run unit tests.
561 : Compile `test-executables` and run `ctest` to run all tests, including
562 : executables. To compile `test-executables` you may have to reduce the
563 : number of cores you build on in parallel to avoid running out of memory.
564 : - To use the command-line interface (CLI), compile the `cli` target (see
565 : \ref tutorial_cli).
566 : - To use the Python bindings, compile the `all-pybindings` target (see
567 : \ref spectre_using_python).
568 :
569 : ## Code Coverage Analysis
570 :
571 : For any coverage analysis you will need to have LCOV installed on the system.
572 : For documentation coverage analysis you will also need to install
573 : [coverxygen](https://github.com/psycofdj/coverxygen) and for test coverage
574 : analysis [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html).
575 :
576 : If you have these installed (which is already done if
577 : you are using the docker container), you can look at code coverage as follows:
578 :
579 : 1. On a gcc build, pass `-D COVERAGE=ON` to `cmake`
580 : 2. `make unit-test-coverage`
581 : 3. The output is in `docs/html/unit-test-coverage`.
|
