ci-install, ci-build: add brief documentation for parameter variables

Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=98889

2 files changed, 51 insertions, 0 deletions

diff --git a/tools/ci-build.sh b/tools/ci-build.sh
index 35cf190a..79d54deb 100755
--- a/tools/ci-build.sh
+++ b/tools/ci-build.sh
@@ -26,13 +26,42 @@ set -euo pipefail
 set -x
 
 NULL=
+
+# ci_buildsys:
+# Build system under test: autotools or cmake
 : "${ci_buildsys:=autotools}"
+
+# ci_docker:
+# If non-empty, this is the name of a Docker image. ci-install.sh will
+# fetch it with "docker pull" and use it as a base for a new Docker image
+# named "ci-image" in which we will do our testing.
+#
+# If empty, we test on "bare metal".
+# Typical values: ubuntu:xenial, debian:jessie-slim
 : "${ci_docker:=}"
+
+# ci_host:
+# See ci-install.sh
 : "${ci_host:=native}"
+
+# ci_parallel:
+# A number of parallel jobs, passed to make -j
 : "${ci_parallel:=1}"
+
+# ci_sudo:
+# If yes, assume we can get root using sudo; if no, only use current user
 : "${ci_sudo:=no}"
+
+# ci_test:
+# If yes, run tests; if no, just build
 : "${ci_test:=yes}"
+
+# ci_test_fatal:
+# If yes, test failures break the build; if no, they are reported but ignored
 : "${ci_test_fatal:=yes}"
+
+# ci_variant:
+# One of debug, reduced, legacy, production
 : "${ci_variant:=production}"
 
 if [ -n "$ci_docker" ]; then
diff --git a/tools/ci-install.sh b/tools/ci-install.sh
index ddab0467..b01c28ab 100755
--- a/tools/ci-install.sh
+++ b/tools/ci-install.sh
@@ -26,10 +26,32 @@ set -euo pipefail
 set -x
 
 NULL=
+
+# ci_distro:
+# OS distribution in which we are testing
+# Typical values: ubuntu, debian; maybe fedora in future
 : "${ci_distro:=ubuntu}"
+
+# ci_docker:
+# If non-empty, this is the name of a Docker image. ci-install.sh will
+# fetch it with "docker pull" and use it as a base for a new Docker image
+# named "ci-image" in which we will do our testing.
 : "${ci_docker:=}"
+
+# ci_host:
+# Either "native", or an Autoconf --host argument to cross-compile
+# the package
 : "${ci_host:=native}"
+
+# ci_in_docker:
+# Used internally by ci-install.sh. If yes, we are inside the Docker image
+# (ci_docker is empty in this case).
 : "${ci_in_docker:=no}"
+
+# ci_suite:
+# OS suite (release, branch) in which we are testing.
+# Typical values for ci_distro=debian: sid, jessie
+# Typical values for ci_distro=fedora might be 25, rawhide
 : "${ci_suite:=trusty}"
 
 if [ $(id -u) = 0 ]; then