path: root/README

parabola-riscv64-bootstrap
==========================

1. Introduction
---------------

This project is an attempt to bootstrap a self-contained parabola
GNU/Linux-libre system for the riscv64 architecture. The scripts are created
with the goal to be as generic as possible, to make future porting effort
easier. Feel free to adapt them to target any architecture you want by
modifying the variables in create.sh

The build process is split into several stages, the rationale of which is
outlined in section 2 below.

To initiate a complete build of all stages, run:
  $> sudo ./create

To discard fragments from an earlier run and start from a clean slate, run:
  $> sudo rm -rf build && sudo ./create

You might have to unmount the directories mounted by the stages as noted in the
sections below.

1.1. A note to the reader
-------------------------

The scripts assume to be running on a parabola GNU/Linux-libre system, and may
fail in subtle and unexpected ways otherwise. They also may fail in subtle and
unexpected ways anyway, because they are modifying upstream PKGBUILD files,
which are very volatile and change without notice. When adapting this project
to a new architecture, or a different flavour of archlinux, execrcise caution,
pay close attention to any output, and be prepared to fix and modify patches
and scripts.

Also, if you found this project useful, and want to chat about anything, you
can email me at <andreas@grapentin.org>.

1.2. Current state of the project
---------------------------------

The stage3 native base-devel makepkg chroot is finished, and stage4 is primed
to begin with native compilation of a first batch of release packages in the
chroot.

2. Build Stages
---------------

The following subsections outline the reasoning behind the separate bootstrap
stages. More details about *how* things are done may be gathered from reading
the inline comments of the respective scripts.

2.1. Stage 1
------------

The first stage creates a cross-compile toolchain for the target triplet
defined in $CHOST, consisting of binutils, linux-libre-api-headers, gcc and
glibc. This toolchain has been pre-packaged for riscv64-unknown-linux-gnu on
parabola GNU/Linux-libre and may be installed by running:

  $> pacman -S riscv64-unknown-linux-gnu-gcc

In any case, the toolchain will be bootstrapped by the stage1.sh script, unless
it is already installed. The scripts will check for $CHOST-ar and $CHOST-gcc in
$PATH to determine whether binutils and gcc are installed, and will then
proceed to look for the following files in $CHOST-gcc's sysroot:

  $sysroot/lib/libc.so.6              # for $CHOST-glibc
  $sysroot/include/linux/kernel.h     # for $CHOST-linux-libre-api-headers

If your system contains these files, the toolchain bootstrap process will be
skipped. Otherwise, the scripts will create a new toolchain as follows:

 - compile $CHOST-binutils
 - compile $CHOST-linux-libre-api-headers
 - compile $CHOST-gcc-bootstrap, without glibc dependency
 - cross-compile $CHOST-glibc using $CHOST-gcc-bootstrap
 - compile $CHOST-gcc against the created $CHOST-glibc

The sysroot of the created toolchain is set as /usr/$CHOST.

The $CHOST-{binutils,linux-libre-api-headers,gcc,glibc} packages are installed
as regular pacman packages on the build system, and are not automatically
removed by the scripts after the build is completed (or has failed).

For more information, you might want to check the PKGBUILD files located in
src/stage1/toolchain-pkgbuilds/*.

2.2. Stage 2
------------

Stage 2 uses the toolchain created in Stage 1 to cross-compile the packages of
the base-devel group of packages plus transitive runtime dependencies, in order
to bootstrap a functional cross-makepkg librechroot.

The script creates an empty skeleton chroot, into which the cross-compiled
packages are installed, and creates a sane makepkg.conf and a patched
makepkg.sh to work in the prepared chroot root directory. To make the sysroot
of the compiler available to builds in the chroot and vice-versa, the /usr
directory of the chroot is mounted into the sysroot. At the end of Stage 2,
this directory is unmounted automatically.

The transitive dependency tree of the base-devel package group is slightly
modified in a way that resolves any cyclic dependencies, and preserves a
somewhat sane build-order of the packages. Some packages that are too painful
to cross-compile are skipped entirely.

To build the packages, the dependency tree is traversed and packages are
rebuilt using upstream PKGBUILDs and custom patches to cross-compile the
packages for the configured target architecture. Packages with the `any'
architecture are simply reused for this stage, since they should work for any
architecture and do not need to be cross-compiled.

As a final note, since the upstream PKGBUILDS change frequently, and the
patches are unlikely to be maintained once the initial bootstrap is done and
stable, they will probably cease to function in the near future. Exercise
caution.

2.3. Stage 3
------------

Stage 3 uses the cross-compiled makepkg chroot created in Stage 2 to natively
compile the base-devel group of packages again, but without using a
cross-compiler and without the need for mandatory package patches. Many
packages `just work' when compiling them using the upstream PKGBUILDs, but some
still need to be altered, and build time dependencies need to be removed when
they are too painful to compile.

This stage requires more packages to complete, since the host system can not
provide things like git for vcs sources. Everything is taken from the makepkg
chroot.

The process is similar to stage2, a clean librechroot is created using the
packages built in Stage 2, a modified libremakepkg.sh is created to inclued a
update hook for config.sub and config.guess scripts, which are unfortunately
too old for most packages to detect the architecture correctly, a dependency
tree is made, and then traversed.

The patches in this stage are fewer and apply less pressure to the packages,
so, while computationally more expensive, this stage is probably a bit easier
to maintain and adapt.

2.4. Stage 4
------------

tbd.