diff --git a/docs/Build.rst b/docs/Build.rst index 98cf394..8c74ebb 100755 --- a/docs/Build.rst +++ b/docs/Build.rst @@ -1,298 +1,302 @@ =========================== Building the RoSA Framework =========================== .. contents:: :local: 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. Build Dependencies ================== In order to build RoSA, the following tools are required: * `CMake `_ (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. The following additional tools are required to generate documentation: * `Doxygen `_ -- for generating API documentation; * `Graphviz `_ -- not necessary, but the API documentation has nicer graphics when `dot` is available; * `Sphinx `_ (with *Python 2*) -- for generating documentation. The following additional tools are required to check and possibly enforce coding standard: * `clang-tidy `_ * `clang-format `_ +.. _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`. 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. `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__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` 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. `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. `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` 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. `ROSA_LOG_LEVEL` Select 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. `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. `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. The framework compiles with *Clang 3.8.0*. 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. You need to have RoSA sources on your computer and Clang executables available via `PATH`.:: rosa-src$ cd .. $ mkdir rosa-build $ cd rosa-build rosa-build$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DROSA_LOG_LEVEL="4" ../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`. + 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. There are two alternatives to do that: * using the *Clang/C2* module for *Visual Studio 2017*, * using *LLVM for Windows* as an external toolset for Visual Studio (necessary for older versions of Visual Studio). For using Visual Studio 2017 -- which would be the preferred way -- one needs to select *Clang/C2 (experimental)* on the *Individual components* tab in *Visual Studio Installer*. 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 versions between 2010 and 2014 (as of LLVM 4.0.0). 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`): * Clang/C2 with VS2017: `v141_clang_c2`. * LLVM for Windows with older VS: `LLVM-vs`. #. 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*. #. Fix the generated Visual Studio projects (*applies for Clang/C2*): * The generated projects define `ExceptionHandling` as `Sync`, which is an invalid value for Clang/C2 and needs to be changed to `Enabled` in all Visual Studio project files: * using GNU command line tools:: rosa-build$ find . -name "*.vcxproj" -print|xargs sed -i -e 's/Sync/Enabled/g' * using PowerShell:: rosa-build> ls -path . -include *.vcxproj -recurse | %{ $f=$_; (gc $f.PSPath) | %{ $_ -replace "Sync", "Enabled" } | sc $f.PSPath } * Note that the project files need to be fixed every time CMake regenerates them, which may happen when building the project in Visual Studio in case you have the CMake project changed in the source directory. #. 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. Should you use Clang/C2, do not forget to fix the newly generated Visual Studio project files as described above. diff --git a/docs/Dev.rst b/docs/Dev.rst index 2a4a852..939dcb3 100755 --- a/docs/Dev.rst +++ b/docs/Dev.rst @@ -1,42 +1,62 @@ -=============== -Developing RoSA -=============== +============================= +Developing the RoSA Framework +============================= .. contents:: :local: + +* Coding Style +* Documentation + + * General docs + + * Sphinx + * man pages for tools! + + * API + + * Doxygen + * doc namespaces + +* When and how to update CMake project + + * header files and source files + * adding libraries, executables + + Using YCM ========= If you happen to use `YCM `_, just make a copy of the provided `ycm_extra_conf.py.template` file as `.ycm_extra_conf.py` in the RoSA source directory, and set the following two variables in it: `compilation_database_folder` the absolute path of your build directory `extra_system_include_dirs` any system include directory which might not be searched by `libclang` [1]_. You probably want compile with Clang if you use YCM, so run CMake with environment variables `CC=clang` and `CXX=clang++` set. Also note that header files in the `include` directory are compiled for YCM with the compiler flags of a corresponding source file in the `lib` directory, if any. Header files in other locations are supposed to have a corresponding source file in the same directory. Notes ----- * If the project's include directory (`include/rosa`) would ever be changed, then the YCM configuration file needs to be adjusted accordingly. ---- .. [1] See: https://github.com/Valloric/YouCompleteMe/issues/303; use the following command to figure out the used system directories: echo | clang -std=c++11 -v -E -x c++ - diff --git a/docs/Plan.rst b/docs/Plan.rst index 3e27fa1..4186236 100755 --- a/docs/Plan.rst +++ b/docs/Plan.rst @@ -1,15 +1,17 @@ -=========== -Future Work -=========== +================================= +Future Work on the RoSA Framework +================================= .. contents:: :local: TODO ==== * Project logo - `docs/_themes/rosa-theme/static/logo.png` * API documentation welcome - `docs/doxygen-mainpage.dox` * Documentation index - `docs/index.rst` +* Complete initial docs... * Fix rules in `.clang-format` +* What about testing? diff --git a/docs/Release.rst b/docs/Release.rst new file mode 100755 index 0000000..cd300e6 --- /dev/null +++ b/docs/Release.rst @@ -0,0 +1,21 @@ +============================================= +Releasing a new version of the RoSA Framework +============================================= + +.. contents:: + :local: + +* what to check + + * coding standard + * build and execute on supported platforms with supported toolsets + +* generate the release + + * step version number -- CMake, Sphinx conf + * tag + * generate docs + * generate source package + * generate binary packages for supported platforms + * publish on website... + diff --git a/docs/Use.rst b/docs/Use.rst new file mode 100755 index 0000000..d3123d2 --- /dev/null +++ b/docs/Use.rst @@ -0,0 +1,10 @@ +======================== +Using the RoSA Framework +======================== + +.. contents:: + :local: + +* build it on your own vs use a binary release +* how to set up a standalone project (especially VS) + diff --git a/docs/index.rst b/docs/index.rst index bbb6745..eee93a0 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,30 +1,48 @@ Overview ======== TODO Overview of RoSA... Documentation ============= .. toctree:: :hidden: + Use Build Dev + Release Plan CommandGuide/index +:doc:`Use` + Describes how to create your own software based on RoSA. + :doc:`Build` - Discusses how to build RoSA. + Describes how to build RoSA. :doc:`Dev` - Provides basic information for developers on how to use RoSA. + Provides basic information for developers on how to contribute to RoSA. + +:doc:`Release` + Describes for maintainers how to make a new release of RoSA. :doc:`Plan` - Plans on future work and possible ways to develop RoSA. + Discusses future work and possible ways to develop RoSA. + +API Documentation +================= + +For details of the provided interface, refer to our `Doxygen documentation`_. + +.. + Relative address to doxygen docs in the build directory, + TODO: adjust it for the website once having one. +.. _Doxygen documentation: ../doxygen/html/index.html Indices and tables ================== * :ref:`genindex` * :ref:`search`