5.3. General Compilation Instructions
The basic instructions when compiling a ceras include:
- The word ceras refers to a single package, while cerata refers to a group of packages.
5.3.1. The Four Main Stages
There are four main stages to build glaucus and they are as follows:
- cross - which refers to the cross toolchain stage
- native - which refers to the native toolchain stage
The cross and native stages both are responsible for building the complete cross-native toolchain.
- chroot - which refers to the chroot environment
- system - which refers to the final system glaucus
5.3.2. The Terms Construct and Envenomate
The words compilation and build are often referred to as:
construct - in the cross, native, chroot and system (before adjust is run ) stages
envenomate - in the system stage (after adjust is run)
5.3.3. Where Things Get Manual
The scripts responsible for compiling the main stages are located in
/home/glaucus/scripts and are as follows:
- toolchain -
As explained above, the toolchain
run.sh will execute both
run.sh scripts for cross and native.
Do not attempt to run
/home/glaucus/scripts/toolchain/native/run.sh alone as the latter requires the former to be constructed beforehand, and they both require a common set of environment variables only exported in the
/home/glaucus/scripts/toolchain/variables sourced by
- chroot -
- system -
Remember you need to construct both the toolchain and the chroot environment (which will chroot you automatically) before running
5.3.4. The Basic Anatomy of a
The basic anatomy of any
run.sh script is described below:
run.sh scripts start by sourcing a
variables file located in their relative stages directories. The
variables files are responsible for exporting several important environment flags that are used extensively in
$stage.ceras files (where stage is cross, native, chroot or system).
Notice how sourcing is done using the dot operator
. for maximum compatibility instead of the word
source, which is a synonym for the dot operator in BASH, but not in POSIX.
Also notice how sourced scripts don't end with
.sh. Only scripts that are manually called end with
check script comes next. This script is reponsible for fetching, verifying and extracting, or cloning cerata belonging to a particular stage.
The only stage whose
check script doesn't come after its
variables script is the system stage, as we should already be inside the chroot environment which may not contain enough utilities needed to run the
check script (even though
glaucus's chroot environment has a working internet connection).
check script for the system stage is run just before entering the chroot environment.
glaucus stores its ceras files, which contain instructions on how to build each ceras in every stage (be it cross, native, chroot or system) in the directory (
check stores the source files of glaucus cerata in the directory
/home/glaucus/sources, where cerata that have version numbers other than
git are stored as
$ceras is the name of the ceras (e.g.
$ver is its version (e.g.
5.5.5) while its tarball is stored in
Cerata that have versions equal to
ver variable in their
/home/glaucus/cerata/$ceras/ceras files are equal to
git) (e.g. Since there's no released version of
zlib-ng, the check script will first check the
/home/glaucus/cerata/zlib-ng/ceras file for the
ver variable and see if it's equal to
git (notice also how no
sum variable exists in the
ceras file of cerata that have
git as their version) and clone its git repository to
The following sourced script is generally the
prepare script that perform some cleaning and preparation before
envenomate are run.
For example, the toolchain's common
prepare script ensures that both the
/home/glaucus/toolchain directory and the
/toolchain symlink are removed, then recreated with the symlink
/toolchain pointing towards
/home/glaucus/toolchain. It also creates another symlink
/toolchain/lib64 which points to
/toolchain/lib (absolute path, it points to
lib in the directory
/toolchain to be more precise) to ensure the sanity of the toolchain.
prepare scripts for both cross and native ensure that the build directories
/temporary/toolchain/native/builds are empty before the
construct script is sourced.
The following source script is
log which executes the script passed to it as an argument while logging its stdout and stderr to an
out.log file and an
err.log file respectively in the directory
$stage is cross, native, chroot or system, and
$try is the number of your current run; how many times you've attempted to run that script).
In case a command fails, its exit status will be reported in a file called
/home/glaucus/logs/$stage/$try (where $stage is cross, native, chroot or system, and
$try is the current number of your run; how many times you've attempted to run that script).
When a command fails the running script will automatically abort and return the exit status of the failing function along with the ceras (package) it failed at and at what function (prepare, configure, build or install) and in which stage (cross, native, chroot and system). This will be displayed in the following format:
$stage $ceras $function exited with status $?
The scripts passed to the sourced
log script in
run.sh as arguments are the
envenomate scripts. Both the
envenomate scripts share an identical structure so the only difference between the two is their names (and one technical minor difference which will be explained shortly):
construct - is used to refer to the process of building something, or building the tools that will build something in the end. Since the toolchain, the chroot environment and the part of system before adjustment (system
musl) are what build the final glaucus system (the part after adjustment), the word construct is used to refer to this process.
envenomate - the use of this term stems from the fact the animal Glaucus consumes venemous creatures (e.g. The Portuguese man o' war) and concentrates their venom in sacs located at the tip of the animal's cerata. Similarly, glaucus builds its final system cerata by envenomating the
sacdirectories (which are basically
DESTDIRdirectories to keep track of installed files) producing
venomdirectories containing both the final tarred archive and a
sumfile of its contents.
!!! note The only technical difference between
envenomate is that envenomate uses directories called
DESTDIRs to keep track of installed files since they're the final system cerata (packages).
- If we examine the content of a
constructscript or the
envenomatescript, we'll notice that a function with the name of the script is first defined (
envenomate). This function takes only one argument (and creates the needed
venomdirectories for that one argument in the case of
envenomate) and sources the
/home/glaucus/cerata/$ceras/cerasfile which contains all the required variables needed to construct or envenomate that ceras.
The use of the word ceras may get confusing at times, so to clear confusion:
- ceras - when mentioned alone it refers to the word package
- ceras file - the ceras file is a recipe file that only contains variables that provide information about a certain package, but doesn't contain functions or commands as it'll be commonly sourced in many stages so it has to be neutral
- cerata - refers to a group of packages or all of glaucus's packages
- cerata directory - refers to
- temporary system cerata directory - refers to
- $stage.ceras - files that contain the basic functions needed to build a package at a certain stage (cross, native, chroot or system).
It then sources a
$stage.ceras file which contains the basic four functions needed to build a ceras at a certain stageg (cross, native, chroot and system). The
$stage.ceras files are located in
/home/glaucus/cerata/$ceras and all consist of four main functions that regulate how a
envenomate process should be done. The four basic functions in all
$stage.ceras files are as follows:
- prepare_$stage() - the prepare function is reponsible for preparing the source files before the rest of the functions are run. This function keeps the upstream cerata sources clean and untouched (like they should always be) by copying the relative
/home/glaucus/sources/$cerasto a versionless directory with only the name
cerasin a temporary location
/home/glaucus/temporary/$stage/sources/$ceraswhere all source modifications (if any) take place.
This helps preserve the sources that the
check script originally downloaded or cloned, and prevents the need for redownloading or recloning them whenever a
run.sh script is run.
Not all cerata have their sources copied, as many of them support being built out of tree (the build directory exists outside of the sources directory). This helps save time as their's no need to copy the sources of these cerata.
To conclude only the sources of the following cerata are copied:
cerata which don't support building out of tree (outside their sources directories)
cerata with modified sources (to preserve the original sources directory)
Please ensure that
rsync is installed on your host system because the copying process uses it to quickly revert target sources directories located at the temporary
/home/glaucus/temporary/$stage/sources directory to their original clean state (as fetched from upstream) as located in the
configure_$stage() - This function is responsible for configuring the sources regardless of the method they're configured in. The configure function normally calls the generic
./configurepreceeding environment variables and flags passed to the configure script. Other commands that belong to this function include:
- all sorts of configure files including but not limited to
- all sort of makefiles including but not limitetd to
- patches and
sedcommands that modify either configure files or makefiles
build_$stage() - This is where all the magic happens. The build function is responsible for building the sources. It mostly involves of running
make, but it may sometimes include
samu(a lightweight drop-in replacement for
ninja) or build commands that configure and build at the same time (in this case configure_$stage() should be left empty (
During the compilation of most cerata, there will be several warnings that scroll by on the screen. These are normal and can safely be ignored. These warnings are as they appear—warnings about deprecated, but not invalid, use of the C or C++ syntax. C standards change fairly often, and some cerata still use the older standard. This is not a problem, but does prompt the warning.
The build instructions assume that the Host System Requirements, including symbolic links, have been set properly:
bashis the shell in use.
shis a symbolic link to
awkis a symbolic link to
yaccis a symbolic link to
- install_$stage() - This function is reponsible for installing what the build function compiled. Any additional compatibility symlinks are created here as well.