Allow to specify the TinyPilot version identifier (#1871)

Follow-up of tiny-pilot/tinypilot-pro#1474,
specifically
tiny-pilot/tinypilot-pro#1474 (comment).

This PR modifies the interface of the `build-debian-pkg` dev script so
that it takes on multiple (optional) named flags, instead of just one
(optional) position argument:

- The `--build-targets` flag replaces the previous positional input
argument.
- The newly added `--tinypilot-version` now allows to set the version of
the Debian package.
- That way we are independent from the ambiguous behaviour of the `git
describe --tags` command. We can still use it as implicit default,
though. In Pro, we can then explicitly pass in the version identifier
from the CircleCI build context – without, however, by directly making
the `build-debian-pkg` script depend on the CircleCI context, e.g. by
referencing the `CIRCLE_TAG` environment variable inside of
`build-debian-pkg`.

When inspecting [the parameters of the actual
build](https://github.com/tiny-pilot/tinypilot/blob/b6f3eb00bd31751dc139c1d6439de11a6fc179f6/dev-scripts/build-debian-pkg#L47),
the changes appear to work fine:

- [`--platform linux/arm/v7 --build-arg
TINYPILOT_VERSION=1.9.5-11+7fae51d`](https://app.circleci.com/pipelines/github/tiny-pilot/tinypilot/4721/workflows/5030b62c-eed8-4536-bf57-772374560679/jobs/35226?invite=true#step-103-182_107)
(this PR)
- [`--platform linux/arm/v7 --build-arg
TINYPILOT_VERSION=1.9.5-8+b6f3eb0`](https://app.circleci.com/pipelines/github/tiny-pilot/tinypilot/4718/workflows/b01d881c-1620-4737-93c1-716d9dba93aa/jobs/35190?invite=true#step-103-390_107)
(latest master)

<a data-ca-tag
href="https://codeapprove.com/pr/tiny-pilot/tinypilot/1871"><img
src="https://codeapprove.com/external/github-tag-allbg.png" alt="Review
on CodeApprove" /></a>

---------

Co-authored-by: Jan Heuermann <jan@jotaen.net>

Author: jotaen4tinypilot

.circleci/config.yml

@@ -181,7 +181,9 @@ jobs:
           docker_layer_caching: true
       - run:
           name: Build Debian package
-          command: ./dev-scripts/build-debian-pkg linux/arm/v7
+          command: |
+            ./dev-scripts/build-debian-pkg \
+              --build-targets linux/arm/v7
       - run:
           name: Print Debian package contents
           command: dpkg --contents debian-pkg/releases/tinypilot*.deb

CONTRIBUTING.md

@@ -285,7 +285,7 @@ Once your dev system is configured for multi-architecture Docker builds, you can
 TARGET_PLATFORM='linux/arm/v7'
 
 (rm debian-pkg/releases/tinypilot*.deb || true) && \
-  ./dev-scripts/build-debian-pkg "${TARGET_PLATFORM}" && \
+  ./dev-scripts/build-debian-pkg --build-targets "${TARGET_PLATFORM}" && \
   mv debian-pkg/releases/tinypilot*.deb bundler/bundle && \
   ./bundler/create-bundle
 ```

dev-scripts/build-debian-pkg

@@ -1,39 +1,68 @@
 #!/bin/bash
 #
-# Build TinyPilot Debian packages.
-#
-# Usage:
-#   build-debian-pkg [target architectures]
-#
-# target architecture: A comma-separated list of architectures that Docker
-#   accepts for its --platform argument. If omitted, defaults to
-#   "linux/arm/v7,linux/amd64". The only supported targets are linux/arm/v7 and
-#   linux/amd64.
-#
-# Examples
-#  build-debian-pkg "linux/arm/v7"
-#  build-debian-pkg "linux/arm/v7,linux/amd64"
+# Build a TinyPilot Debian package.
 
 # Exit build script on first failure.
 set -e
 
-# Echo commands before executing them, by default to stderr.
-set -x
-
 # Exit on unset variable.
 set -u
 
-BUILD_TARGETS="${1:-linux/arm/v7,linux/amd64}"
+print_help() {
+  cat <<EOF
+Usage: ${0##*/} [--help] [--build-targets BUILD_TARGETS] [--tinypilot-version TINYPILOT_VERSION]
+Build a TinyPilot Debian package.
+  --help                                  Optional. Display this help and exit.
+  --build-targets BUILD_TARGETS           Optional. A comma-separated list of architectures
+                                          that Docker accepts for its --platform argument.
+                                          If omitted, defaults to "linux/arm/v7,linux/amd64".
+                                          The only supported targets are "linux/arm/v7" and
+                                          "linux/amd64".
+  --tinypilot-version TINYPILOT_VERSION   Optional. The version identifier that shall be
+                                          assigned. If omitted, determines the version string
+                                          automatically, in the "x.y.z-i+hhhhhhh" format that
+                                          we use for nightly builds.
+EOF
+}
 
 print_tinypilot_version() {
   # Format build hash suffix according to SemVer (`-ghhhhhhh` -> `+hhhhhhh`).
   git describe --tags --long |
   sed --expression 's/\(-g\([0-9a-f]\{7\}\)\)$/+\2/g'
 }
 
+# Parse command-line arguments.
+BUILD_TARGETS='linux/arm/v7,linux/amd64'
 TINYPILOT_VERSION="$(print_tinypilot_version)"
+while (( "$#" > 0 )); do
+  case "$1" in
+    --help)
+      print_help
+      exit
+      ;;
+    --build-targets)
+      BUILD_TARGETS="$2"
+      shift # For flag name.
+      shift # For flag value.
+      ;;
+    --tinypilot-version)
+      TINYPILOT_VERSION="$2"
+      shift # For flag name.
+      shift # For flag value.
+      ;;
+   *)
+      >&2 echo "Unknown argument: $1"
+      >&2 echo "Use the '--help' flag for more information"
+      exit 1
+      ;;
+  esac
+done
+readonly BUILD_TARGETS
 readonly TINYPILOT_VERSION
 
+# Echo commands before executing them, by default to stderr.
+set -x
+
 PKG_VERSION="$(date '+%Y%m%d%H%M%S')"
 readonly PKG_VERSION
 

dev-scripts/device/install-from-source

@@ -22,7 +22,7 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 readonly SCRIPT_DIR
 cd "${SCRIPT_DIR}/.."
 
-./dev-scripts/build-debian-pkg "linux/arm/v7"
+./dev-scripts/build-debian-pkg --build-targets 'linux/arm/v7'
 
 # Shellcheck recommends find instead of ls for non-alphanumeric filenames, but
 # we don't expect non-alphanumeric filenames, and the find equivalent is more