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
|