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

• 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 - /home/glaucus/scripts/toolchain/run.sh

• chroot - /home/glaucus/scripts/chroot/run.sh
• system - /scripts/system/run.sh

5.3.4. The Basic Anatomy of a run.sh Script

The basic anatomy of any run.sh script is described below:

5.3.4.1. The variables Script

All 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).

5.3.4.2. The check Script

The check script comes next. This script is reponsible for fetching, verifying and extracting, or cloning cerata belonging to a particular stage.

5.3.4.3. The prepare Script

The following sourced script is generally the prepare script that perform some cleaning and preparation before construct or 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.

The prepare scripts for both cross and native ensure that the build directories /temporary/toolchain/cross/builds and /temporary/toolchain/native/builds are empty before the construct script is sourced.

5.3.4.4. The log Script

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 /home/glaucus/logs/$stage/$try (where $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).

5.3.4.5. The construct and envenomate Scripts

The scripts passed to the sourced log script in run.sh as arguments are the construct and envenomate scripts. Both the construct and 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 linux-headers and 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 sac directories (which are basically DESTDIR directories to keep track of installed files) producing venom directories containing both the final tarred archive and a sum file of its contents.

!!! note The only technical difference between construct and envenomate is that envenomate uses directories called sacs as DESTDIRs to keep track of installed files since they're the final system cerata (packages).

• If we examine the content of a construct script or the envenomate script, we'll notice that a function with the name of the script is first defined (construct() for construct, and envenomate() for envenomate). This function takes only one argument (and creates the needed sac and venom directories for that one argument in the case of envenomate) and sources the /home/glaucus/cerata/$ceras/ceras file which contains all the required variables needed to construct or envenomate that ceras.

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 construct or 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 $ceras-$ver directory in /home/glaucus/sources/$ceras to a versionless directory with only the name ceras in a temporary location /home/glaucus/temporary/$stage/sources/$ceras where 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:

1. cerata which don't support building out of tree (outside their sources directories)

2. cerata with modified sources (to preserve the original sources directory)

• 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 ./configure preceeding environment variables and flags passed to the configure script. Other commands that belong to this function include:

• ./autogen.sh

• autoreconf -vfi
• all sorts of configure files including but not limited to config.mk, config.mak and configure.local
• all sort of makefiles including but not limitetd to Makefile, Makefile.am, Makefile.in, Makefile.local and Makefile.PL
• patches and sed commands that modify either configure files or makefiles

• meson

• 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 (:)).

• install_$stage() - This function is reponsible for installing what the build function compiled. Any additional compatibility symlinks are created here as well.