Build & Install
***************
FleCSI can be configured to run with different distributed-memory
runtimes, including Legion, HPX, and MPI.
FleCSI applications can also use several kinds of on-node parallelism,
including the C++ standard library's parallel algorithms and (via Kokkos)
OpenMP, CUDA and HIP. Full documentation for FleCSI
requires both Sphinx and Doxygen. These configuration options are listed
to convey to the reader that the FleCSI build system has several paths
that can be taken to tailor FleCSI to a given system and architecture.
----
Build requirements
++++++++++++++++++
* C++17 compliant compiler
* MPI: must have support for *MPI_THREAD_MULTIPLE*.
* `Boost `_ : We require *program_options* and *stacktrace*.
* `Legion `_
* `CMake `_
* `Kokkos `_
Additional requirements for documentation
-----------------------------------------
* `Python `_
* `Sphinx `_ : only required to build the web-based documentation.
* `Sphinx RTD Theme `_
* `Doxygen `_ : only required to build the interface documentation.
----
Getting The Code
++++++++++++++++
.. note::
If you are a user and only want to install FleCSI, you can skip this
step and use the instructions for installing FleCSI using Spack.
Clone the `FleCSI git repository`__ and create an out-of-source build area
(FleCSI prohibits in-source builds):
__ https://github.com/flecsi/flecsi
.. code-block:: console
$ git clone https://github.com/flecsi/flecsi.git
$ cd flecsi
$ mkdir build
$ cd build
----
Spack
+++++
The preferred method for installing FleCSI and its dependencies is to
use `Spack `_. Spack is easy
to install and configure:
.. code-block:: console
$ git clone https://github.com/spack/spack.git
$ source path/to/spack/repository/share/spack/setup-env.sh
Once spack is installed, you can install FleCSI like:
.. code-block:: console
$ spack install flecsi
FleCSI supports several different versions and variants, e.g.:
.. code-block:: console
$ spack install flecsi@2 backend=legion +graphviz +kokkos
For a complete list of versions and variants, type:
.. code-block:: console
$ spack info flecsi
More documentation and information on Spack is available `here
`_.
----
FleCSI Developers
+++++++++++++++++
If you are a developer, and would like to install only the dependencies of
FleCSI (assuming that you will build FleCSI from source), you can use
Spack's ``--only`` option:
.. code-block:: console
$ spack install --only dependencies flecsi backend=legion +hdf5 ^mpich
If you are developing against a particular branch of FleCSI, you can
capture branch-specific spack dependencies by adding the FleCSI spack
repo (before performing the above step):
.. code-block:: console
$ spack repo add path/to/flecsi/spack-repo
This will prepend a spack repository path to your spack configuration,
such that the specific branch of FleCSI can override the normal builtin
spack dependencies to provide whatever features are required for a
successful build.
----
Configuration & Build
+++++++++++++++++++++
.. toctree::
build/options
Example configuration: **MPI**
.. code-block:: console
$ cmake -DFLECSI_BACKEND=mpi ..
Example configuration: **Legion**
.. code-block:: console
$ cmake -DFLECSI_BACKEND=legion ..
After configuration is complete, just use ``make`` to build:
.. code-block:: console
$ make -j 16
Installation uses the normal ``make install`` and will install FleCSI in
the directory specified by ``CMAKE_INSTALL_PREFIX``:
.. code-block:: console
$ make install
----
Building the Unit Tests
+++++++++++++++++++++++
To build the FleCSI unit test suite, turn on the ``ENABLE_UNIT_TESTS``
option:
.. code-block:: console
$ cmake -DENABLE_UNIT_TESTS=ON ..
After building FleCSI, you can run the unit tests like:
.. code-block:: console
$ make test
----
Building the Documentation (Developers)
+++++++++++++++++++++++++++++++++++++++
FleCSI uses Doxygen for its API reference and Sphinx for user and
developer documentation.
Doxygen can be installed with most Linux package managers. To install
Sphinx, you can install ``pip3`` and use it to install ``Sphinx``
and ``sphinx_rtd_theme``. Your package manager should also
have ``pip3``; e.g., on Ubuntu, you can install all of these requirements
like:
.. code-block:: console
$ sudo apt install doxygen
$ sudo apt install python3-pip
$ pip3 install Sphinx
$ pip3 install sphinx_rtd_theme
To enable documentation, do this:
.. code-block:: console
$ cmake -DENABLE_DOCUMENTATION=ON ..
By default, this will enable Doxygen and Sphinx. Once you have properly
configured FleCSI, you can build the documentation like:
.. code-block:: console
$ make doxygen
$ make sphinx
Both of these targets will be built in your build directory under ``doc/``:
Doxygen in an ``api`` subdirectory, and the top-level Sphinx page as ``index.html``.
.. vim: set tabstop=2 shiftwidth=2 expandtab fo=cqt tw=72 :