In order to build RoSA, the following tools are required:
* `CMake <https://cmake.org/>`_ (minimum version 3.15.0);
* Build system of your choice (`Ninja <https://ninja-build.org/>` is recommended for Linux) that can be targeted by CMake -- including a
- compiler supporting *C++17*.
+ compiler supporting *C++20*.
- * Clang/LLVM -- minimum version 5.0.0
+ * Clang/LLVM -- minimum version 9.0.0
- * A proper C++ standard library implementation is needed as well (e.g., `libstdc++` from GCC with minimum version 7)
+ * A proper C++ standard library implementation is needed as well (e.g., `libstdc++` from GCC with minimum version 7 should be enough for the library features used.)
- * Visual Studio 2017 -- minimum version 15.7
+ * Visual Studio 2017 -- minimum version 15.7 (check this!)
The following additional tools are required to generate documentation:
* `Doxygen <http://doxygen.org>`_ -- for generating API documentation;
* `Graphviz <http://www.graphviz.org/>`_ -- not necessary, but the API
documentation has nicer graphics when `dot` is available;
* `Sphinx <http://www.sphinx-doc.org/>`_ -- for generating documentation.
The following additional tools are required to check and possibly enforce coding
* The repository defines git submodules, which are necessary to build RoSA.
Initialize and update submodules before building.
* The framework is delivered with a CMake project, which can be used to generate
build projects to build the framework.
* The provided CMake project supports building in a dedicated build directory
either inside or outside of the RoSA source directory.
.. _doxygen-warnings:
* Doxygen warnings -- typically indicating actual errors -- are printed to
`stderr`, do check that when generating API documentation.
.. _cmake-variables:
CMake Variables
===============
Beyond the usual CMake variables, the following project-related options are
available:
`ROSA_INCLUDE_APPS`
Generate build targets for the defined RoSA applications. The option is a string that is a list of app names. All apps that are present in the option are built, others are ignored. All apps are built by default.
`ROSA_INCLUDE_TOOLS`
Generate build targets for RoSA tools. The tools are also built when the
option is set to `ON`, which is the default setting.
`ROSA_INCLUDE_EXAMPLES`
Generate build targets for RoSA examples. The examples are also built when the
option is set to `ON`, which is the default setting.
`ROSA_ENABLE_PEDANTIC`
Compile the framework with using `-pedantic` for GCC-compatible compilers,
otherwise ignored. The option defaults to `ON`.
`ROSA_ENABLE_ASSERTIONS`
Enable assertions for non-Debug builds, which defaults to `OFF`.
Note that assertions are always enabled for Debug builds and this option is
ignored for such builds.
.. _CMake_clang_tidy:
`ROSA_ENABLE_CLANG_TIDY`
Run *clang-tidy* checks when building RoSA, which defaults to `OFF`.
When the variable is enabled, build targets created by *Makefile* and *Ninja*
generators include calls for clang-tidy. Other generators ignore this option.
Note that CMake variables `CMAKE_<LANG>_CLANG_TIDY` are set when enabled.
Settings for clang-tidy are defined by the file `.clang-tidy` in the RoSA
source directory.
Consider the following options when the option is enabled:
`ROSA_CLANG_TIDY_PATH`
Custom path for `clang-tidy` executable.
In order to use clang-tidy, CMake needs to find the `clang-tidy`
executable. If `clang-tidy` to be used is available via `PATH`, just leave
the option empty -- which is default. Set the absolute path of the
directory containing the `clang-tidy` executable otherwise, in which case
no default path is searched for `clang-tidy`.
`ROSA_CLANG_TIDY_FIX`
Apply suggested clang-tidy fixes to the sources, which defaults to `OFF`.
Enable the option only if you know what you are doing.
.. _CMake_clang_format:
`ROSA_INCLUDE_CLANG_FORMAT` **[experimental]**
Generate build target -- `format-rosa` -- for formatting RoSA sources with
*clang-format*, which defatuls to `OFF`.
When the variable is enabled and *CMake is not running on a Windows host*, a
build target is generated which can be used to have all the RoSA sources
formatted with clang-format. Settings for clang-format are defined by the file
`.clang-format` in the RoSA source directory.
Note that executing build target `format-rosa` will reformat all the source
files *inplace*.
Consider the following option when a build target for clang-format is to be
generated:
`ROSA_CLANG_FORMAT_PATH`
Custom path for `clang-format` executable.
In order to use clang-format, CMake needs to find the `clang-format`
executable. If `clang-format` to be used is available via `PATH`, just
leave the option empty -- which is default. Set the absolute path of the
directory containing the `clang-format` executable otherwise, in which case
no default path is search for `clang-format`.
`ROSA_LOG_LEVEL`
Level of logging to be used, use one of the following valid integer values.
======== =========
Variable Log Level
======== =========
`0` `ERROR`
`1` `WARNING`
`2` `INFO`
`3` `DEBUG`
`4` `TRACE`
`5` *disabled*
======== =========
Level of logging defaults to *disabled*.
`ROSA_INCLUDE_DOCS`
Generate build targets for RoSA documentation, defaults to `ON`.
Note that the automatic execution of the generated build targets is
controlled by the option `ROSA_BUILD_DOCS`. The actual documentations to
build are controlled by the options `ROSA_ENABLE_DOXYGEN` and
`ROSA_ENABLE_SPHINX`.
`ROSA_BUILD_DOCS`
Build RoSA documentation automatically as part of the build process. The
option defaults to `OFF` and takes effect only if the option
`ROSA_INCLUDE_DOCS` is enabled.
.. _CMake_doxygen:
`ROSA_ENABLE_DOXYGEN`
Use *doxygen* to generate RoSA API documentation. The option defaults to `OFF`
and takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled.
Doxygen documentation may be generated by executing build target
`doxygen-rosa`, which is done as part of the default build process if
`ROSA_BUILD_DOCS` is enabled.
Doxygen must be available via `PATH` if the option is enabled.
The following options are also available to tune doxygen:
`ROSA_DOXYGEN_SVG`
Use *svg* instead of *png* files for doxygen graphs. The option defaults to
`OFF` and takes effect if the tool *dot* is available via `PATH` to be used
to generated graph images.
`ROSA_DOXYGEN_EXTERNAL_SEARCH`
Enable doxygen external search, which defatuls to `OFF`.
The following options need to be set if the option is enabled:
`ROSA_DOXYGEN_SEARCHENGINE_URL`
URL to use for external search.
`ROSA_DOXYGEN_SEARCH_MAPPINGS`
Doxygen Search Mappings.
.. _CMake_sphinx:
`ROSA_ENABLE_SPHINX`
Use *Sphinx* to generate RoSA documentation. The option defaults to `OFF` and
takes effect only if the option `ROSA_INCLUDE_DOCS` is enabled.
Sphinx must be available via `PATH` if the option is enabled.
The following options are also available to tune Sphinx:
`SPHINX_OUTPUT_HTML`
Output standalone HTML files. The option defaults to `ON`.
Documentation may be generated by executing build target `docs-rosa-html`,
which is done as part of the default build process if `ROSA_BUILD_DOCS` is
enabled.
`SPHINX_OUTPUT_MAN`
Output man pages for RoSA applications and tools. The option defaults to
`ON`.
Man pages may be generated by executing build target `docs-rosa-man`, which
is done as part of the default build process if `ROSA_BUILD_DOCS` is
enabled.
`SPHINX_WARNINGS_AS_ERRORS`
When building documentation, treat Sphinx warnings as errors. The option
defaults to `ON`.
Building RoSA Step-by-Step
==========================
Building on Linux with Ninja
----------------------------
Configuring and building the framework on Linux using *Ninja* is a
straightforward process which does not require performing any tricks.
Set C and C++ compilers with the variables `CC` and `CXX`, respectively. Use the
CMake variable `CMAKE_BUILD_TYPE` to set the type of build: `Debug`, `Release`.
Follows an example on building the framework with all options turned on. CMake
variables may be skipped as necessary. You need to have RoSA sources on your