.. |br| raw:: html
.. _build: Build & Install *************** FleCSI can be configured to run with different distributed-memory runtimes, including Legion and MPI. FleCSI also has support for various fine-grained, node-level runtimes, including OpenMP, Kokkos, and the C++17 extensions for parallelism. 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. .. toctree:: :caption: Building: build/options ---- Requirements & Prerequisites ++++++++++++++++++++++++++++ The following list of requirements provides a complete set of build options, which might not be necessary for a particular build: .. note:: CI listings indicate specific versions used by FleCSI's continuous integration tests. If nothing is indicated, there is no specific version tested. * **Boost** |br| We require *program_options* and *stacktrace*. |br| *CI: 1.79.0* * **C++17 compliant compiler** |br| At the current time, FleCSI has been tested with GNU and Clang C++ compilers. |br| *CI: gcc 9.4.0, clang 13.0.1* * **Doxygen** |br| Doxygen is only required to build the interface documentation. * **GASNet** |br| GASNet is only required if Legion support is enabled. * **MPI** |br| The MPI implementation must have support for *MPI_THREAD_MULTIPLE*. |br| *CI: mpich 3.4.2, openmpi 4.1.2* * **Legion** |br| We are currently using the most up-to-date version of the control replication branch. |br| *CI: control_replication branch* * **parMETIS/METIS** |br| *CI: 4.0.3 (parMETIS), 5.1.0 (METIS)* * **CMake** |br| We currently require CMake version 3.12 or greater. |br| *CI: 3.20.1* * **Sphinx** |br| Sphinx is only required to build the web-based documentation. We are currently using Sphinx 5.0.2. We also require the Sphinx RTD Theme (using version 1.0.0). These can be installed on most Linux systems using pip. * **Python** |br| We currently require Python 3.0 or greater. ---- 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 +++++++++++++++++++++ Example configuration: **MPI** .. code-block:: console $ cmake -DFLECSI_BACKEND=mpi .. Example configuration: **MPI + OpenMP** .. code-block:: console $ cmake -DFLECSI_BACKEND=mpi -DENABLE_OPENMP .. 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``, ``recommonmark``, 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 recommonmark $ 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/``: e.g., the main Doxygen ``index.html`` page will be located at ``doc/api/index.html``. Similarly, the Sphinx main ``index.html`` page will be located at ``doc/index.html``. You can open these in your browser with ``file:///path/to/your/build/directory/doc/api/index.html`` and ``file:///path/to/your/build/directory/doc/index.html``. .. vim: set tabstop=2 shiftwidth=2 expandtab fo=cqt tw=72 :