sortix--sortix/doc/cross-development

Sortix Cross Development Guide
==============================

The primary way to build Sortix is on Sortix itself. However, the system may not
be fully up to the task yet and your favorite development environment may not
have been ported. You can cross-compile Sortix from a reasonable similar system
such as GNU+Linux. The build process will liberally use common GNU tool options,
so you may wish to install the basic GNU distribution or compatible.

Overview
--------

To build Sortix you need these components:

* Sortix source tree
* Sortix binutils
* Sortix gcc
* GRUB2 (iso support)
* xorriso (iso support)

In this tutorial we will cross-compile a Sortix using by following these steps:

1. Retrieve all the source code.
2. Build additional Sortix-specific tool programs.
3. Create a system root containing all the Sortix system headers.
4. Compile a new compiler that targets Sortix and uses the system root.
5. Actually compile Sortix.

It is necessary to compile binutils and gcc because your system compilers
doesn't produce executables for Sortix, but rather for your current system.

Source Code
-----------

You can find the latest Sortix source code at:
https://gitorious.org/sortix/sortix/

You can find the latest Sortix binutils source code at:
https://cs.au.dk/~sortie/sortix/toolchain/sortix-binutils-latest.tar.xz

You can find the latest Sortix gcc source code at:
https://cs.au.dk/~sortie/sortix/toolchain/sortix-gcc-latest.tar.xz

It is only possible to build Sortix with this blessed toolchain or a derivative
thereof as it has been customized to understand Sortix and provide a number of
useful extensions. You may need to occasionally upgrade the toolchain, in the
event that it is further modified and Sortix takes advantage of these changes.

Target Platform
---------------

You need to decide what the platform your final Sortix system will run on. You
can currently decide between i486-sortix and x86_64-sortix. In this guide we
will refer to that platform triplet as $SORTIX_PLATFORM. If you want to build
another platform afterwards, then you will have to follow this guide again.

Cross-Environment
-----------------

You should install your cross-toolchain into a useful and isolated directory
such as $HOME/opt/$SORTIX_PLATFORM. This allows you to easily dispose of the
directory and keeps it neatly isolated from the rest of the system. Let's refer
to that location as $CROSS_PREFIX.

You need to add $CROSS_PREFIX/bin to your $PATH variable:

  export PATH="$CROSS_PREFIX/bin:$PATH"

This will modify the $PATH variable in this particular shell session. Depending
on your shell and system configuration you can make this permanent by adding
that line to your ~/.profile. Consult your shell documentation. Otherwise type
it in all Sortix-related shells before doing anything.

Sortix build tools
------------------

You need to install some additional Sortix programs into your local environment
as they are needed to build Sortix. Assuming you cloned the Sortix source code
tree into the ~/sortix directory, you can install them by typing the following
commands:

  cd ~/sortix &&
  make PREFIX="$CROSS_PREFIX" build-tools &&
  make PREFIX="$CROSS_PREFIX" install-build-tools

These tools produce platform independent output so you may wish to install them
into $HOME/bin or /usr/local/bin or where it suits you in your $PATH.

Setting up basic system root
----------------------------

The compiler has been taught how to correctly build programs for a Sortix
system, however it gets part of this information from the system headers. The
first step is to create a basic system root that contains the headers and
filesystem structure for the final system. We will install the kernel, libc,
libm, and other core library headers into this directory. Run the following:

  cd ~/sortix &&
  make sysroot-base-headers HOST=$SORTIX_PLATFORM

This will automatically set up a basic system root in ~/sortix/sysroot. We will
use this when we build the cross-compiler in a moment. Let's call the system
root directory $SYSROOT.

Cross-Toolchain Dependencies
----------------------------

You may need to install these packages (and their development packages) before
building binutils and gcc, or the packages will refuse to configure or some
obscure error will occur. In particular, you may need to install:

* Bison
* Flex
* GNU GMP
* GNU MPFR
* GNU MPC

You should consult the official binutils and gcc documentation on what exactly
you need to install before building these packages yourself.

Cross-Binutils
--------------

We need a cross-binutils that have been taught the Sortix program format. If you
have extracted the Sortix binutils source code into ~/src/sortix-binutils then
you can build binutils out-of-directory using these commands:

  mkdir ~/src/binutils-build &&
  cd ~/src/binutils-build &&
  ../sortix-binutils/configure \
    --target=$SORTIX_PLATFORM \
    --with-sysroot="$SYSROOT" \
    --prefix="$CROSS_PREFIX" \
    --program-prefix=$SORTIX_PLATFORM- &&
  make &&
  make install

You may need to install some dependencies before you build binutils. You can
remove the temporary ~/src/binutils-build directory when you are done.

Cross-GCC
---------

We need a cross-compiler that has been taught what Sortix is and that supports a
few extensions that have been added to Sortix gcc that isn't present in upstream
gcc. If you have extracted the Sortix gcc source code into ~/src/sortix-gcc then
you can build gcc out-of-directory using these commands.

  mkdir ~/src/gcc-build &&
  cd ~/src/gcc-build &&
  ../sortix-gcc/configure \
    --target=$SORTIX_PLATFORM \
    --with-sysroot=$SYSROOT \
    --prefix="$CROSS_PREFIX" \
    --enable-languages=c,c++ \
    --program-prefix=$SORTIX_PLATFORM- &&
  make all-gcc all-target-libgcc &&
  make install-gcc install-target-libgcc

You may need to install some dependencies before you build gcc, such as libmpc,
libmpfr and libgmp. You can remove the temporary ~/src/gcc-build directory when
you are done. Notice how we don't build all of gcc as this isn't possible yet.
For instance, the C++ library requires the Sortix libc to have been built.

Building Sortix
---------------

You now have the needed components to build a working Sortix system. If you have
completed the above steps correctly, then you can simply do:

  cd ~/sortix &&
  make HOST=$SORTIX_PLATFORM

This will compile a basic Sortix system into ~/sortix/sysroot with a kernel,
headers, libraries, programs, everything you need. This isn't a bootable system
yet. If you have xorriso and grub-mkrescue from GRUB 2 installed, then you can
can build a bootable .iso by typing:

  cd ~/sortix &&
  make HOST=$SORTIX_PLATFORM sortix.iso

This will produce a ~/sortix/sortix.iso file that is bootable on real hardware
and virtual machines. Alternatively, you can take the sortix.bin file and boot
that with GRUB as a multiboot kernel and sortix.initrd (snapshot of the sysroot)
as a multiboot module/initrd.

You can clean the source directory fully:

  cd ~/sortix &&
  make distclean

This will clean all the source directories and ports and delete all the builds
and the binary package repositories (if you use ports as below) and it will
delete the system root containing your installed system. Alternatively, you may
be interested in the target `mostlyclean `that doesn't delete binary packages
for ports, as they may take considerable time to recompile. See also the targets
`clean`, `clean-core`, `clean-sysroot`, `clean-repository`, `clean-builds`,
and `clean-ports` which lets you control what is cleaned.