fsfw-example-common/doc/README-eclipse.md
2021-06-08 17:51:23 +02:00

191 lines
8.4 KiB
Markdown

<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 build 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.