1 file changed, 23 insertions, 25 deletions
diff --git a/tools/release-build.sh b/tools/release-build.sh
index b55fc434..12f42606 100755
--- a/tools/release-build.sh
+++ b/tools/release-build.sh
@@ -1,16 +1,11 @@
 #!/bin/sh
-# Build cgit for a release with Linux hardening flags.
-#
-# These are ELF and GCC/Clang specific, so this targets a Linux deploy
-# rather than local macOS development, where a plain make is enough. The
-# flags add a stack protector, fortified libc calls, a position independent
-# executable, and full RELRO.
-#
-# By default Lua is pinned off so the binary needs no Lua at runtime. Pass
-# "lua" as the first argument to link the lua: filter backend instead, which
-# needs a Lua dev package installed.
-#
-# Usage: ./tools/release-build.sh [lua]
+# Build cgit for a release with Linux hardening flags. These are ELF and GCC
+# or Clang specific, so this targets a Linux deploy rather than local macOS
+# development, where a plain make is enough. The flags add a stack protector,
+# fortified libc calls, a position independent executable, and full RELRO. By
+# default Lua is pinned off so the binary needs no Lua at runtime, and running
+# it as ./tools/release-build.sh lua links in the backend behind the "lua:"
+# filter prefix instead, which needs a Lua dev package installed.
 
 set -eu
 
@@ -35,14 +30,16 @@ cd "$(dirname "$0")/.."
 CC=${CC:-cc}
 
 # Not every hardening flag exists on every toolchain, and an unknown one would
-# fail the build rather than be ignored, so each is compiled before it is used.
+# fail the build rather than be ignored, so the ones that might be missing are
+# compiled before they are used. The argument is left unquoted so a caller can
+# probe several flags at once.
 supports() {
 	printf 'int main(void){return 0;}\n' >"$probe.c"
 	$CC $1 -o "$probe.out" "$probe.c" >/dev/null 2>&1
 }
 
-# An explicit template rather than -t, whose handling of a prefix differs
-# between the GNU and BSD versions.
+# The template is spelled out rather than passed with -t, whose handling of a
+# prefix differs between the GNU and BSD versions.
 probe=$(mktemp "${TMPDIR:-/tmp}/cgit-probe.XXXXXX")
 trap 'rm -f "$probe" "$probe.c" "$probe.out"' EXIT
 
@@ -59,7 +56,8 @@ else
 	CFLAGS="$CFLAGS -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=2"
 fi
 
-# Makes a large stack frame touch each guard page rather than step over it.
+# Without this a large stack frame can step over a guard page rather than
+# touch it.
 if supports "-fstack-clash-protection"; then
 	CFLAGS="$CFLAGS -fstack-clash-protection"
 fi
@@ -70,20 +68,20 @@ LDFLAGS="-pie \
 
 # These reach only the cgit objects, so git's own sources are not held to them.
 # -Wformat-security is an error because a non-literal format with no arguments
-# is never intentional.
-#
-# The shape that let a repository supply its own format string through
-# module-link was a non-literal *with* arguments, which only -Wformat-nonliteral
-# reports. It is left out here because it also fires on forwarding a va_list and
-# on local format constants, so it cannot be an error without false positives.
-# Worth running by hand when touching anything that formats:
+# is never intentional. The shape that let a repository supply its own format
+# string through module-link was the other one, a non-literal that does take
+# arguments, and only -Wformat-nonliteral reports that, and that one is left out because it also fires
+# on forwarding a va_list and on local format constants, so it cannot be an
+# error without false positives. It is still worth running by hand when
+# touching anything that formats.
 #
 #     make cgit CGIT_EXTRA_CFLAGS=-Wformat-nonliteral
 #
 CGIT_EXTRA_CFLAGS="-Wformat -Wformat-security -Werror=format-security"
 
-# A full rebuild so the bundled git objects pick up the same flags.
-# cleanall also descends into vendor/git, which plain clean does not.
+# The build starts from clean so the bundled git objects pick up the same
+# flags, and cleanall rather than clean because only cleanall descends into
+# vendor/git.
 make cleanall
 exec make "$@" CFLAGS="$CFLAGS" LDFLAGS="$LDFLAGS" \
 	CGIT_EXTRA_CFLAGS="$CGIT_EXTRA_CFLAGS"