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 git@github.com:HelenOS/helenos.git HelenOS

If you do not have GitHub account (with public keys set), you may need to use HTTPS instead:

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

Note: To get versions up to 0.7.1 you have to access the abandoned Bazaar repository

$ bzr branch bzr://bzr.helenos.org/mainline HelenOS

Note: To get versions older than 0.4.1 you have to access the original Subversion repository

$ svn checkout svn://svn.helenos.org/HelenOS/trunk HelenOS

2. Build a supported cross-compiler

Use our script to install a supported cross-compiler toolchain. The script either needs to be run as the root user (because it will install the cross-compiler to the /usr/local/cross/ia32 directory) or you need to set the CROSS_PREFIX environment variable to use custom toolchain installation directory.

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

Note: In older revisions of the source tree the toolchain.sh script was present in the contrib directory (not the tools directory where it is now).

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 bison dialog python-yaml genisoimage

Whereas for CentOS/Fedora, you will need:

# yum group install 'Development Tools'
# yum install wget texinfo libmpc-devel mpfr-devel gmp-devel PyYAML genisoimage

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

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

Go back to the source root of HelenOS and start the build process

$ cd ..
$ make PROFILE=ia32

Now HelenOS should automatically start building.

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

5. Run it

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

$ qemu-system-i386 -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

Which profiles are available?

Look under the defaults/ directory. As of 2016-02-20 the list is:

amd64
arm32/beagleboardxm
arm32/beaglebone
arm32/gta02
arm32/integratorcp
arm32/raspberrypi
ia32
ia64/i460GX
ia64/ski
mips32/malta-be
mips32/malta-le
mips32/msim
ppc32
sparc32/leon3
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.

Warning: Do not select a different compiler unless you really know what you are doing! If you use gcc_native instead of gcc_cross, it won't work, so please don't ask in the mailing list! Building HelenOS with a native compiler is not supported!

To configure:

$ make distclean && make config

alternatively

$ make distclean && make

this will cause the HelenOS build to automatically start once you are done with the configuration.

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 will not be build since we are building from exported sources.

To build all release files go to the source root and run:

$ make release

To build an individual release file go to the source root and run:

$ make -C release release PROFILES=profile_name

This builds a release file (boot image / disk image) based on the specified configuration profile profile_name.