added common docs
This commit is contained in:
parent
338e7eed56
commit
a81cd732b1
76
docs/README-cmake.md
Normal file
76
docs/README-cmake.md
Normal 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
190
docs/README-eclipse.md
Normal 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 → 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 → Preferences → MCU → 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 → C/C++ General → 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 → C/C++ Build → Tool Chain Editor and set the correct
|
||||
editor. Then go to Properties → C/C++ Build → 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 → Import → 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 → 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 →
|
||||
C/C++ Build → 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 → 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 → Perspective → 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 → Debug Configurations → 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 → Import → 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.
|
||||
Loading…
x
Reference in New Issue
Block a user