= Compiling HelenOS From Source =
[[PageOutline(2-3)]]

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

== Attention ==
{{{#!box type=warning
This method is not recommended for beginners.
}}}

If you are running HelenOS for the first time, please [UsersGuide/QuickStart 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. The script either needs to be run as the `root` user (because it will install the cross-compiler to the `/usr/local/cross` directory) or you need to 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 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 ==

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 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 source root 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 [wiki:UsersGuide/RunningInQEMU#Networking 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 [wiki:HowToFileABug 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
}}}