fsfw/fsfw-example-common
12
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

added common docs

Browse Source
This commit is contained in:
Robin Müller 2021-06-08 17:45:18 +02:00
parent 338e7eed56
commit a81cd732b1
No known key found for this signature in database
GPG Key ID: 71B58F8A3CDFA9AC
2 changed files with 266 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
docs/README-cmake.md Normal file
View File

@ -0,0 +1,76 @@
<img align="center" src="./images/cmake.png" width="25%">
<sub><sup>Image taken from [Wikipedia](https://commons.wikimedia.org/wiki/File:Cmake.svg)
and licensed under [Creative Commons 2.0](https://creativecommons.org/licenses/by/2.0/deed.en),
no changes made</sup></sub>
CMake is a modern cross-platform build system which is able to generate
various build systems. It also features a dependency management system which
allows developers to operate on targets (e.g. compile target as a library, link
against a target) which allows better control of build properties compared
to tools like Make.
## Building with CMake
Generally, building software with CMake is a two-step process.
First, the build configuration is set up using the CMake build system or IDE project
generators and then the software is built using the select build system or IDE.
CMake projects are generally built out-of-source which means that the files generated
during the build process are kept separately from the source tree. This generally involves
creating a build folder like `Debug` or `Release` and then performing all
steps inside that folder.
It is also possible to generate IDE project files with CMake. This is
not recommended for Eclipse because the CDT generation is not very good.
Instead, it is recommended to configure the build system once in the command line and then
invoke the CMake build command from Eclipse.
Script files were supplied in the `buildsystem` folder to have a starting point.
It is also possible to generate Visual Studio files but this has not been tested extensively yet.
It is possible to perform the build configuration steps with the
`cmake-gui` or with the curses `ccmake` command line utility. This also provides a graphical displayed
of available options and variables.
## Build Configuration options in CMake
Call `cmake --help` to get a first overview of how the CMake build configuration
works. Generally, build options can be displayed by running following command:
```sh
cmake -LA <path-to-source>
```
The general form to configure a build system is to call this command
in the folder where the build system should be set up (this is generally not
in a separate folder to avoid pollution of the source tree).
The generators for the host system can be displayed with `cmake --help` as well
and are supplied with `-G` to the build configuration.
Please note that the OSAL and architecture specific READMEs contain the
explicit commands to configure the build systems correctly.
```sh
cmake -G <Build Generator> <Options and Defines> <path-to-source>
```
Following build configurations are possible by setting the `CMAKE_BUILD_TYPE`
string when configuring the build system. Supply `-DCMAKE_BUILD_TYPE=<option>`
to do this:
1. `None`: No flags added
1. `Debug`: Default type if no build type is specified
2. `RelWithDebInfo`: Release build, but debug symbols included
3. `MinSizeRel`: Build for minimum size
4. `Release`: Build for maximum speed
For more information, see the [CMake website](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/Useful-Variables#compilers-and-tools)
The FSFW OSAL can be specified with the `OS_FSFW` define during build configuration
Supply `-DOS_FSFW=<option>` to the configuration to do this.
Possible options are:
1. `host`: Host OSAL, tested for Windows 10 and Linux (Ubuntu 20.04)
2. `linux`: Linux OSAL, tested for regular Linux (Ubuntu 20.04) and embedded Linux
3. `freertos`: FreeRTOS OSAL, example for the STM32H743ZI-Nucleo development board provided.
4. `rtems`: Currently, no example provided, but will be provided for STM32H743ZI-Nucleo board.

190
docs/README-eclipse.md Normal file
View File

@ -0,0 +1,190 @@
<img align="center" src="./images/eclipse_logo_colour.png" width="30%">
<sub><sup>Image taken from [Eclipse website](https://www.eclipse.org/artwork/)</sup></sub>
Eclipse is a general purpose IDE, which was initially developed for Java
but has evolved to be used for C/C++ as well. It is the recommended IDE
to develop Software with the FSFW because it is cross-platform, provides
useful features like an indexer and can be configured with moderate effort
to use the Make and CMake build systems.
## Setting up Eclipse - General
Eclipse project files and launch configurations were provided to have a starting
point for application development with Eclipse. It is recommended to use those
files and delete unneeded run configurations manually.
There are separate project files to either use the Makefiles or CMake.
1. Install [Eclipse for C/C++](https://www.eclipse.org/downloads/packages/)
using the installer. Install the Eclipse MCU plugin
for the STM32 and Raspberry Pi example by going to Help &rarr; Eclipse
Marketplace and searching and installing the plugin
2. For the STM32, the ARM toolchain (and Windows Build Tools on Windows) should have been
installed previously. Go to Window &rarr; Preferences &rarr; MCU &rarr; Global ARM Toolchain
and Windows Build Tools. Packages installed with xpm should be recognized automatically.
3. Setting up the indexer: It is recommended to use the separate indexers for
each run configurations. Right click on the project folder in the tree view,
go to Properties &rarr; C/C++ General &rarr; Indexer and set the indexer as shown below.
<img align="center" src="./images/eclipse/eclipse-indexer.png" width="50%">
4. Cross-Compiling: In general, the provided project configurations should set up
the cross compiler properly. However, if there are issues, the user should
check whether the compilers are set up properly.
Right click on the project folder in the tree view, go to
Properties &rarr; C/C++ Build &rarr; Tool Chain Editor and set the correct
editor. Then go to Properties &rarr; C/C++ Build &rarr; Settings and check
whether the cross-compiler paths are correct.
## Setting up Eclipse for a hosted CMake projects
1. Copy the files `.project` and `.cproject` inside the misc/eclipse/make folder
into the root of the cloned folder. This will add all build configurations.
```sh
cd fsfw_example
cp misc/eclipse/cmake/.project .
cp misc/eclipse/cmake/.cproject .
```
2. Import the project now by going to File &rarr; Import &rarr; Existing Projects and selecting the cloned folder.
Only check the root folder, Eclipse will try to import every folder which contains
`.project` or `.cproject` files!
<img src="./images/eclipse_cfg.PNG" width="50%">
3. Set up the build folders. Helper scripts have been provided to perform this
task and have a starting point, but a valid Python 3 installation is required for them to work.
For example, to create the build folder `Debug` and build the software
with the FSFW Host OSAL on Windows or Linux, perform the following steps in the MinGW64
command line or Linux terminal after navigating into the cloned example folder:
```sh
cd buildsystem/cmake/scripts/Host
./create_cmake_debug_cfg.sh
```
The shell script can also be run by double clicking it in Windows as long as it is executed
by the MinGW terminal. This shell script will first create a new Debug folder (and delete the old one)
and then execute the following command in the Debug folder on Windows
```sh
cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug -DOS_FSFW=host
```
or the following command on Linux:
```sh
cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DOS_FSFW=host
```
For example, the execution of the script in MinGW64 on Windows should show the
following output:
<img src="./images/build_cfg_mingw.PNG" width="50%">
4. The build system is now ready to be used in Eclipse. Select the `fsfw-mingw-debug-cmake` (Windows)
or `fsfw-linux-debug-cmake` (Linux) launch configuration
in Eclipse and press the hammer button to build the software or the bug button to debug the
software for a host machine. This will invoke `cmake --build . -j` in the respective build
folders to build the software.
## Seting up Eclipse for Raspberry Pi projects - Remote Application
Eclipse is configured to assume that the toolchain is located in `/opt/cross-pi-gcc/bin` and
will deduce settings and compiler specs automatically (e.g. for the indexer) if the provides build
and launch configurations are used. Adapt the toolchain path accordingly if is installed
somewhere else.
Follow steps one and two of the previous section.
3. Set up the run configuration properly by setting up a SSH connection with
your Raspberry Pi. Go to Run &rarr; Debug Configurations.., look for the
`C/C++ Remote Application` section and click on one of the configurations
provided for the Raspberry Pi. A new SSH connection should be set up here.
The following image shows an example
<img src="./images/eclipse/eclipse-rpi.png" width="50%">
4. Set up the build folders if this was not done already.
We are going to do this with the script
```sh
cd buildsystem/cmake/scripts/RPi
./create_cmake_debug_cfg.sh
```
5. The build system is now ready to be used in Eclipse.
Select the `fsfw-rpi-debug-cmake` launch configuration and press the run or
debug button in the top panel on the right side to run or debug the application.
If there are issues, ensure that the Launch Configuration uses the correct
SSH settings to connect to the Raspberry Pi.
On Windows, MinGW Makefiles are used for the cross-compilation process, but Eclipse will only
have the Windows environmental variables cached. This can lead to issues with the CMake build if it
is configured in MinGW64. It is recommended to add the `RASPBIAN_ROOTFS` and the `RASPBERRY_VERSION`
variable to the Windows environmental variables.
The following picture shows an example:
<img src="./images/eclipse/rpi-win-environment.PNG" width="50%">
Alternatively, you can also add them to the Eclipse environmental variables in Properties &rarr;
C/C++ Build &rarr; Environment
## Setting up Eclipse for Raspberry Pi projects - TCF agent
Alternatively, the [TCF agent](https://wiki.eclipse.org/TCF) can be used
as a more generic and powerful tool to perform remote debugging.
1. Install the TCF agent plugin in Eclipse from the
[releases](https://www.eclipse.org/tcf/downloads.php). Go to
Help &rarr; Install New Software and use the download page, for
example https://download.eclipse.org/tools/tcf/releases/1.6/1.6.2/ to search
for the plugin and install it.
2. Go to Window &rarr; Perspective &rarr; Open Perspective and open the
**Target Explorer Perspective**. Here, the Raspberry Pi should show up if
the TCF agent has been set up on the Raspberry Pi as specified
[here](https://wiki.eclipse.org/TCF/Raspberry_Pi) or in the
respective [README](README-rpi.md#top). Connect to it.
3. Create a new **TCF Remote Application**. No launch configuration has
been provided because the IP address can change regularly.
- Create a new the configuration by pressing the cogs button at the top or
going to Run &rarr; Debug Configurations &rarr; Remote Application and
creating a new one there.
- Select the TCF connection, the correct image in the main tab (it might be
necessary to send it the the Raspberry Pi manually once) and file transfer properties
- It is also recommended to link the correct Eclipse project.
After that, comfortable remote debugging should be possible with the Debug button.
## Setting up Eclipse for the Makefile projects
The Makefiles are not maintained anymore and it is recommended to use the
CMake build configurations instead.
1. Copy the files `.project` and `.cproject` inside the misc/eclipse/make folder
into the root of the cloned folder. This will add all build configurations.
Configurations which are not required can be deleted manually.
```sh
cd fsfw_example
cp misc/eclipse/make/.project .
cp misc/eclipse/make/.cproject .
```
2. Import the project now by going to File &rarr; Import &rarr; Existing Projects and selecting
the cloned folder.
3. It should now be possible to build and debug the program by selecting the
correct launch configuration in the top panel and hitting the hammer or debug button.