.Dd December 29, 2015
.Dt CROSS-DEVELOPMENT 7
.Os
.Sh NAME
.Nm cross-development
.Nd operating system development from another operating system
.Sh DESCRIPTION
The
.Xr development 7
manual page describes the primary way of building the operating system, which
is under itself.
The secondary way is to cross-compile it from a sufficiently similar operating
system such as Linux with the GNU tools installed.
The build system assumes the presence of some GNU extensions in the standard
command line tools.
This document will detail the process of bootstrapping a Sortix system from
another operating system.
.Pp
Be sure you are reading the latest version of this document, rather than an old
copy installed on the system or on an online manual page viewer, if you want to
build the latest development code rather than the stable release.
To view the instructions for the latest source code using the command line:
.Bd -literal
    cd /latest/source/code &&
    man share/man/man7/cross-development.7
.Ed
.Ss Overview
To build Sortix you need to get these programs from your operating system vendor
or compile them yourself:
.Bl -bullet -compact
.It
GRUB (for iso creation)
.It
xorriso (for iso creation)
.It
mtools (for iso creation) (if on UEFI systems)
.It
mandoc (for html manuals if building a release directory)
.El
.Pp
GRUB with BIOS support is required.
If you are on an UEFI system, you may need to install further files to get BIOS
support.
For instance, on an apt-based system you might install the
.Sy grub-pc-bin
package.
.Pp
The overall process is:
.Bl -bullet -compact
.It
Retrieving the source code.
.It
Installing the build tools.
.It
Creating a cross-compiler.
.It
Cross-compiling the operating system.
.El
.Ss Source Code
You can find the latest Sortix source code at
.Lk https://sortix.org/source/
.Pp
The source code for the ports are in the ports subdirectory as URLs to the
upstream tarball, alongside any patches to the upstream release, which are
downloaded when each port is built.
.Ss Variables
This document will use meta-syntactic shell variables to denote where you have
choice.
These are simply convenient shorthands that lets this document refer to your
choices.
You shouldn't use real shell variables but just textually replace them with your
choices when you run commands.
.Bl -tag -width "$SORTIX_PLATFORM" -offset indent
.It Sy $SORTIX
The path to the directory containing the Sortix source code.
This could for instance be
.Pa /home/user/sortix .
.It Sy $SORTIX_PLATFORM
The Sortix target platform.
This could for instance be
.Sy x86_64-sortix .
.It Sy $CROSS_PREFIX
The directory path where the cross-toolchain will be installed.
This could for instance be
.Pa /home/user/opt/sortix-toolchain .
.El
.Pp
The following sections describe these variables in detail.
.Ss Sortix Directory
You can put the Sortix source code wherever you'd like.
It is typically git cloned from your home directory and the source code will
appear in
.Pa ~/sortix .
This place will contain the operating system code.
We'll refer to that location as
.Sy $SORTIX.
.Pp
Don't make a sortix directory and git clone inside it, you redundantly get a
.Pa ~/sortix/sortix
directory instead.
.Ss Target Platform
You need to decide what the platform your final Sortix system will run on.
You can currently decide between
.Sy i686-sortix
and
.Sy x86_64-sortix .
In this guide we will refer to that platform triplet as
.Sy $SORTIX_PLATFORM .
If you want to build another platform afterwards, then repeat the steps with
the other platform.
.Ss Cross-Prefix
You should install your cross-toolchain into a useful and isolated directory
such as
.Pa $HOME/opt/sortix-toolchain .
This allows you to easily dispose of the directory and keeps it isolated from
the rest of the system.
We'll refer to that location as
.Sy $CROSS_PREFIX.
.Ss PATH
You need to add
.Pa $CROSS_PREFIX/bin
and
.Pa $CROSS_PREFIX/sbin
to your
.Ev PATH
variable:
.Bd -literal
    export PATH="$CROSS_PREFIX/sbin:$CROSS_PREFIX/bin:$PATH"
.Ed
.Pp
This will modify the
.Ev PATH
variable in this particular shell session.
You can make this permanent by adding that line to your
.Pa ~/.profile
or the applicable file for your shell and system.
Consult your shell documentation.
Otherwise type it in all Sortix-related shells before doing anything.
.Ss Cross-toolchain Dependencies
You need to install these libraries (and the development packages) before
building binutils and gcc:
.Bl -bullet -compact
.It
bison
.It
flex
.It
libgmp
.It
libmpfr
.It
libmpc
.El
.Pp
Consult the official binutils and gcc documentation for the exact dependencies.
.Ss Cross-toolchain
You can build the full cross-toolchain containing the build tools and the
cross-compiler (binutils and gcc) by running:
.Bd -literal
    cd "$SORTIX" &&
    make clean-cross-toolchain &&
    make PREFIX="$CROSS_PREFIX" TARGET=$SORTIX_PLATFORM install-cross-toolchain
.Ed
.Pp
This command builds and installs the build tools and the cross-compiler.
The build downloads the source code for binutils and gcc modified with support
for this operating system.
.Pp
If you want to build a toolchain for every architecture at once, use the
.Sy install-cross-toolchain-all-archs
makefile target instead and omit the
.Sy TARGET
variable.
.Pp
.Xr following-development 7
gains a notice whenever the build tools or cross-compiler must be upgraded.
.Ss Build Tools
The above
.Sy install-cross-toolchain
command already built the build tools needed to bootstrap the operating system.
.Pp
However, whenever they change you can reinstall the build utilities only by
running:
.Bd -literal
    cd "$SORTIX" &&
    make clean-build-tools &&
    make PREFIX="$CROSS_PREFIX" install-build-tools
.Ed
.Pp
.Xr following-development 7
gains a notice whenever the build tools must be upgraded, as they must match the
source code being built.
.Ss Building Sortix
With the build tools and cross-compiler in the
.Ev PATH
is it now possible to build the operating system as described in
.Xr development 7
by setting
.Ev HOST
to your value of
.Sy $SORTIX_PLATFORM .
This tells the build system you are cross-compiling and it will run the
appropriate cross-compiler.
For instance, to build an bootable cdrom image using a
.Sy x86_64-sortix
cross-compiler you can run:
.Bd -literal
    cd "$SORTIX" &&
    make HOST=x86_64-sortix sortix.iso
.Ed
.Pp
This creates a bootable
.Pa sortix.iso
including all ports of third party software.
To build only the minimal set of ports required for installation, set the
.Ev PACKAGES
environment variable to
.Sy minimal!
or set it to the empty string to only build the base system.
Cross-compiling the ports requires installing additional dependencies locally
in order to bootstrap the cross-compilation of some ports.
.Ss Additional Required Reading
The
.Xr development 7
manual page documents how to develop Sortix and how to use the build system.
This manual page only documents how to set up a cross-development environment
and is not sufficient to develop Sortix.
.Pp
The
.Xr following-development 7
manual page documents what needs to be done to stay updated with the latest
developments.
You will need to read the new version of that document whenever you update the
source code.
.Ss Troubleshooting
If producing a bootable cdrom with
.Xr grub-mkrescue 1
gives the error
.Pp
.Dl xorriso : FAILURE : Cannot find path '/efi.img' in loaded ISO image
.Pp
then your GRUB installation is defective.
You need to install
.Xr mformat 1
to use
.Xr grub-mkrescue 1
in your case.
.Sh SEE ALSO
.Xr make 1 ,
.Xr development 7 ,
.Xr following-development 7 ,
.Xr installation 7 ,
.Xr porting 7 ,
.Xr sysinstall 8