.. |br| raw:: html

   <br />

CMake Configuration Options
===========================

The following set of options are available to control how FleCSI is
built.
Several of them are `made available <../../api/user/group__config.html>`__  as C++ macros for client code.

Flog (FleCSI logging utility) options
-------------------------------------

* **ENABLE_FLOG [default: OFF]** |br|
  This option enables support for the FleCSI logging utility (Flog).
  When *OFF*, functions in the ``flog`` namespace
  and the ``flog`` macros
  remain defined but produce no output.

* **FLOG_ENABLE_COLOR_OUTPUT [default: OFF]** |br|

  .. warning::

     This interface is deprecated. It can now be configured at runtime using
     ``flog::config::color``.
     See also :doc:`../tutorial/runtime`.

  Produce colorized Flog output instead of using the output device's
  default colors.

* **FLOG_SERIALIZATION_INTERVAL [default: 100]** |br|

  .. warning::

     This interface is deprecated. It can now be configured at runtime using
     ``flog::config::serialization_interval``.
     See also
     :doc:`../tutorial/runtime`.

  The Flog serialization interval specifies the number of task
  executions after which FleCSI should check for buffered output to
  process.  It should be set to a value that balances output
  timeliness (lower = more timely output) against performance (higher
  = less overhead from the requisite global reduction).

* **FLOG_SERIALIZATION_THRESHOLD** |br|

  .. warning::

     This interface is deprecated and not used anymore.

* **FLOG_STRIP_LEVEL [default: 0]** |br|

  .. warning::

     This interface is deprecated. It can now be configured at runtime using
     ``flog::config::strip_level``.
     See also
     :doc:`../tutorial/runtime`.

  Set the Flog strip level, which should an integer from 0 to 4.  Like
  tag groups, strip levels are a mechanism for the user to control the
  amount of output that Flog generates: the higher the strip level,
  the fewer Flog messages will be output.  There are five strip levels
  in Flog:

  =====  =====
  Level  Type
  =====  =====
  0      trace
  1      info
  2      warn
  3      error
  4      fatal
  =====  =====

  Each number represents the largest value of ``FLOG_STRIP_LEVEL``
  that will produce that type of output.  That is, if the strip level
  is 0, all message types will be output; if the strip level is 3,
  only *error* and *fatal* log messages will be output. Regardless of
  the strip level, Flog messages that are designated *fatal* will
  generate a runtime error and will invoke ``std::exit``.

Parallelization options
-----------------------

* **ENABLE_KOKKOS** |br|
  This **deprecated** option is ignored for compatibility.

* **ENABLE_MPI_CXX_BINDINGS** |br|
  This **deprecated** option is ignored.

* **ENABLE_OPENMP [default: OFF]** |br|
  This **deprecated** option is ignored for compatibility.

* **FLECSI_BACKEND [default: legion]** |br|
  Specify the backend to use. Currently, *legion*, *hpx*, and *mpi* are
  the only valid options.

Documentation options
---------------------

* **ENABLE_DOCUMENTATION [default: OFF]** |br|
  This option controls whether or not the FleCSI user- and
  developer-guide documentation is built. If enabled, CMake will
  generate these guides as PDFs in the *doc* subdirectory of the
  build.  To build the documentation, run

.. code-block:: console

  $ make doc

* **ENABLE_DOXYGEN [default: OFF]** |br|

  If enabled, CMake will verify that a suitable *doxygen* binary is
  available on the system and will add a target for generating
  Doxygen-style interface documentation from the FleCSI source code
  (``make doxygen``, which becomes a dependency of ``make doc``).

* **ENABLE_DOXYGEN_WARN** |br|
  This **deprecated** option is ignored for compatibility.

Miscellaneous options
---------------------

* **ENABLE_COVERAGE_BUILD [default: OFF]** |br|
  Enable build mode to determine the code coverage of the current set of
  unit tests. This is useful for continuous integration (CI) test analysis.

* **ENABLE_GRAPHVIZ [default: OFF]** |br|
  If enabled, support the use of `Graphviz <https://graphviz.org/>`_
  to produce graphical visualizations of a FleCSI program's control
  points and actions.

* **ENABLE_HDF5 [default: OFF]** |br|
  If enabled, support the use of `HDF5 <https://www.hdfgroup.org/>`_
  for checkpointing program state.

* **CALIPER_DETAIL [default: none]** |br|
  A choice from ``none``, ``low``, ``medium``, and ``high`` to control which Caliper annotations are active.
  With ``none``, Caliper is not a dependency.

* **ENABLE_UNIT_TESTS [default: OFF]** |br|
  Enable FleCSI unit tests. If enabled, the unit test suite can be run
  by invoking:

.. code-block:: console

  $ make test

* **FLECSI_ID_TYPE [default: std::uint32_t]** |br|
  Specify the C++ type for FleCSI topologies to use for entity IDs.