245 lines
6.6 KiB
Groff
245 lines
6.6 KiB
Groff
.Dd $Mdocdate: 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 pages 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.
|
|
.Ss Overview
|
|
To build Sortix you need these components:
|
|
.Bl -bullet -compact
|
|
.It
|
|
Sortix source code
|
|
.It
|
|
Sortix binutils
|
|
.It
|
|
Sortix gcc
|
|
.It
|
|
GRUB (for iso creation)
|
|
.It
|
|
xorriso (for iso creation)
|
|
.El
|
|
.Pp
|
|
The overall process is:
|
|
.Bl -bullet -compact
|
|
.It
|
|
Retrieving all the source code.
|
|
.It
|
|
Installing the build tools.
|
|
.It
|
|
Creating a system root with the system headers.
|
|
.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
|
|
You can find the latest Sortix binutils source code at
|
|
.Lk https://sortix.org/toolchain/sortix-binutils-latest.tar.xz
|
|
.Pp
|
|
You can find the latest Sortix gcc source code at
|
|
.Lk https://sortix.org/toolchain/sortix-gcc-latest.tar.xz
|
|
.Pp
|
|
This is a compiler toolchain that has been modified to support Sortix. The
|
|
toolchain is sometimes updated and you will need the latest toolchain to keep
|
|
building the latest code.
|
|
.Ss Variables
|
|
This document will use shell variables to denote where you have choice. You
|
|
would typically set them up like this:
|
|
.Bd -literal
|
|
# The Sortix source code is in /home/user/sortix
|
|
# The cross-compiler is installed in /home/user/opt/x86_64-sortix
|
|
SORTIX_PLATFORM=x86_64-sortix
|
|
CROSS_PREFIX=/home/user/opt/x86_64-sortix
|
|
SORTIX_SYSROOT=/home/user/sortix/sysroot
|
|
export PATH="/home/user/opt/x86_64-sortix/bin:$PATH"
|
|
export PATH="/home/user/opt/x86_64-sortix/sbin:$PATH"
|
|
.Ed
|
|
.Pp
|
|
The following sections describe these variables in detail.
|
|
.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
|
|
.Ev SORTIX_PLATFORM .
|
|
If you want to build another platform afterwards, then you will have to follow
|
|
this guide again.
|
|
.Ss Cross-environment
|
|
You should install your cross-toolchain into a useful and isolated directory
|
|
such as
|
|
.Pa $HOME/opt/$SORTIX_PLATFORM .
|
|
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
|
|
.Ev CROSS_PREFIX.
|
|
.Pp
|
|
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 Build Tools
|
|
You need to install some additional build tools as they are needed to build the
|
|
operating system. The installed build tools must be in sync with the source
|
|
code as described in
|
|
.Xr development 7 .
|
|
Assuming the source code is in
|
|
.Pa ~/sortix ,
|
|
you can install them by running:
|
|
.Bd -literal
|
|
cd ~/sortix &&
|
|
make PREFIX="$CROSS_PREFIX" clean-build-tools &&
|
|
make PREFIX="$CROSS_PREFIX" build-tools &&
|
|
make PREFIX="$CROSS_PREFIX" install-build-tools &&
|
|
make distclean
|
|
.Ed
|
|
.Pp
|
|
These tools produce platform independent output so you may wish to install them
|
|
into
|
|
.Pa $HOME/bin
|
|
and
|
|
.Pa $HOME/sbin
|
|
or
|
|
.Pa /usr/local/bin
|
|
and
|
|
.Pa /usr/local/sbin
|
|
or where it suits you in your
|
|
.Ev PATH .
|
|
.Ss System Root with System Headers
|
|
Building the compiler requires the standard library headers being available.
|
|
This can be satisfies by creating a system root with the system headers:
|
|
.Bd -literal
|
|
cd ~/sortix &&
|
|
make sysroot-base-headers HOST=$SORTIX_PLATFORM
|
|
.Ed
|
|
.Pp
|
|
This will create a system root at
|
|
.Pa ~/sortix/sysroot .
|
|
Refer to that directory as
|
|
.Ev SORTIX_SYSROOT .
|
|
.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 binutils
|
|
Assuming you extracted the binutils to
|
|
.Pa ~/src/sortix-binutils ,
|
|
you can build binutils out-of-directory by running:
|
|
.Bd -literal
|
|
mkdir ~/src/binutils-build &&
|
|
cd ~/src/binutils-build &&
|
|
../sortix-binutils/configure \\
|
|
--target=$SORTIX_PLATFORM \\
|
|
--with-sysroot="$SORTIX_SYSROOT" \\
|
|
--prefix="$CROSS_PREFIX" \\
|
|
--disable-werror &&
|
|
make &&
|
|
make install
|
|
.Ed
|
|
.Pp
|
|
You can remove the temporary
|
|
.Pa ~/src/binutils-build
|
|
directory when finished.
|
|
.Ss gcc
|
|
Assuming you extracted the gcc to
|
|
.Pa ~/src/sortix-gcc ,
|
|
you can build gcc out-of-directory by running:
|
|
.Bd -literal
|
|
mkdir ~/src/gcc-build &&
|
|
cd ~/src/gcc-build &&
|
|
../sortix-gcc/configure \\
|
|
--target=$SORTIX_PLATFORM \\
|
|
--with-sysroot="$SORTIX_SYSROOT" \\
|
|
--prefix="$CROSS_PREFIX" \\
|
|
--enable-languages=c,c++ &&
|
|
make all-gcc all-target-libgcc &&
|
|
make install-gcc install-target-libgcc
|
|
.Ed
|
|
.Pp
|
|
You can remove the temporary
|
|
.Pa ~/src/gcc-build
|
|
directory when finished. Notice how special make targets are used to not build
|
|
all of gcc.
|
|
.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
|
|
.Ev 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 .
|
|
See the
|
|
.Xr development 7
|
|
manual page for how to use the build system.
|
|
.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 installation 7 ,
|
|
.Xr porting-guide 7 ,
|
|
.Xr sysinstall 8
|