Genode Porting Guide: Porting third-party code to Genode

Porting an existing program or library to Genode is for the most part a straight-forward task and depends mainly on the complexity of the program itself. Genode provides a fairly complete libc based on FreeBSD's libc whose functionality can be extended by so-called libc plugins. If the program one wants to port solely uses standard libc functions, porting becomes easy. Every porting task involves usually the same steps which are outlined below.

Steps in porting applications to Genode

1. Check requirements/dependencies (e.g. on Linux)

   The first step is gathering information about the application, e.g. what functionality needs to be provided by the target system and which libraries does it use.

2. Create a port file

   Prepare the source code of the application for the use within Genode. The Genode build-system infrastructure uses fetch rules, so called port files, which declare where the source is obtained from, what patches are applied to the source code, and where the source code will be stored and configured.

3. Check platform dependent code and create stub code

   This step may require changes to the original source code of the application to be compilable for Genode. At this point, it is not necessary to provide a working implementation for required functions. Just creating stubs of the various functions is fine.

4. Create build-description file

   To compile the application we need build rules. Within these rules we also declare all dependencies (e.g. libraries) that are needed by it. The location of these rules depends on the type of the application. Normal programs on one hand use a target.mk file, which is located in the program directory (e.g. src/app/foobar) within a given Genode repository. Libraries on the other hand use one or more <library-name>.mk files that are placed in the lib/mk directory of a Genode repository. In addition, libraries have to provide import-<library-name>.mk files. Amongst other things, these files are used by applications to find the associated header files of a library. The import files are placed in the lib/import directory.

5. Create a run script to ease testing

   To ease the testing of applications, it is reasonable to write a run script that creates a test scenario for the application. This run script is used to automatically build all components of the Genode OS framework that are needed to run the application as well as the application itself. Testing the application on any of the kernels supported by Genode becomes just a matter of executing the run script.

6. Compile the application

   The ported application is compiled from within the respective build directory like any other application or component of Genode. The build system of Genode uses the build rules created in the fourth step.

7. Run the application

   While porting an application, easy testing is crucial. By using the run script that was written in the fifth step we reduce the effort.

8. Debug the application

   In most cases, a ported application does not work right away. We have to debug misbehaviour and implement certain functionality in the platform-depending parts of the application so that is can run on Genode. There are several facilities available on Genode that help in the process. These are different on each Genode platform but basically break down to using either a kernel debugger (e.g., JDB on Fiasco.OC) or gdb(1). The reader of this guide is advised to take a look at the "User-level debugging on Genode via GDB" documentation.

The order of step 1-4 is not mandatory but is somewhat natural.