SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs/Installation - Installation.md Hit Total Coverage
Commit: ebec864322c50bab8dca0a90baf8d01875114261 Lines: 0 1 0.0 %
Date: 2020-11-25 20:28:50
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             : This page details the installation procedure for SpECTRE on personal computers.
       8             : For instructions on installing SpECTRE on clusters please refer to the \ref
       9             : installation_on_clusters "Installation on clusters" page.
      10             : 
      11             : ### Dependencies
      12             : 
      13             : #### Required:
      14             : 
      15             : * [GCC](https://gcc.gnu.org/) 7.0 or later,
      16             : [Clang](https://clang.llvm.org/) 5.0 or later, or AppleClang 6.0 or later
      17             : * [CMake](https://cmake.org/) 3.8.0 or later
      18             : * [Charm++](http://charm.cs.illinois.edu/) 6.10.2
      19             : * [Git](https://git-scm.com/)
      20             : * BLAS (e.g. [OpenBLAS](http://www.openblas.net))
      21             : * [Blaze](https://bitbucket.org/blaze-lib/blaze/overview) v3.5
      22             : * [Boost](http://www.boost.org/) 1.60.0 or later
      23             : * [Brigand](https://github.com/edouarda/brigand)
      24             : * [Catch](https://github.com/philsquared/Catch) 2.1.0 or later
      25             : * [GSL](https://www.gnu.org/software/gsl/)
      26             : * [HDF5](https://support.hdfgroup.org/HDF5/) (non-mpi version on macOS)
      27             : * [jemalloc](https://github.com/jemalloc/jemalloc)
      28             : * LAPACK
      29             : * [libsharp](https://github.com/Libsharp/libsharp) should be built with
      30             :   support disabled for openmp and mpi, as we want all of our parallelism to
      31             :   be accomplished via Charm++.
      32             : * [LIBXSMM](https://github.com/hfp/libxsmm)
      33             : * [yaml-cpp](https://github.com/jbeder/yaml-cpp) version 0.6.3 is
      34             :   recommended. Building with shared library support is also recommended.
      35             : * [Python](https://www.python.org/) 2.7, or 3.5 or later
      36             : * [NumPy](http://www.numpy.org/) 1.10 or later
      37             : * [SciPy](https://www.scipy.org)
      38             : 
      39             : #### Optional:
      40             : * [Pybind11](https://pybind11.readthedocs.io) for SpECTRE Python bindings
      41             : * [Doxygen](http://www.stack.nl/~dimitri/doxygen/index.html) — to generate
      42             :   documentation
      43             : * [Python](https://www.python.org/) with
      44             :   [BeautifulSoup4](https://pypi.org/project/beautifulsoup4/) and
      45             :   [Pybtex](https://pybtex.org) — for documentation post-processing
      46             : * [Google Benchmark](https://github.com/google/benchmark) - to do
      47             :   microbenchmarking inside the SpECTRE framework. v1.2 or newer is required
      48             : * [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) and
      49             :   [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) — to check code test
      50             :   coverage
      51             : * [coverxygen](https://github.com/psycofdj/coverxygen) — to check documentation
      52             :   coverage
      53             : * [PAPI](http://icl.utk.edu/papi/) — to access hardware performance counters
      54             : * [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) — to format C++
      55             :   code in a clear and consistent fashion
      56             : * [Clang-Tidy](http://clang.llvm.org/extra/clang-tidy/) — to "lint" C++ code
      57             : * [Cppcheck](http://cppcheck.sourceforge.net/) — to analyze C++ code
      58             : * [yapf](https://github.com/google/yapf) 0.29.0 - to format python code
      59             : 
      60             : ## Using Docker to obtain a SpECTRE environment
      61             : 
      62             : A [Docker](https://www.docker.com/) image is available from
      63             : [DockerHub](https://hub.docker.com/r/sxscollaboration/spectrebuildenv/) and can
      64             : be used to build SpECTRE on a personal machine.
      65             : 
      66             : **Note**: The Docker image is the recommended way of using SpECTRE on a personal
      67             : Linux machine. Because of the wide variety of operating systems available today
      68             : it is not possible for us to support all configurations. However, using Spack
      69             : as outlined below is a supported alternative to Docker images.
      70             : 
      71             : **NOTE**: If you have SELinux active
      72             : on your system you must figure out how to enable sharing files with the host
      73             : OS. If you receive errors that you do not have permission to access a shared
      74             : directory it is likely that your system has SELinux enabled. One option is to
      75             : disable SELinux at the expense of reducing the security of your system.
      76             : 
      77             : To build with the docker image:
      78             : 
      79             : 1. Clone SpECTRE into SPECTRE_ROOT, a directory of your choice.
      80             : 2. Retrieve the docker image (you may need `sudo` in front of this command)
      81             :    ```
      82             :    docker pull sxscollaboration/spectrebuildenv:latest
      83             :    ```
      84             : 3. Start the docker container (you may need `sudo`)
      85             :    ```
      86             :    docker run -v SPECTRE_ROOT:SPECTRE_ROOT --name CONTAINER_NAME \
      87             :               -i -t sxscollaboration/spectrebuildenv:latest /bin/bash
      88             :    ```
      89             :    - The `--name CONTAINER_NAME` is optional, where CONTAINER_NAME is a name
      90             :    of your choice. If you don't name your container, docker will generate an
      91             :    arbitrary name.
      92             :    - On macOS you can significantly increase the performance of file system
      93             :    operations by appending the flag `:delegated` to `-v`, e.g.
      94             :    `-v SPECTRE_ROOT:SPECTRE_ROOT:delegated` (see
      95             :    https://docs.docker.com/docker-for-mac/osxfs-caching/).
      96             :    - It can be useful to expose a port to the host so you can run servers such
      97             :    as [Jupyter](https://jupyter.org/index.html) for accessing the Python
      98             :    bindings (see \ref spectre_using_python) or a Python web server to view the
      99             :    documentation. To do so, append the `-p` option, e.g. `-p 8000:8000`.
     100             : 
     101             :    You will end up in a shell in the docker container,
     102             :    as root (you need to be root).
     103             :    Within the container, the files in SPECTRE_ROOT are available and
     104             :    Charm++ is installed in `/work/charm`. For the following steps, stay inside
     105             :    the docker container as root.
     106             : 4. Make a build directory somewhere inside the container, e.g.
     107             :    `/work/spectre-build-gcc`, and cd into it.
     108             : 5. Build SpECTRE with
     109             : ```
     110             :    cmake -D CMAKE_Fortran_COMPILER=gfortran-8 \
     111             :          -D CHARM_ROOT=/work/charm/multicore-linux-x86_64-gcc SPECTRE_ROOT
     112             : ```
     113             :    then
     114             :    `make -jN`
     115             :    to compile the code, `make test-executables -jN` to compile the test
     116             :    executables, and `ctest` to run the tests.
     117             : 
     118             : Notes:
     119             :   * Everything in your build directory is owned by root, and is
     120             :     accessible only within the container.
     121             :   * You should edit source files in SPECTRE_ROOT in a separate terminal
     122             :     outside the container, and use the container only for compiling and
     123             :     running the code.
     124             :   * If you exit the container (e.g. ctrl-d),
     125             :     your compilation directories are still saved, as is the patch
     126             :     that you have applied to /work/charm and any other changes to
     127             :     the container that you have made.
     128             :     To restart the container, try the following commands
     129             :     (you may need `sudo`):
     130             :     1. `docker ps -a`,
     131             :       to list all containers with their CONTAINER_IDs and CONTAINER_NAMEs,
     132             :     2. `docker start -i CONTAINER_NAME` or `docker start -i CONTAINER_ID`,
     133             :       to restart your container.
     134             :   * You can run more than one shell in the same container, for instance
     135             :     one shell for compiling with gcc and another for compiling
     136             :     with clang.
     137             :     To add a new shell, run `docker exec -it CONTAINER_NAME /bin/bash`
     138             :     (or `docker exec -it CONTAINER_ID /bin/bash`) from
     139             :     a terminal outside the container.
     140             :   * In step 3 above, the `-v SPECTRE_ROOT:SPECTRE_ROOT` maps the directory
     141             :     SPECTRE_ROOT outside the container to SPECTRE_ROOT inside the container.
     142             :     Technically docker allows you to say `-v SPECTRE_ROOT:/my/new/path`
     143             :     to map SPECTRE_ROOT outside the container to any path you want inside
     144             :     the container, but **do not do this**.  Compiling inside the container
     145             :     sets up git hooks in SPECTRE_ROOT that
     146             :     contain hardcoded pathnames to SPECTRE_ROOT *as seen from
     147             :     inside the container*. So if your source paths inside and outside the
     148             :     container are different, commands like `git commit` run *from
     149             :     outside the container* will die with `No such file or directory`.
     150             :   * To compile with clang, the cmake command is
     151             : ```
     152             :     cmake -D CMAKE_CXX_COMPILER=clang++ \
     153             :           -D CMAKE_C_COMPILER=clang \
     154             :           -D CMAKE_Fortran_COMPILER=gfortran-8 \
     155             :           -D CHARM_ROOT=/work/charm/multicore-linux-x86_64-clang SPECTRE_ROOT
     156             : ```
     157             :   * To compile the Python bindings, add the option
     158             :     `-D BUILD_PYTHON_BINDINGS=ON` to the `cmake` command (see
     159             :     \ref spectre_writing_python_bindings). You can specify the Python version,
     160             :     interpreter and libraries used for compiling and testing the bindings by
     161             :     setting the `-D PYTHON_EXECUTABLE` to an absolute path such as
     162             :     `/usr/bin/python3`.
     163             :   * When the Docker container gets updated, you can stop it with
     164             :     `docker stop CONTAINER_NAME`, remove it with `docker rm CONTAINER_NAME`
     165             :     and then start at step 2 above to run it again.
     166             : 
     167             : ## Using Singularity to obtain a SpECTRE environment
     168             : 
     169             : [Singularity](http://singularity.lbl.gov/index.html) is a container alternative
     170             : to Docker with better security and nicer integration.
     171             : 
     172             : To use Singularity you must:
     173             : 
     174             : 1. Build [Singularity](http://singularity.lbl.gov/index.html) and add it to your
     175             :    `$PATH`
     176             : 2. `cd` to the directory where you want to store the SpECTRE Singularity image,
     177             :    source, and build directories, let's call it WORKDIR. The WORKDIR must be
     178             :    somewhere in your home directory. If this does not work for you, follow the
     179             :    Singularity instructions on setting up additional [bind
     180             :    points](http://singularity.lbl.gov/docs-mount). Once inside the WORKDIR,
     181             :    clone SpECTRE into `WORKDIR/SPECTRE_ROOT`.
     182             : 3. Run `sudo singularity build spectre.img
     183             :    docker://sxscollaboration/spectrebuildenv:latest`.
     184             : 
     185             :    If you get the error message that `makesquashfs` did not have enough space to
     186             :    create the image you need to set a different `SINGULARITY_TMPDIR`. This can
     187             :    be done by running: `sudo SINGULARITY_TMPDIR=/path/to/new/tmp singularity
     188             :    build spectre.img docker://sxscollaboration/spectrebuildenv:latest`. Normally
     189             :    `SINGULARITY_TMPDIR` is `/tmp`, but building the image will temporarily need
     190             :    almost 8GB of space.
     191             : 
     192             :    You can control where Singularity stores the downloaded image files from
     193             :    DockerHub by specifying the `SINGULARITY_CACHEDIR` environment variable. The
     194             :    default is `$HOME/.singularity/`. Note that `$HOME` is `/root` when running
     195             :    using `sudo`.
     196             : 4. To start the container run `singularity shell spectre.img` and you
     197             :    will be dropped into a bash shell.
     198             : 5. Run `cd SPECTRE_HOME && mkdir build && cd build` to set up a build
     199             :    directory.
     200             : 6. To build SpECTRE run
     201             : ```
     202             :    cmake -D CMAKE_Fortran_COMPILER=gfortran-8 \
     203             :          -D CHARM_ROOT=/work/charm/multicore-linux-x86_64-gcc SPECTRE_ROOT
     204             : ```
     205             :    followed by
     206             :    `make -jN` where `N` is the number of cores to build on in parallel.
     207             : 
     208             : Notes:
     209             : - You should edit source files in SPECTRE_ROOT in a separate terminal outside
     210             :   the container, and use the container only for compiling and running the code.
     211             : - Unlike Docker, Singularity does not keep the state between runs. However, it
     212             :   shares the home directory with the host OS so you should do all your work
     213             :   somewhere in your home directory.
     214             : - To run more than one container just do `singularity shell spectre.img` in
     215             :   another terminal.
     216             : - Since the data you modify lives on the host OS there is no need to worry about
     217             :   losing any data, needing to clean up old containers, or sharing data between
     218             :   containers and the host.
     219             : - To build with clang, the CMake command is:
     220             : ```
     221             :     cmake -D CMAKE_CXX_COMPILER=clang++ \
     222             :           -D CMAKE_C_COMPILER=clang \
     223             :           -D CMAKE_Fortran_COMPILER=gfortran-8 \
     224             :           -D CHARM_ROOT=/work/charm/multicore-linux-x86_64-clang SPECTRE_ROOT
     225             : ```
     226             : 
     227             : ## Using Spack to set up a SpECTRE environment
     228             : 
     229             : SpECTRE's dependencies can be installed with
     230             : [Spack](https://github.com/LLNL/spack), a package manager tailored for HPC use.
     231             : Install Spack by cloning it into `SPACK_DIR` (a directory of your choice),
     232             : then add `SPACK_DIR/bin` to your `PATH`.
     233             : 
     234             : For security, it is good practice to make Spack use the system's OpenSSL
     235             : rather than allow it to install a new copy — see Spack's documentation for
     236             : [instructions](https://spack.readthedocs.io/en/latest/getting_started.html#openssl).
     237             : You may need to install the development version of OpenSSL:
     238             : * On Ubuntu (16.04), run `sudo apt-get install libssl-dev`
     239             : * On Fedora (27), run `sudo dnf install openssl-devel`
     240             : 
     241             : Spack works well with a module environment. We recommend
     242             : [LMod](https://github.com/TACC/Lmod), which is available on many systems:
     243             : * On macOS, install LMod from [brew](https://brew.sh/), then source the LMod
     244             :   shell script by adding `. /usr/local/Cellar/lmod/YOUR_VERSION_NUMBER/init/sh`
     245             :   to your `.bash_profile`.
     246             : * On Ubuntu, run `sudo apt-get install -y lmod` and, for Ubuntu 17.04, add
     247             :   `. /etc/profile.d/lmod.sh` to your `.bashrc`. For Ubuntu 16.04, the correct
     248             :   path to add is `. /usr/share/lmod/lmod/init/bash`.
     249             : * On Arch Linux, run `yaourt -Sy lmod` and add `. /etc/profile.d/lmod.sh` to
     250             :   your `.bashrc`,
     251             : * On Fedora/RHEL, GNU Environment Modules comes out-of-the-box and works equally
     252             :   well.
     253             : * Instructions for other Linux distros are available online.
     254             : 
     255             : To use modules with Spack, enable Spack's shell support by adding
     256             : `. SPACK_DIR/share/spack/setup-env.sh` to your `.bash_profile` or `.bashrc`.
     257             : 
     258             : Once you have Spack installed and configured with OpenSSL and LMod, you can
     259             : install the SpECTRE dependencies using
     260             : ```
     261             : spack install blaze@3.2
     262             : spack install brigand@master
     263             : spack install libsharp -openmp -mpi
     264             : spack install catch2
     265             : spack install gsl
     266             : spack install jemalloc # or from your package manager
     267             : spack install libxsmm
     268             : spack install yaml-cpp@develop
     269             : ```
     270             : You can also install CMake, OpenBLAS, Boost, and HDF5 from Spack.
     271             : To load the packages you've installed from Spack run `spack load PACKAGE`,
     272             : or (equivalently) use the `module load` command.
     273             : 
     274             : **Note**: Spack allows very flexible configurations and
     275             : it is recommended you read the [documentation](https://spack.readthedocs.io) if
     276             : you require features such as packages installed with different compilers.
     277             : 
     278             : **Note**: On a Mac, you may need to `spack install
     279             : yaml-cpp@develop~shared` (note that is a tilde and not a dash in front
     280             : of shared) in order to force the building of the static libraries in
     281             : order to avoid dynamic linking errors.
     282             : 
     283             : ### Building SpECTRE
     284             : 
     285             : After the dependencies have been installed, Charm++ and SpECTRE can be compiled.
     286             : Follow these steps:
     287             : 
     288             : 1.  Clone [SpECTRE](https://github.com/sxs-collaboration/spectre) into
     289             :     `SPECTRE_ROOT`, a directory of your choice.
     290             : 2.  Install Charm++:
     291             :   * Clone [Charm++](http://charm.cs.illinois.edu/software) into `CHARM_DIR`,
     292             :     again a directory of your choice.
     293             :   * In `CHARM_DIR`, run
     294             :     `git checkout v6.10.2` to switch to a supported, stable release of Charm++.
     295             :   * Charm++ is compiled by running
     296             :     `./build charm++ ARCH OPTIONS`.
     297             :     To figure out the correct target architecture and options, you can simply
     298             :     run `./build`; the script will then ask you questions to guide you towards
     299             :     the correct settings (see notes below for additional details).
     300             :     Then compile Charm++.
     301             :     The Charm++ build will be located in a new directory,
     302             :     `CHARM_DIR/ARCH_OPTS`, whose name may (or may not) have some of the options
     303             :     appended to the architecture.
     304             :   * On macOS 10.12 it is necessary to patch the STL implementation. Insert
     305             :     \code
     306             :     #ifndef _MACH_PORT_T
     307             :     #define _MACH_PORT_T
     308             :     #include <sys/_types.h> /* __darwin_mach_port_t */
     309             :     typedef __darwin_mach_port_t mach_port_t;
     310             :     #include <pthread.h>
     311             :     mach_port_t pthread_mach_thread_np(pthread_t);
     312             :     #endif /* _MACH_PORT_T */
     313             :     \endcode
     314             :     into the front of
     315             :     `/Library/Developer/CommandLineTools/usr/include/c++/v1/__threading_support`
     316             : 3.  Return to `SPECTRE_ROOT`, and create a build dir by running
     317             :     `mkdir build && cd build`
     318             : 4.  Build SpECTRE with
     319             :     `cmake -D CHARM_ROOT=CHARM_DIR/ARCH_OPTS SPECTRE_ROOT`
     320             :     then
     321             :     `make -jN`
     322             :     to compile the code.
     323             : 5.  Run the tests with
     324             :     `make test-executables && ctest`.
     325             : 
     326             : **Notes**:
     327             : * For more details on building Charm++, see the directions
     328             :   [here](http://charm.cs.illinois.edu/manuals/html/charm++/A.html)
     329             :   The correct target is `charm++` and, for a personal machine, the
     330             :   correct target architecture is likely to be `multicore-linux-x86_64`
     331             :   (or `multicore-darwin-x86_64` on macOS).
     332             :   On an HPC system, the correct Charm++ target architecture depends on the
     333             :   machine's inter-node communication architecture. We will be providing specific
     334             :   instructions for various HPC systems.
     335             : * Both Charm++ and SpECTRE must be compiled using the same compiler,
     336             :   otherwise you will receive undefined reference errors while linking SpECTRE.
     337             :   When compiling Charm++ you can specify the compiler using, for example,
     338             :   ```
     339             :   ./build charm++ ARCH clang
     340             :   ```
     341             :   When compiling SpECTRE you can specify the compiler to CMake using,
     342             :   for example,
     343             :   ```
     344             :   cmake -D CMAKE_CXX_COMPILER=clang++ \
     345             :         -D CMAKE_C_COMPILER=clang \
     346             :         -D CMAKE_Fortran_COMPILER=gfortran \
     347             :         -D CHARM_ROOT=CHARM_DIR/ARCH_OPTS SPECTRE_ROOT
     348             :   ```
     349             : * Inside the SpECTRE build directory, use `make list` to see all available
     350             :   targets. This list can be refreshed by running CMake again.
     351             : 
     352             : ## Code Coverage Analysis
     353             : 
     354             : For any coverage analysis you will need to have LCOV installed on the system.
     355             : For documentation coverage analysis you will also need to install
     356             : [coverxygen](https://github.com/psycofdj/coverxygen) and for test coverage
     357             : analysis [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html).
     358             : 
     359             : If you have these installed (which is already done if
     360             : you are using the docker container), you can look at code coverage as follows:
     361             : 
     362             : 1. On a gcc build, pass `-D COVERAGE=ON` to `cmake`
     363             : 2. `make unit-test-coverage`
     364             : 3. The output is in `docs/html/unit-test-coverage`.

Generated by: LCOV version 1.14