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 for the system

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

The system root directory (sysroot) is a concept used in cross compiling. It contains the initial filesystem that is used to boot the OS. All cross-compiled libraries and applications are installed to this folder, and when cross-compiling a program or library, the compiler uses this directory as the location to search for headers, libraries and more. This avoids using the host systems header files.

Checking out

  1. Clone the ghost-sysroot to /ghost/sysroot (If you want to use a different folder, see the "Tips" section below).

  2. Clone the main repository somewhere to your filesystem (for example /ghost/source)

Installing prerequisites

There are some pre-requisites that you need to install on your host system. On Linux you should be able to easily install them with apt;

  • apt update

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

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

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

  • apt install asciidoc asciidoctor

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

On Cygwin

The recommended way of building on Windows is using the Windows Subsystem for Linux. Install the required packages that are described above via the Cygwin setup, except:

  • autoconf2.64 must be built from source

  • xorriso must be built from source, install libiconv-devel in Cygwin setup beforehand. (It wants to be built & configured in the source directory)

  • grub2 must be built from source. Use grub-1.99 and do export TARGET_CFLAGS="-Wno-error" export CFLAGS="-Wno-error" before configure

On Mac OS

If you are on Mac OS X, you must make sure that the GNU GCC is used (default alias points to LLVM). Use export to set the correct version:

export CC=gcc-5
export CXX=g++-5
export CPP=cpp-5
export LD=gcc-5

Building the toolchain

Run the toolchain setup script It will attempt to do everything that is necessary to create the toolchain.

If the process fails on one step, open the respective build folder (for example temp/build-gcc) and check for a ghost-build.log file.

Once the toolchain was built, you might want to add it to your PATH.

When the script fails at some point but downloading/patching archives was successful, you can skip those steps with --skip-archives.

Building the system

There is a in the main folder that installs required libraries, builds all applications and then builds and packs the kernel.

On some systems while running, I had the problem that the configure script of some ports would hang at either "checking for suffix of executables" or "checking whether we are crosscompiling". Run killall conftest to get it running again.

For building manually, the essential order is:

  • ./libapi/

  • ./libc/

  • ./libuser/

  • ./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.