Robin Mueller
c2bf09d506
This PR introduces the generation of documentation based on this excellent blog post: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ It combines the tools Sphinx, Doxygen and Breathe to generate good looking HTML documentation conveniently which can be hosted easily. The helper scripts were unified and there is now one helper.py script which can be used to create, build and open both tests and documentation. "./helper.py -h" can be used to get the different options. This PR also contains some smaller fixes which were necessary for the docs to build
116 lines
4.5 KiB
ReStructuredText
116 lines
4.5 KiB
ReStructuredText
Getting Started
|
|
================
|
|
|
|
|
|
Getting started
|
|
----------------
|
|
|
|
The `Hosted FSFW example`_ provides a good starting point and a demo to see the FSFW capabilities.
|
|
It is recommended to get started by building and playing around with the demo application.
|
|
There are also other examples provided for all OSALs using the popular embedded platforms
|
|
Raspberry Pi, Beagle Bone Black and STM32H7.
|
|
|
|
Generally, the FSFW is included in a project by providing
|
|
a configuration folder, building the static library and linking against it.
|
|
There are some functions like ``printChar`` which are different depending on the target architecture
|
|
and need to be implemented by the mission developer.
|
|
|
|
A template configuration folder was provided and can be copied into the project root to have
|
|
a starting point. The [configuration section](docs/README-config.md#top) provides more specific
|
|
information about the possible options.
|
|
|
|
Adding the library
|
|
-------------------
|
|
|
|
The following steps show how to add and use FSFW components. It is still recommended to
|
|
try out the example mentioned above to get started, but the following steps show how to
|
|
add and link against the FSFW library in general.
|
|
|
|
1. Add this repository as a submodule
|
|
|
|
.. code-block:: console
|
|
|
|
git submodule add https://egit.irs.uni-stuttgart.de/fsfw/fsfw.git fsfw
|
|
|
|
2. Add the following directive inside the uppermost ``CMakeLists.txt`` file of your project
|
|
|
|
.. code-block:: cmake
|
|
|
|
add_subdirectory(fsfw)
|
|
|
|
3. Make sure to provide a configuration folder and supply the path to that folder with
|
|
the `FSFW_CONFIG_PATH` CMake variable from the uppermost `CMakeLists.txt` file.
|
|
It is also necessary to provide the `printChar` function. You can find an example
|
|
implementation for a hosted build
|
|
`here <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted/src/branch/master/bsp_hosted/utility/printChar.c>`_.
|
|
|
|
4. Link against the FSFW library
|
|
|
|
.. code-block:: cmake
|
|
|
|
target_link_libraries(<YourProjectName> PRIVATE fsfw)
|
|
|
|
|
|
5. It should now be possible use the FSFW as a static library from the user code.
|
|
|
|
Building the unittests
|
|
-------------------------
|
|
|
|
The FSFW also has unittests which use the `Catch2 library`_.
|
|
These are built by setting the CMake option ``FSFW_BUILD_UNITTESTS`` to ``ON`` or `TRUE`
|
|
from your project `CMakeLists.txt` file or from the command line.
|
|
|
|
The fsfw-tests binary will be built as part of the static library and dropped alongside it.
|
|
If the unittests are built, the library and the tests will be built with coverage information by
|
|
default. This can be disabled by setting the `FSFW_TESTS_COV_GEN` option to `OFF` or `FALSE`.
|
|
|
|
You can use the following commands inside the ``fsfw`` folder to set up the build system
|
|
|
|
.. code-block:: console
|
|
|
|
mkdir build-tests && cd build-tests
|
|
cmake -DFSFW_BUILD_UNITTESTS=ON -DFSFW_OSAL=host ..
|
|
|
|
|
|
You can also use ``-DFSFW_OSAL=linux`` on Linux systems.
|
|
|
|
Coverage data in HTML format can be generated using the `Code coverage`_ CMake module.
|
|
To build the unittests, run them and then generare the coverage data in this format,
|
|
the following command can be used inside the build directory after the build system was set up
|
|
|
|
.. code-block:: console
|
|
|
|
cmake --build . -- fsfw-tests_coverage -j
|
|
|
|
|
|
The ``helper.py`` script located in the ``script`` folder can also be used to create, build
|
|
and open the unittests conveniently. Try ``helper.py -h`` for more information.
|
|
|
|
Building the documentation
|
|
----------------------------
|
|
|
|
The FSFW documentation is built using the tools Sphinx, doxygen and breathe based on the
|
|
instructions provided in `this blogpost <https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/>`_. You can set up a
|
|
documentation build system using the following commands
|
|
|
|
.. code-block:: bash
|
|
|
|
mkdir build-docs && cd build-docs
|
|
cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host ..
|
|
|
|
Then you can generate the documentation using
|
|
|
|
.. code-block:: bash
|
|
|
|
cmake --build . -j
|
|
|
|
You can find the generated documentation inside the ``docs/sphinx`` folder inside the build
|
|
folder. Simply open the ``index.html`` in the webbrowser of your choice.
|
|
|
|
The ``helper.py`` script located in the ``script`` folder can also be used to create, build
|
|
and open the documentation conveniently. Try ``helper.py -h`` for more information.
|
|
|
|
.. _`Hosted FSFW example`: https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted
|
|
.. _`Catch2 library`: https://github.com/catchorg/Catch2
|
|
.. _`Code coverage`: https://github.com/bilke/cmake-modules/tree/master
|