tools/ci.sh: Make this script runnable as command.

This makes it easier to run a sequence of ci steps locally.  A help message
is also provided.

Signed-off-by: Jeff Epler <jepler@gmail.com>

2 files changed, 81 insertions, 0 deletions

diff --git a/docs/develop/gettingstarted.rst b/docs/develop/gettingstarted.rst
index 329d218a8..b625a72c9 100644
--- a/docs/develop/gettingstarted.rst
+++ b/docs/develop/gettingstarted.rst
@@ -282,6 +282,30 @@ To run a selection of tests on a board/device connected over USB use:
 
 See also :ref:`writingtests`.
 
+Using ci.sh locally
+-------------------
+
+MicroPython uses GitHub Actions for continuous integration.
+To reduce dependence on any specific CI system, the actual build steps for Unix-based builds are in the file ``tools/ci.sh``.
+This can also be used as a script on developer desktops, with caveats:
+
+* For most steps, An Ubuntu/Debian system similar to the one used during CI is assumed.
+* Some specific steps assume specific Ubuntu versions.
+* The setup steps may invoke the system package manager to install packages,
+  download and install software from the internet, etc.
+
+To get a usage message including the list of commands, run:
+
+.. code-block:: bash
+
+   $ tools/ci.sh --help
+
+As an example, you can build and test the unix minimal port with:
+
+.. code-block:: bash
+
+   $ tools/ci.sh unix_minimal_build unix_minimal_run_tests
+
 Folder structure
 ----------------
 
diff --git a/tools/ci.sh b/tools/ci.sh
index 901059991..6b974f983 100755
--- a/tools/ci.sh
+++ b/tools/ci.sh
@@ -970,3 +970,60 @@ function ci_alif_ae3_build {
     make ${MAKEOPTS} -C ports/alif BOARD=OPENMV_AE3 MCU_CORE=M55_DUAL
     make ${MAKEOPTS} -C ports/alif BOARD=ALIF_ENSEMBLE MCU_CORE=M55_DUAL
 }
+
+function _ci_help {
+    # Note: these lines must be indented with tab characters (required by bash <<-EOF)
+    cat <<-EOF
+	ci.sh: Script fragments used during CI
+
+	When invoked as a script, runs a sequence of ci steps,
+	stopping after the first error.
+
+	Usage:
+	    ${BASH_SOURCE} step1 step2...
+
+	Steps:
+	EOF
+    if type -path column > /dev/null 2>&1; then
+        grep '^function ci_' $0 | awk '{print $2}' | sed 's/^ci_//' | column
+    else
+        grep '^function ci_' $0 | awk '{print $2}' | sed 's/^ci_//'
+    fi
+    exit
+}
+
+function _ci_main {
+    case "$1" in
+        (-h|-?|--help)
+            _ci_help
+        ;;
+        (*)
+            cd $(dirname "$0")/..
+            while [ $# -ne 0 ]; do
+                ci_$1
+                shift
+            done
+        ;;
+    esac
+}
+
+# https://stackoverflow.com/questions/2683279/how-to-detect-if-a-script-is-being-sourced
+sourced=0
+if [ -n "$ZSH_VERSION" ]; then
+  case $ZSH_EVAL_CONTEXT in *:file) sourced=1;; esac
+elif [ -n "$KSH_VERSION" ]; then
+  [ "$(cd -- "$(dirname -- "$0")" && pwd -P)/$(basename -- "$0")" != "$(cd -- "$(dirname -- "${.sh.file}")" && pwd -P)/$(basename -- "${.sh.file}")" ] && sourced=1
+elif [ -n "$BASH_VERSION" ]; then
+  (return 0 2>/dev/null) && sourced=1
+else # All other shells: examine $0 for known shell binary filenames.
+     # Detects `sh` and `dash`; add additional shell filenames as needed.
+  case ${0##*/} in sh|-sh|dash|-dash) sourced=1;; esac
+fi
+
+if [ $sourced -eq 0 ]; then
+    # invoked as a command
+    if [ "$#" -eq 0 ]; then
+        set -- --help
+    fi
+    _ci_main "$@"
+fi