Documentation + fixed Brotli configure script

sources/00-brotli-add-automake.patch

@@ -108,7 +108,7 @@ new file mode 100755
 index 0000000..d4325b2
 --- /dev/null
 +++ b/bootstrap
-@@ -0,0 +1,36 @@
+@@ -0,0 +1,32 @@
 +#!/bin/sh -e
 +
 +REQUIRED='is required, but not installed.'
@@ -127,18 +127,14 @@ index 0000000..d4325b2
 +mkdir m4 2>/dev/null
 +fi
 +
-+BROTLI_ABI_HEX=`sed -n 's/#define BROTLI_ABI_VERSION 0x//p' c/common/version.h`
-+BROTLI_ABI_INT=`echo "ibase=16;$BROTLI_ABI_HEX" | bc`
-+BROTLI_ABI_CURRENT=`echo "scale=0;$BROTLI_ABI_INT / 16777216" | bc`
-+BROTLI_ABI_REVISION=`echo "scale=0;$BROTLI_ABI_INT / 4096 % 4096" | bc`
-+BROTLI_ABI_AGE=`echo "scale=0;$BROTLI_ABI_INT % 4096" | bc`
++BROTLI_ABI_CURRENT=`sed -n 's/#define BROTLI_ABI_CURRENT //p' c/common/version.h`
++BROTLI_ABI_REVISION=`sed -n 's/#define BROTLI_ABI_REVISION //p' c/common/version.h`
++BROTLI_ABI_AGE=`sed -n 's/#define BROTLI_ABI_AGE //p' c/common/version.h`
 +BROTLI_ABI_INFO="$BROTLI_ABI_CURRENT:$BROTLI_ABI_REVISION:$BROTLI_ABI_AGE"
 +
-+BROTLI_VERSION_HEX=`sed -n 's/#define BROTLI_VERSION 0x//p' c/common/version.h`
-+BROTLI_VERSION_INT=`echo "ibase=16;$BROTLI_VERSION_HEX" | bc`
-+BROTLI_VERSION_MAJOR=`echo "scale=0;$BROTLI_VERSION_INT / 16777216" | bc`
-+BROTLI_VERSION_MINOR=`echo "scale=0;$BROTLI_VERSION_INT / 4096 % 4096" | bc`
-+BROTLI_VERSION_PATCH=`echo "scale=0;$BROTLI_VERSION_INT % 4096" | bc`
++BROTLI_VERSION_MAJOR=`sed -n 's/#define BROTLI_VERSION_MAJOR //p' c/common/version.h`
++BROTLI_VERSION_MINOR=`sed -n 's/#define BROTLI_VERSION_MINOR //p' c/common/version.h`
++BROTLI_VERSION_PATCH=`sed -n 's/#define BROTLI_VERSION_PATCH //p' c/common/version.h`
 +BROTLI_VERSION="$BROTLI_VERSION_MAJOR.$BROTLI_VERSION_MINOR.$BROTLI_VERSION_PATCH"
 +
 +sed -i.bak "$SED_ERE" "s/[0-9]+:[0-9]+:[0-9]+/$BROTLI_ABI_INFO/" Makefile.am

sources/brotli-gen-sources-list.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+echo "BROTLI_CLI_C = " c/tools/*.c
+echo "BROTLI_COMMON_C = " c/common/*.c
+echo "BROTLI_COMMON_H = " c/common/*.h
+echo "BROTLI_DEC_C = " c/dec/*.c
+echo "BROTLI_DEC_H = " c/dec/*.h
+echo "BROTLI_ENC_C = " c/enc/*.c
+echo "BROTLI_ENC_H = " c/enc/*.h
+echo "BROTLI_INCLUDE = " c/include/brotli/*.h

sources/default.nix

@@ -47,7 +47,10 @@ let
   brotli_configured_src = mkConfiguredSrc
     { pkg = brotli;
       patches = [ ./00-brotli-add-automake.patch ];
-      confScript = "true";
+      confScript = ''
+        sh ${./brotli-gen-sources-list.sh} > ./scripts/sources.lst
+        ./bootstrap
+      '';
       dest = "libbrotlicommon";
     };
 

src/builders/autoconf.ab

@@ -56,5 +56,6 @@ main(cmdl)
     let inc_prefix = cmdl[4]
 
     trust env_var_set("_NIXIE_TESTING_SKIP_TARBALL", "1")
+    trust env_var_set("step_total", "1")
     build_autoconf_dep(lib_name, var_name, lib_prefix, inc_prefix)?
 }

src/builders/boost.ab

@@ -31,6 +31,7 @@ fun find_boost_libs(libs: [Text]): Bool
     return true
 }
 
+/// This function runs within the source directory, in a subshell.
 fun build_boost_inner()
 {
     let args = [ "--static" ]
@@ -43,6 +44,9 @@ fun build_boost_inner()
     $./b2 "{args}"$?
 }
 
+/// This is the core function for the Boost builder.
+///
+/// It exports the `BOOST_ROOT` variable.
 pub fun build_boost()
 {
     let source_root = get_source_root()
@@ -63,5 +67,6 @@ pub fun build_boost()
 main(cmdl)
 {
     trust env_var_set("_NIXIE_TESTING_SKIP_TARBALL", "1")
+    trust env_var_set("step_total", "1")
     build_boost()?
 }

src/builders/common.ab

@@ -20,6 +20,7 @@ pub fun pkg_exists(package: Text): Bool
     return true
 }
 
+/// Change the terminal title to a build step, and increments the step counter.
 pub fun step_title(name: Text): Null
 {
     let step_total = trust env_var_get("step_total")
@@ -31,6 +32,7 @@ pub fun step_title(name: Text): Null
     step_current += 1
 }
 
+/// Obtain the base directory where source packages are extracted.
 pub fun get_source_root(): Text
 {
     let repo_root = get_repo_root()

src/builders/lowdown.ab

@@ -9,11 +9,13 @@ import { get_osname, get_cache_root } from "../platform.ab"
 
 import { pkg_exists, step_title, get_source_root } from "./common.ab"
 
+/// Workaround for the default Makefile not building a shared library on macOS.
 fun macos_build_post()
 {
     $cc -shared -o liblowdown.1.dylib *.o$?
 }
 
+/// This function runs within the source directory, in a subshell.
 fun build_lowdown_inner()
 {
     $./configure$?
@@ -23,6 +25,9 @@ fun build_lowdown_inner()
         macos_build_post()?
 }
 
+/// This is the core function for the Lowdown builder.
+///
+/// It exports the `LOWDOWN_LIBS` and `LOWDOWN_CFLAGS` variables.
 pub fun build_lowdown()
 {
     let source_root = get_source_root()
@@ -44,5 +49,6 @@ pub fun build_lowdown()
 main(cmdl)
 {
     trust env_var_set("_NIXIE_TESTING_SKIP_TARBALL", "1")
+    trust env_var_set("step_total", "1")
     build_lowdown()?
 }

src/builders/nix.ab

@@ -9,6 +9,7 @@ import { get_cache_root } from "../platform.ab"
 
 import { step_title, get_source_root } from "./common.ab"
 
+/// This function runs within the source directory, in a subshell.
 fun build_nix_inner()
 {
     let source_root = get_source_root()
@@ -27,6 +28,10 @@ fun build_nix_inner()
     ${venv}/bin/ninja$?
 }
 
+/// This is the core function for the final Nix builder.
+///
+/// It produces a Nix executable in the `{cache_root}/nix-static` location,
+/// where the Nix runner expects it.
 pub fun build_nix()
 {
     let source_root = get_source_root()

src/builders/nlohmann_json.ab

@@ -8,6 +8,9 @@ import { pull_source_file } from "../resources.ab"
 
 import { pkg_exists, step_title, get_source_root } from "./common.ab"
 
+/// This is the core function for the NLohmann JSON library.
+///
+/// It exports the `LNLOHMANN_JSON_LIBS` and `NLOHMANN_JSON_CFLAGS` variables.
 pub fun build_nlohmann_json()
 {
     let source_root = get_source_root()
@@ -27,5 +30,6 @@ pub fun build_nlohmann_json()
 main(cmdl)
 {
     trust env_var_set("_NIXIE_TESTING_SKIP_TARBALL", "1")
+    trust env_var_set("step_total", "1")
     build_nlohmann_json()?
 }

src/builders/openssl.ab

@@ -21,6 +21,7 @@ fun make_headers()
     }
 }
 
+/// This function runs within the source directory, in a subshell.
 fun build_openssl_inner()
 {
     let dll_ext = get_dll_ext()
@@ -35,6 +36,9 @@ fun build_openssl_inner()
     trust $cp ./libcrypto.* {cache_root}/nix-lib/$
 }
 
+/// This is the core function for the OpenSSL builder.
+///
+/// It exports the `OPENSSL_LIBS` and `OPENSSL_CFLAGS` variables.
 pub fun build_openssl()
 {
     let source_root = get_source_root()
@@ -60,6 +64,7 @@ pub fun build_openssl()
 main(cmdl)
 {
     trust env_var_set("_NIXIE_TESTING_SKIP_TARBALL", "1")
+    trust env_var_set("step_total", "1")
     build_openssl()?
 }
 

src/common.ab

@@ -19,7 +19,7 @@ if text_contains(me, "/") {
             SELF = "{PWD}/{me}"
         }
 
-        // This second pass check if the result of readlink is relative
+        // This second pass checks if the result of readlink is relative
         if {
             rl == "":                  SELF = SELF
             not starts_with(rl, "/"):  SELF = "{PWD}/{rl}"

src/resources.ab

@@ -15,12 +15,24 @@ fun cachix_url(derivation: Text, member: Text): Text
     return "https://{SOURCE_CACHE}/serve/{derivation}/{member}"
 }
 
+/// Unpack a known source code package into the requested target directory.
+///
+/// This function will try the following methods, in order:
+/// - Extract from the embedded tarball
+/// - Pull tarball from directory marked by `_NIXIE_TESTING_SOURCES_DIR`
+/// - Download tarball from known Cachix URL
+///
+/// ### Arguments:
+/// - `member`: The name of the source package to unpack
+/// - `dest`: The target directory to move the package contents into
 pub fun pull_source_file(member: Text, dest: Text): Null?
 {
     let SOURCE_DERIVATION = trust env_var_get("SOURCE_DERIVATION")
 
     let where = ""
     let my_status = 1
+
+    // This allows individual builders' entry points to not fail
     if not env_var_test("_NIXIE_TESTING_SKIP_TARBALL") {
         where = trust untar("sources/{member}")
         my_status = status
@@ -55,6 +67,15 @@ pub fun pull_source_file(member: Text, dest: Text): Null?
     trust mv where dest
 }
 
+/// Retrieve a known precompiled file and move it to the requested target.
+///
+/// This function will try the following methods, in order:
+/// - Extract from the embedded tarball
+/// - Download file from known Cachix URL
+///
+/// ### Arguments:
+/// - `member`: The filename of the file to retrieve
+/// - `dest`: The target filename to move the file into
 pub fun pull_binary(member: Text, dest: Text): Null?
 {
     let NIX_BINS_DERIVATION = trust env_var_get("NIX_BINS_DERIVATION")