Abstract

Quick start to build Genode for Linux

The best starting point for exploring Genode is to run it on Linux. Make sure that your system satisfies the following requirements:

• GNU Make version 3.81 or newer installed

• libSDL-dev installed

Furthermore, you will need to install the official Genode toolchain, which you can download at http://genode.org/download/tool-chain. In the following, we assume that you downloaded, extracted, and entered the base directory of the Genode sources.

The Genode build system never touches the source tree but generates object files, libraries, and targets inside a build directory. We do not have a build directory yet. So let us create one:

1. Create a directory at the same level as the base/ directory:

    mkdir build
    cd build
   

2. Create a symbolic link for the Makefile that manages the build process:

    ln -s ../tool/builddir/build.mk Makefile
   

Now let us build the targets by simply issuing

 make

After the build process is successfully finished, you find the newly created binaries in the bin/ subdirectory. By default however, you won't find any exciting applications to play with. The Genode base system comes with only one real program called Core. Anyway, to see a lifesign of Genode, you may give Core a shot:

 cd bin
 ./core

As indicated by the debug output, Core tries to spawn the Init process, which does not exist yet.

Adding additional source-code repositories

To keep the Genode base system tidy and neat, the build system provides a way to implement non-basic Genode components outside the Genode source tree by incorporating additional source-code repositories into the build process. Examples of such additional source-code repository are the os and demo repositories. The os repository contains device drivers, fundamental services, and the Init process. The demo repository supplements the os repository with some components to graphically demonstrate the Genode concepts. You can tell the build system to incorporate these repositories into the build process by creating an etc/ subdirectory in your build directory and adding a configuration file called etc/build.conf with the following entry:

 REPOSITORIES = ../base-linux ../base ../os ../demo

If you now issue make again, you will see some additional targets such as init, nitpicker, timer, and fb_sdl are created.

When starting Core now, the debug output indicates that Core successfully spawns init, which fails to access its configuration file. You can cancel the execution of Core by pressing Control-C. As a starting point, you can use the configuration-file template supplied with the os repository:

 cp ../../os/config/linux_demo config

If you start Core again, you will get a more satisfying result. At least, you should see something colorful popping up.

Enabling experimental features

Some features of Genode are classified as experimental, in particular if their usage involves known risks. To enable experimental features, add a file called specs.conf with the following content to the etc/ subdirectory of your build directory:

 SPECS += experimental

Building during development

When using multiple source-code repositories, the overall build process may revisit a lot of targets and thus, give you some extra seconds to look bored on your screen. To improve the workflow during development, the Genode build system supports building subtrees of the sources. For example, by issuing

 make core server/nitpicker

The build system builds all targets found in the core and server/nitpicker source directories. As indicated by the build output, the build system revisits each library that is used by the target. This is very handy for developing libraries because instead of re-building your library and then your library- using program, you just build your program and that's it. This concept even works recursively, which means that libraries may depend on other libraries.

In practice, you won't ever need to build the whole tree but only the targets that you are interested in.

Controlling the verbosity of the build process

If you are venturesome enough to try understanding the inner workings of the build system in more detail, you can tell the build system to display each directory change by specifying

 make VERBOSE_DIR=

If you are interested in the arguments that are passed to each invocation of make, you can make them visible via

 make VERBOSE_MK=

Furthermore, you can observe each single shell-command invocation by specifying

 make VERBOSE=

Of course, you can combine these verboseness toggles for maximizing the noise.

Customizing your work flow

The etc/build.conf file in your build directory is not only useful for declaring the repositories to be included into the build process but it also enables you to customize your work flow. For example, if you happen to specify VERBOSE= to the build process at a regular basis, you can create a syntactical shortcut for this argument by adding the following snippet into your etc/build.conf file:

 ifeq ($(V),1)
 VERBOSE =
 endif

With this addition, you can use

 make V=1

to achieve the same effect as by using

 make VERBOSE=

During development, your may often restrict the build process to revisit only the targets that you are working on. For example, if only the targets within core, init, and drivers/framebuffer are of interest to your work:

 make core init drivers/framebuffer

As this list of targets grows, the manual specification of the targets becomes sufficiently inconvenient. You can alternatively specify the these targets by overriding the MAKECMDGOALS make variable in your etc/build.conf file:

 MAKECMDGOALS = init core drivers/framebuffer

Source tree directory layout

The Genode source tree has the following layout:

Creating targets and libraries

Target descriptions

A good starting point is to look at the Init target. The source code of Init is located at os/src/init/. In this directory, you will find a target description file named target.mk. This file contains the building instructions and it usually is very simple. The build process is controlled by defining the following variables.

Build variables to be defined by you

Specifying search locations

Library descriptions

In contrast to target descriptions that are scattered across the whole source tree, library descriptions are located at the central place lib/mk. Each library corresponds to a <libname>.mk file. The base of the description file is the name of the library. Therefore, there is no TARGET variable to be set. The source code locations are expressed as $(REP_DIR)-relative vpath commands.

Specializations

Building components for different platforms likely implicates portions of code that are tied to certain aspects of the target platform. For example, a target platform may be characterized by

• A kernel API such as L4v2, Linux, L4.sec,

• A hardware architecture such as x86, ARM, Coldfire,

• A certain hardware facility such as a custom device, or even

• Other properties such as software license requirements.

All these attributes express a specialization of the build process. The Genode build system provides a generic mechanism to handle such specializations.

The programmer of a software component knows the properties on which his software relies and thus, specifies these requirements in his build description file.

The user/customer/builder decides to build software for a specific platform and defines the platform specifics via the SPECS variable per build directory in etc/specs.conf. The default platform specification that you just used in Section Quick start to build Genode for Linux is located at base/etc/specs.conf.

Each <specname> in the SPECS variable instructs the build system to

• Include the make-rules of a corresponding base/mk/spec-<specname>.mk file. This enables us to customize the build process for each platform. For example, the spec-linux.mk file tells the build system to add Linux-specific include search directories and link the POSIX thread library to the target.

• Search for <libname>.mk files in the lib/mk/<specname>/ subdirectory. This way, we can provide alternative implementations of one and the same library interface for different platforms.

Before a target or library gets built, the build system checks if the REQUIRES entries of the build description file are satisfied by entries of the SPECS variable. The compilation is executed only if each entry in the REQUIRES variable is present in the SPECS variable as supplied by the build directory configuration.

Using a secondary source-code repository for your developments

A source-code repository is a directory tree with a layout that corresponds to the Genode source tree. The following directories are mandatory:

 lib/mk/
 src/
 include/