Page MenuHomePhorge
Files F10705433

Build.rst
No OneTemporary
Actions

Size
12 KB
Referenced Files
None
Subscribers
None

Build.rst
View Options

===========================
Building the RoSA Framework
===========================
.. contents::
:local:
Build Dependencies
==================
In order to build RoSA, the following tools are required:
* `CMake <https://cmake.org/>`_ (minimum version 3.6.0 if clang-tidy is used,
2.8.8 otherwise);
* Build system of your choice that can be targeted by CMake -- including a
compiler supporting *C++14*.
* Clang/LLVM -- minimum version 3.9.0
[#f-clang_template_argument_deduction_DeluxeAgent]_
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/>`_ (with *Python 2*) -- for generating
documentation.
The following additional tools are required to check and possibly enforce coding
standard:
* `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_
* `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_
General notes
=============
* 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 out-of-tree builds only, i.e. one must use
a separate build directory 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_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 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 Make
---------------------------
Configuring and building the framework on Linux using *Make* 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
computer.::
rosa-src$ cd ..
$ mkdir rosa-build
$ cd rosa-build
rosa-build$ CC=<clang-executable> CXX=<clang++-executable> <cmake-executable> -G "Unix Makefiles" -DROSA_ENABLE_CLANG_TIDY=ON -DROSA_CLANG_TIDY_PATH=<clang-tidy-execdir> -DROSA_INCLUDE_CLANG_FORMAT=ON -DROSA_CLANG_FORMAT_PATH=<clang-format-execdir> -DROSA_LOG_LEVEL=4 -DROSA_ENABLE_DOXYGEN=ON -DROSA_DOXYGEN_SVG=ON -DROSA_ENABLE_SPHINX=ON -DCMAKE_BUILD_TYPE=Debug ../rosa-src
[CMake configures and generates without errors]
$ make
[Make builds the project]
You just need to re-run Make in order to re-build the project after changing
the source code and the CMake project. In case the CMake project is changed,
Make automatically calls CMake to update the build project.
In order to build documentation and enforce coding standard, refer to
corresponding :ref:`cmake-variables`.
.. _Build_VS:
Building on Windows with Visual Studio
--------------------------------------
Unfortunately, the native MSVC compiler cannot compile the framework. One needs
to use Clang with Visual Studio in order to build the framework.
Microsoft recently started to bundle a special version of Clang to Visual Studio
as the *Clang/C2* module. That compiler is, however, several versions behind the
official LLVM releases as of Visual Studio 2017. Therefore, it is necessary to
use *LLVM for Windows* as an external toolset for Visual Studio.
For using *LLVM for Windows*, one downloads the official binary release from
http://llvm.org and consults with its documentation. The release provides
integration for Visual Studio starting from Visual Studio 2010.
Prepare your toolchain like this:
#. Install Visual Studio.
* If installing Visual Studio 2017, make sure the component
*VC++ 2015.3 v140 toolset (x86,x64)* on the *Individual components* tab is
selected in *Visual Studio Installer*. Installing the older *v140 toolset*
is necessary because the LLVM integration (as of version 4.0.1) does not
support the *v141 toolset*, which is default for Visual Studio 2017.
* Otherwise, default installation of Visual Studio should go.
#. Install *LLVM for Windows*.
#. Install the integration by executing as *Administrator*::
> <LLVM-install-dir>\tools\msbuild\install.bat
Having your build system prepared and RoSA sources fetched to your computer,
configure and build the framework like this:
#. Generate Visual Studio solution with CMake:
#. Start CMake.
#. Define *source directory* and a separate *build directory* in CMake.
#. Click *Configure*.
#. Select the proper *generator* for your version of Visual Studio.
#. Define your optional toolset (argument for `-T`) as `LLVM-vs<year>`.
* Note that `<year>` refers to the version of Visual Studio: `2010`,
`2012`, `2013`, and `2014`. Visual Studio 2017 with the *v140 toolset*
uses `2014`.
#. Click *Finish*.
#. Tune CMake variables as you wish.
* Note that Visual Studio Generators are multi-configuration generators,
hence you cannot set `CMAKE_BUILD_TYPE`. You need to select a
configuration to build in Visual Studio.
#. Click *Generate*.
#. Build the framework with Visual Studio:
#. Open the generated `RoSA.sln` from the build directory with Visual
Studio.
#. Build the project `ALL_BUILD`.
You just need to re-build the project in Visual Studio after changing the
source code and the CMake project.
In case the CMake project is changed, Visual Studio automatically calls CMake
the update the build project.
Build Result
============
The build process works in the build directory. After a successful build, one
can find the following final outputs there -- besides some intermediate files.
.. _Build_Result_Software:
Software
--------
In the build directory, `include` contains header files which are generated by
CMake and provide configuration-specific information.
The build process generates static libraries in `lib` and executables --
examples and tools -- in `bin`. Projects generated by a multi-configuration
generator result in the actual libraries and executables being located in
subdirectories corresponding to different build configurations.
.. _Build_Result_Documentation:
Documentation
-------------
Documentation is generated in `docs`.
The general documentation can be found in `docs/html`. Man pages for tools can
be found in `docs/man`.
The API documentation can be found in `docs/doxygen/html`.
.. rubric:: Footnotes
.. [#f-clang_template_argument_deduction_DeluxeAgent]
Clang breaks on template argument deduction when instantiating the class
`rosa::deluxe::DeluxeAgent`, the issue is gone with clang version 3.9.0 and
newer. Check the documentation on the relevant constructor for more details.

File Metadata

Mime Type
text/plain
Expires
Sun, May 31, 4:39 PM (1 d, 19 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
328501
Default Alt Text
Build.rst (12 KB)

Event Timeline