Build Scripts

I have some home-grown automation that I use to test and publish software across multiple platforms. For each repository where I use this automation, project-specific build steps are stored as a collection of bash scripts in a directory called buildscripts.

If you are distributing or hacking on any of these projects, feel free to ignore the build scripts completely. I try to stick to "normal" project structures that will build and run without any additional ceremony. Nonetheless on this page I will describe how the scripts work, mostly as a reference for my future self. If you are trying to work out how the downloadable artefacts are created then you might also find it interesting.

Operations

• build.sh $PLATFORM - attempt to compile the software
• lint.sh $PLATFORM - check formatting and run static analysis
• test.sh $PLATFORM - run tests
• dist-generic.sh $TAG - create non-binary build artefacts such as source code and documentation
• dist.sh $PLATFORM $TAG - create platform-specific build artefacts

Scripts are expected to return a 0 exit code on success, some other exit code on failure, and emit their logs (successful or not) to stdout/stderr.

Parameters

$PLATFORM indicates the target platform we are building for. This needs to be specified because a given build host may be able to target multiple platforms, e.g., both x86 and Apple Silicon.

• mac-x86_64 - Mac with Intel processor
• mac-arm64 - Mac with Apple Silicon processor
• linux-x86_64 - Linux x86_64
• linux-armhf - Linux 32-bit ARM, suitable for a Raspberry Pi with a 32-bit image installed
• linux-arm64 - Linux 64-bit ARM
• windows-x86_64 - Windows x86_64, which should also run okay on Windows ARM machines thanks to the emulation layer in Windows. Maybe one day I'll publish Windows ARM binaries.

$TAG is the version string, something like v0.5.0, which will be embedded in the filenames of the artefacts. I call it the tag because it's expected to be the name of the git tag for the release that we are publishing, though in reality any valid string will do.

Dist Artefacts

The two dist scripts will emit specially-formatted lines to stdout describing files that should be downloaded from the build server before cleaning it up.

PLATFORM_ARTIFACT|$PATH

• Only emitted by dist.sh - we know which platform we are building for, and the artefact is implicitly for that platform.
• $PATH is a relative path within the checkout to a file that should be made available for download.
• This file will be included in the generated SHA256SUMS.

GENERIC_ARTIFACT|$PATH|$DESCRIPTION

• $PATH is a relative path within the checkout to a file that should be made available for download.
• $DESCRIPTION is a human-readable description for what this artefact is, e.g., "Source Code".
• This file will be included in the generated SHA256SUMS.

URL|$DESCRIPTION|$URL|$LINKTEXT

• Creates an entry in the downloads table that is a URL to an external resource associated with this release, e.g., Git or crates.io.
• $DESCRIPTION is a human-readable description for what this URL is, e.g., "Git Tag".
• $URL is the absolute URL that will be linked to.
• $LINKTEXT is the text of the link. It could be the URL again, or something more descriptive.

The program that consumes this output is neither public nor particularly interesting.

Notarisation on Mac

dist.sh may check for two environment variables, CODESIGNCMD and NOTARISECMD, which are set on the Mac builder.

• $CODESIGNCMD $BINARY - sign the binary executable at the given path using an appropriate developer identity.
• $NOTARISECMD $PKG - having packed the binary into a .pkg installer, submit this package to Apple for notarisation and staple the ticket.

Bash on Windows

The Windows build host uses the same bash scripts as other platforms. This is done using the Git Bash environment that comes with Git for Windows. Happily, it is possible to configure OpenSSH on Windows so that SSHing into that Windows machine gives you a Git Bash shell, just as if it was a Linux host.