Compiling HelenOS From Source
This section explains how to compile HelenOS from latest source code.
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
$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 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
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
$ 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
environment variable is correctly set.
Once configuration is finished, use
ninja to build HelenOS.
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
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:
Building all predefined profiles
First, you need to build all required cross-compiler targets.
toolchain.sh script makes this easy.
Remember to set your
CROSS_PREFIX variable if you want non-default location.
$ cd HelenOS/tools $ ./toolchain.sh all
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
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
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
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.
$ cd HelenOS-build $ ../HelenOS/configure.sh # Interactive configuration $ ninja # Build code $ ninja image_path # Build boot image
$ 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: