Compiling HelenOS From Source

This section explains how to compile HelenOS from latest source code.

Attention

This method is not recommended for beginners.

If you are running HelenOS for the first time, please run a pre-built, supported HelenOS image (see instructions in that article).

Compiling an operating system is not quite as simple as running the common configure && make && make install combo you use to compile your favorite application. If you still want to do it, please follow these instructions very carefully. If you skip parts of these instructions without knowing exactly what you are doing, it won't compile (or it will not run). We are happy to help with actual problems, but please don't bother us on the mailing list with fake issues caused by not following these instructions. For example, if you choose not to install our fine compiler toolchain, then please don't expect that the compilation process of HelenOS should magically work without it.

1. Get the sources

Checkout the latest sources from our central Git repository

$ git clone https://github.com/HelenOS/helenos.git HelenOS

2. Build a supported cross-compiler

Use our script to install a supported cross-compiler toolchain. By default, the script installs the cross-compiler to the $XDG_DATA_HOME/HelenOS/cross (i.e. $HOME/.local/share/HelenOS/cross) directory and therefore can be run as the normal user. To install the cross-compiler to the /opt/HelenOS/cross system-wide directory, run the script with the --system-wide option (this requires running the script as the root user). Alternatively, you cat set the $CROSS_PREFIX environment variable to use custom toolchain installation directory.

$ cd HelenOS/tools
$ ./toolchain.sh amd64

The toolchain script will print a list of software packages that are required for the toolchain to correctly build. Make sure you install all the dependencies. Unfortunately, the script cannot install the required dependencies for you automatically since the host environments are very diverse. In case the compilation of the toolchain fails half way through, try to analyze the error message(s), add appropriate missing dependencies and try again.

As an example, here are some of the packages you will need for Ubuntu 16.04:

$ sudo apt install build-essential wget texinfo flex bison dialog python-yaml genisoimage

Whereas for CentOS/Fedora, you will need:

# yum group install 'Development Tools'
# yum install wget texinfo PyYAML genisoimage flex bison

In case the toolchain script won't work no matter how hard you try, let us know. Please supply as much relevant information as possible (your OS and distribution, list of installed packages with version information, the output of the toolchain script, etc.).

3. Did you install the compiler toolchain? Good.

If you did not, it won't work! You can't use the default compiler installed on your system to build HelenOS. Don't even try to pester us about that. It won't work. Because it won't. It can't.

Why it can't work?

• Tool versions: We only test HelenOS on the one single version of GCC, binutils, etc. We don't have the resources to test other versions. Other versions have bugs (or lack required features), experimental modifications that break HelenOS, etc. It won't compile.
• Different ABIs: Each OS has a different ABI and different set of compiler settings. If you build binaries with your native compiler, they will run fine in your OS, but certainly not in HelenOS!
• -Werror: Developer builds use -Werror and each compiler version produces different warnings. Thus, you will get warnings and these get turned into errors.

4. Configure and build

Since mid-2019, HelenOS uses the Meson build system. Make sure you have a recent-enough version of Meson and Ninja. The safest bet is installing both using pip3 tool.

$ pip3 install ninja
$ pip3 install meson

Meson version 0.53.0 is broken. Do not use it. Any other recent version should be fine.

Meson does not support in-tree builds, so you have to create a directory for your build. You can have as many build directories as you want, each with its own configuration. cd into your build directory and run configure.sh script which exists in the source root. configure.sh can be run with a profile name, to use one of the predefined profiles, or without arguments for interactive configuration.

$ cd HelenOS
$ mkdir -p ../HelenOS-build/amd64
$ cd ../HelenOS-build/amd64
$ ../../HelenOS/configure.sh amd64

Note: If you installed the toolchain to a custom directory, make sure CROSS_PREFIX environment variable is correctly set.

Once configuration is finished, use ninja to build HelenOS. Invoking ninja without arguments builds all binaries and debug files, but not bootable image. This is because during development, most builds are incremental and only meant to check that code builds properly. In this case, the time-consuming process of creating a boot image is not useful and takes most time. This behavior might change in the future.

In case you want to rebuild the bootable image, you must invoke ninja image_path. This also emits the name of the bootable image into the file image_path in build directory.

$ ninja
$ ninja image_path

Now HelenOS should automatically start building.

5. Run it

When you get the command line back, there should be an image.iso file in the root of the build directory. If you have QEMU, you should be able to start HelenOS by running

$ qemu-system-x86_64 -m 256 -boot d -cdrom image.iso

If you want to use network, you may add other parameters or, preferably, you shall use a helper script that adds all these parameters for you and sets-up even the port forwarding:

$ ./tools/ew.py

For additional information about running HelenOS, see UsersGuide/RunningInQEMU or UsersGuide/RunningInVirtualBox or see the files in contrib/conf.

Advanced Topics

Building all predefined profiles

First, you need to build all required cross-compiler targets. The toolchain.sh script makes this easy.

Remember to set your CROSS_PREFIX variable if you want non-default location.

$ cd HelenOS/tools
$ ./toolchain.sh essential

Next, create a directory in which you want build files to be created.

$ cd HelenOS
$ mkdir ../HelenOS-build-all
$ cd ../HelenOS-build-all

To run the build, use tools/build_all.sh.

$ ../HelenOS/tools/build_all.sh

Now wait for all profiles to be configured and built. This is the recommended way to check all default (supported) configurations.

If you are lazy, you can run tools/build_all.sh right in the source directory.

$ cd HelenOS
$ tools/build_all.sh

This will build everything in a build_all subdirectory in the source directory, as a special case.

Which profiles are available?

To list all predefined profiles, run tools/list_profiles.sh.

As of mid-2019 the list is:

amd64
arm32/beagleboardxm
arm32/beaglebone
arm32/gta02
arm32/integratorcp
arm32/raspberrypi
arm64/virt
ia32
ia64/i460GX
ia64/ski
mips32/malta-be
mips32/malta-le
mips32/msim
ppc32
riscv64
sparc64/niagara
sparc64/ultra
special/abs32le

Manual Configuration

Please Note: Normally you don't need to do this. Manual configuration was mostly used in the past where HelenOS had no command line. Nowadays manual configuration (and configuration options in general) are used much less and only when absolutely necessary (e.g. if you really need to build a smaller system). If you configure HelenOS manually and it does not build (or does not work), you probably hit a combination of the configuration options that nobody tested properly. In that case you should file a bug.

With manual configuration you can change the initial screen resolution, disable building of some components, etc.

To configure:

$ cd HelenOS-build
$ ../HelenOS/configure.sh   # Interactive configuration
$ ninja                     # Build code
$ ninja image_path          # Build boot image

alternatively

$ cd HelenOS-build
$ ../HelenOS/configure.sh profile
$ ninja config              # Interactive configuration
$ ninja                     # Build code
$ ninja image_path          # Build boot image

You can change configuration at any time, and the build system should be able to resolve all necessary rebuilds automatically. Note however that you cannot change target platform/machine type once the initial configuration is finished. To build for a different device, you need to create a new build directory for it.

Building release files

This procedure is used to create HelenOS realease files before releasing a new HelenOS version, or for simulating that process. The resulting system image is based on one of the predefined configuration profiles (as opposed to the current configuration).

Before building release files make sure you have no uncommitted changes. These would get incorporated into the release.

To build all release files, create a build directory and run:

$ path/to/HelenOS/tools/release.sh