23b3271fca
Add python3 to the basic set of ports in order to build releases.
255 lines
7.4 KiB
Groff
255 lines
7.4 KiB
Groff
.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
|