BASIC WORKINGS

Checksums and rebuilds

GUB seeks to minimise unnecessary rebuilds while being strict
about important changes. Before starting the actual building of a
package, the build recipe is executed as a dry-run and a checksum
is calculated from these build commands. This checksum includes
the environment variables DISPLAY, FTP_PROXY, GUB_TOOLS_PREFIX,
HOME, HTTP_PROXY, LIBRESTRICT, PATH [no other environment
variables are allowed through].

The packages' build checksum is matched with the previous build
and if it changes, the package is rebuilt. Otherwise, only the
binary package is reinstalled, if necessary.
This means that the .py build specs can be changed and refactored
at will and as long as no actual build commands change, nothing
will be rebuilt.

This makes that forcing rebuilds can can be tricky: gub refuses to
do so if it deems rebuilding unnecessary.

SHARING DIRECTORIES

GUB uses an ABI environment variable to work around some build
bugs in some packages. This variable is not checked by the
environment-changed function, so problems will probably occur if
you share your GUB build directory between a 32-bit and 64-bit OS.
If you change your operating system, delete the target/ directory
of GUB before trying to build it again.

LIBRESTRICT

A common problem with [making reproducible cross] builds is using
files or features that are not controlled by the [GUB] build
process, but just happen to be on the build host and
happen to differ between most build hosts.

GUB uses the LD_PRELOAD feature with
the gub/specs/librestrict.py package and code
from ./librestrict/restrict.c to disallow reading
from build host files. This makes for much better reprocucibility,
especially between different build hosts.

The downside to this LIBRESTRICT feature is that quite a few
packages are not prepared for cross building. LIBRESTRICT will
catch these errors and they have to be fixed in the package's spec
file.

you often find these in config.log files when
package-dependant code blondly looks in /usr/include
or /usr/lib.

stat-restriction

LIBRESTRICT has an experimental strict mode enabled by
setting the environment variable

LIBRESTRICT=open:stat

This will even disallow any STATting outside the target's build
tree. It would be nice to get this to work and some effort has
been done. However, this is potentially a lot of work as not only
upstream packages but also build system authors [autoconf,
automake, libtool etc.] look at the build host root file system
while cross building.

Simplifying package builds or avoiding code duplication

Another idea of GUB is to identify, fix and generalise build
quircks and move them from a package's spec file into one of the
generic build classes. This increases maintainability by avoiding
code duplication, makes spec files smaller, simpler and also
increases the chances of a new package's spec file to only need a
source url to specify the build.

BASIC USAGE

Build package hello for platform linux-x86

bin/gub linux-x86::hello

Examine why package hello wants to rebuild

less target/linux-x86/log/build.log
search from end back to `mismatch:' [type: FC-c?mismatch:RET]

Force a rebuild of package hello for platform linux-x86

rm -rf target/linux-x86/*/hello-*

Force a rebuild of package hello for all platforms

rm -rf target/*/*/hello-*

Prepare to rebuild entire linux-x86 platform

rm -rf target/linux-x86

Prepare to rebuild everything, all platforms

rm -rf target

SPEC FILES

Plain url builds

<--no spec-->

Well behaved packages can be built without spec file, straight from an
url. For example, to build bison-2.2 as a build tool, do