Getting started

This document contains an explanation on how to build entire operating system from source.

The project consists of two repositories:

  • ghost, main repository containing the source code

  • ghost-sysroot, a blueprint for the system root directory

The system root directory (sysroot) is a concept used in cross-compiling. Everything in this directory is written to the ramdisk, which is mounted as the root folder of the filesystem when the OS has started.

When cross-compiling libraries and applications on your host system, the headers and libraries from within this directory are used. This is required to seperate the host from our target.


  1. Clone ghost-sysroot to /ghost/sysroot

  2. Clone main repository anywhere (for example /ghost/source)

If you want to use a different folder, see the "Tips" section below.

Installing prerequisites

There are some pre-requisites that you need to install on your host system. Install the following dependencies:

  • apt-get update

  • apt-get install libmpfr-dev libgmp-dev libmpc-dev

  • apt-get install autoconf2.69 pkg-config xorriso grub-pc-bin

  • apt-get install make texinfo flex bison gcc g++ nasm

  • apt-get install asciidoc asciidoctor

You may need to export AUTOCONF=autoconf2.69 depending on your installation.

On Windows

The recommended way of building on Windows is using WSL (Windows Subsystem for Linux).

On Mac OS

There are quite some prerequisites, so probably setting up a Linux VM is easier. The least that has to be done to get it working on OS X is to install GCC, build libmpfr, libgmp and libmpc from source and prepare the environment properly.

Toolchain setup

Run the toolchain setup script It will attempt to do everything that is necessary to create the toolchain. Once the toolchain was built, add it to your PATH.


Usually all folders contain a which is a simple bash script that builds this specific part. Multiple targets can be specified:

./ clean all
On some systems while running, the configure scripts of some ports might hang at either "checking for suffix of executables" or "checking whether we are crosscompiling". Run killall conftest to get it running again.

The in the root directory will attempt to build all components in the correct order. For building yourself, the dependency order is:

  • ./libapi/

  • ./libc/

  • Build the required ports

  • ./applications/*/

  • ./kernel/

The ISO image is generated to the main folder as ghost.iso.

Library dependency

libapi is the lowest layer library that provides wrapping of system calls. On top of this is the libc that utilizes libapi. libuser builds on top of these and provides high-level functionalities.

Library Dependencies

Third-party software

To install third-party libraries, it is usually necessary to provide some parameters to the ./configure script:

  • --host=i686-ghost to set the correct host

  • --prefix=/system to install libraries to the correct folder

There is also a simplified port installation script in patches/ports that allows automatically downloads, patches and installs some third-party libraries.

Creating a bootable USB stick

You can create a bootable USB stick with the following steps.

  1. Convert the image.iso file to an .img

    hdiutil convert -format UDRO -o converted.img image.iso
  2. Find out which drive the USB stick is with

    diskutil list
  3. Unmount the disk

    diskutil unmountDisk /dev/diskN
  4. Write the image to the stick

    sudo dd if=converted.img of=/dev/rdiskN bs=1m
  5. Unmount it again

    diskutil unmountDisk /dev/diskN


  • To specify a different toolchain base directory, modify TOOLCHAIN_BASE, copy the to and specify the variable with an export.

  • While binutils and gcc are being built, the log output is redirected to a file named ghost-build.log in the respective build directory in the temporary folder. If the build fails for some reason, you should check this log file.