fsfw_example_public/doc/README-linux.md

# FSFW demo with the Linux OSAL

This demo can be run on a Linux host computer. The application can be built with Make or
with CMake. It is generally assumed that the application will still run on a host computer, 
so the `bsp_hosted` folder is used.

This demo still uses the Linux abstraction OSAL, so it is in principle possible
to compile it for embedded linux by setting the correct cross compiler by 
supplying `CROSS_COMPILE=<toolchain>` to the make command (however, a custom makefile 
is propably still necessary).

## Generical Information

These steps were tested for Ubuntu 20.04. Adapt accordingly for used
Linux distribution. If not done yet, install the full C++ build chain:

```sh
sudo apt-get install build-essential
```

Linux has a limit to message queue message. Please see the section 
to set up UNIX environment for more information.
Sometimes, special steps are necessary so the real-time functionalities can be used
without root privileges. Instructions are contained in the setup section
for UNIX as well.

## Building the software with CMake

CMake should be [installed](https://cmake.org/install/) first.
More detailed information on the CMake build process and options 
can be found in the [CMake README](README-cmake#top).
Readers unfamiliar with CMake should read this first. The following steps will show to to build
the Debug executable using the "Unix Makefiles" generator in the command line to be 
as generic as possible.

1. Clone the repository with
   ```sh
   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
   cd fsfw_example
   ```

2. Update all the submodules
   
   ```sh
   git submodule init
   git submodule update
   ```
   
3. Navigate into the cloned repository and create a folder for the build. We will create a    Debug build folder.

   ```sh
   mkdir build-Debug-Linux
   cd build-Debug-Linux
   ```
   
4. Create and configure the build system. The CMake default build system shoule be
   "Unix Makefiles" by default. If this is not the case, add `-G "Unix Makefiles` 
   to the command. Type `cmake --help` for more information.
   
   ```sh
   cmake -DOS_FSFW=linux -DCMAKE_BUILD_TYPE=Debug ..
   ```
   
   The build configuration can also be performed with the shell scripts located inside `cmake/scripts/Linux` or the Python helper script `cmake_build_config.py` inside `cmake/scripts`.
   The configured build options can now be shown with `cmake -L`.

5. Build the application
   ```sh
   cmake --build . -j
   ```
   The application will be located inside the Debug folder.

### Setting up Eclipse for CMake projects

The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse to build CMake projects. The debug output is colored by default. It is recommended to install the
`ANSI Escape in Console` plugin in Eclipse so the coloring works in the Eclipse console.

## Building the software with Make

1. Clone the repository with
   ```sh
   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
   cd fsfw_example
   ```

2. Update all the submodules
   
   ```sh
   git submodule init
   git submodule sync
   git submodule update
   ```

3. Copy the `Makefile-Linux` file in the `buildsystem/make` folder into the root folder 
   and rename it to `Makefile`
   
   ```sh
   cp buildsyste/make/Makefile-Linux .
   mv Makefile-Linux Makefile
   ```

3. After that, the linux binary can be built with:

   ```sh
   make -j all
   ```

   to compile for Linux. All will build the debug version,
   which can also be built with the target `debug`. The optimized
   release version can be built with the target `release`.

4. Run the binary located inside the `_bin` folder.

## Setting up UNIX environment for real-time functionalities
Please note that on most UNIX environments (e.g. Ubuntu), the real time functionalities 
used by the UNIX pthread module are restricted, which will lead to permission errors when creating these tasks
and configuring real-time properites like scheduling priorities.

To solve this issues, try following steps:

1. Edit the /etc/security/limits.conf 
file and add following lines at the end:
```sh
<username>   hard   rtprio  99
<username>   soft   rtprio  99
```
The soft limit can also be set in the console with `ulimit -Sr` if the hard
limit has been increased, but it is recommended to add it to the file as well for convenience.
If adding the second line is not desired for security reasons,
the soft limit needs to be set for each session. If using an IDE like eclipse 
in that case, the IDE needs to be started from the console after setting
the soft limit higher there. After adding the two lines to the file,
the computer needs to be restarted.

It is also recommended to perform the following change so that the unlockRealtime
script does not need to be run anymore each time. The following steps
raise the maximum allowed message queue length to a higher number permanently, which is 
required for some framework components. The recommended values for the new message
length is 130.

2. Edit the /etc/sysctl.conf file
```sh
sudo nano /etc/sysctl.conf
```
Append at end: 
```sh
fs/mqueue/msg_max = <newMsgMaxLen>
```
Apply changes with: 
```sh
sudo sysctl -p
```

A possible solution which only persists for the current session is
```sh
echo <newMsgMax> | sudo tee /proc/sys/fs/mqueue/msg_max
```
or running the `unlockRealtime` script.

3. Run the shell script inside the linux folder
```sh
./unlockRealtime
```
This script executes the `sudo setcap 'cap_sys_nice=eip' \<application\>`
command on the binaries, increases the soft real time limit of the current
session and increases the maximum number of message queues by setting
`/proc/sys/fs/mqueue/msg_max`.
All changes are only applied for the current session (read 2. and 3. for 
a permanent solution). If running the script before executing the binary does
not help or an warning is issue that the soft real time value is invalid, 
the hard real-time limit of the system might not be high enough (see step 1).