Document, and add recipe_diff

make.sh

@@ -1,4 +1,24 @@
 #!/usr/bin/env sh
+#
+# td: "Telodendria Developer"
+#
+# A helper script that operates sort of like Make, except it is
+# a lot easier to read and write than a Makefile, and it works on
+# any POSIX system.
+#
+# I chose to use a custom build script instead of using Make because
+# it is much more portable and flexible. This script doesn't only
+# handle building the code, it also handles formatting it, as well
+# as generating patch files.
+
+# If a .env file exists in the current directory, we load it.
+# As Telodendria's build infrastructure relies heavily on
+# environment variables, we allow users to specify their
+# Telodendria-specific variables in a dedicated .env so they don't
+# have to pollute their environment.
+if [ -f "$(pwd)/.env" ]; then
+	. "$(pwd)/.env"
+fi
 
 #
 # Set variables
@@ -19,10 +39,9 @@
 : "${LDFLAGS:=-static -flto -fdata-sections -ffunction-sections -s -Wl,-static -Wl,-gc-sections}"
 : "${PROG:=telodendria}"
 
-if [ -f "$(pwd)/.env" ]; then
+# Check the modificiation time of a file. This is used to do
-	. "$(pwd)/.env"
+# incremental builds; we only want to rebuild files that have
-fi
+# have changed.
-
 mod_time() {
     if [ -n "$1" ] && [ -f "$1" ]; then
         case "$(uname)" in
@@ -33,6 +52,8 @@ mod_time() {
                 stat -f %m "$1" 
                 ;;
             *)
+				# Platform unknown, force rebuilding the whole
+				# project every time.
                 echo "0" 
                 ;;
         esac 
@@ -41,6 +62,8 @@ mod_time() {
     fi 
 }
 
+# Build the source code, and generate  the 'build/telodendria'
+# binary.
 recipe_build() {
 	mkdir -p build
 
@@ -69,10 +92,14 @@ recipe_build() {
 	fi
 }
 
+# Remove all build files, which can be regenerated by re-running the
+# build recipe.
 recipe_clean() {
 	rm -rv build
 }
 
+# Format the source code by updating the copyright headers and
+# then running indent(1) on each source code file.
 recipe_format() {
 	find src -name '*.c' -or -name '*.h' | while IFS= read -r src; do
 		# Update the headers
@@ -88,10 +115,13 @@ recipe_format() {
 	done
 }
 
+# Execute all the unit tests and report any failures.
 recipe_test() {
 	echo "Unit tests are not implemented yet."
 }
 
+# Deploy the Telodendria website by copying the required files to
+# a web root defined by TELODENDRIA_PUB.
 recipe_site() {
 	if [ -z "$TELODENDRIA_PUB" ]; then
 		echo "No public root directory specified."
@@ -103,6 +133,8 @@ recipe_site() {
 	cp -v site/* "$TELODENDRIA_PUB/"
 }
 
+# Generate a release tarball, checksum and sign it, and push it to
+# the web root.
 recipe_release() {
 	if [ -z "$TELODENDRIA_PUB" ]; then
 		echo "No public root directory specified."
@@ -113,14 +145,18 @@ recipe_release() {
 	mkdir -p "$TELODENDRIA_PUB/pub/v$TELODENDRIA_VERSION"
 	cd "$TELODENDRIA_PUB/pub/v$TELODENDRIA_VERSION"
 
+	# Generate release tarball
 	cvs export "-r$CVS_TAG" "Telodendria"
 	mv "Telodendria" "Telodendria-v$TELODENDRIA_VERSION"
 	tar -czf "Telodendria-v$TELODENDRIA_VERSION.tar.gz" \
 		"Telodendria-v$TELODENDRIA_VERSION"
 	rm -r "Telodendria-v$TELODENDRIA_VERSION"
+
+	# Checksum release tarball
 	sha256 "Telodendria-v$TELODENDRIA_VERSION.tar.gz" \
 		> "Telodendria-v$TELODENDRIA_VERSION.tar.gz.sha256"
 
+	# Sign release tarball
 	if [ ! -z "$TELODENDRIA_SIGNIFY_SECRET" ]; then
 		signify -S -s "$TELODENDRIA_SIGNIFY_SECRET" \
 			-m "Telodendria-v$TELODENDRIA_VERSION.tar.gz" \
@@ -131,15 +167,25 @@ recipe_release() {
 	fi
 }
 
+# Generate a formatted patch file. The Telodendria project isn't
+# really picky about how patches look, but this is how we like them
+# best. Makes them easy to read.
 recipe_patch() {
+
+	# If the user has not set their MXID, try to deduce one from
+	# their system.
 	if [ -z "$MXID" ]; then
 		MXID="@${USER}:$(hostname)"
 	fi
 
+	# If the user has not set their DISPLAY_NAME, try to deduce it
+	# from their system.
 	if [ -z "$DISPLAY_NAME" ]; then
 		DISPLAY_NAME=$(getent passwd "$USER" | cut -d ':' -f 5 | cut -d ',' -f 1)
 	fi
 
+	# If the user has not set their EDITOR, use a safe default.
+	# (vi should be available on any POSIX system)
 	if [ -z "$EDITOR" ]; then
 		EDITOR=vi
 	fi
@@ -147,24 +193,30 @@ recipe_patch() {
 	NORMALIZED_MXID=$(echo "$MXID" | sed -e 's/@//g' -e 's/:/-/g')
 	PATCH_FILE="${NORMALIZED_MXID}_$(date +%s).patch"
 
+	# Generate the actual patch file
+	# Here we write some nice headers, and then do a cvs diff.
 	(
 		printf 'From: "%s" <%s>\n' "$DISPLAY_NAME" "$MXID"
 		echo "Date: $(date)"
 		echo "Subject: "
 		echo
-		# Do a quiet diff that doesn't have any untracked files
+		cvs -q diff -uNp $PATCHSET | grep -v '^\? '
-		# listed in it.
-		cvs -q diff -uNp $PATCH | grep -v '^\? '
 	) > "$PATCH_FILE"
 
 	"$EDITOR" "$PATCH_FILE"
 	echo "$PATCH_FILE"
 }
 
+recipe_diff() {
+	cvs -q diff -uNp | less
+}
+
+# Execute the user-specified recipes.
 for recipe in $@; do
 	recipe_$recipe
 done
 
+# If no recipe was provided, run a build.
 if [ -z "$1" ]; then
 	recipe_build
 fi