= 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. 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 }}} {{{#!box type=warning 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 [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 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 `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 }}}