Add the ability to specify location of qtype_stack libraries

by Git remote and commit hash.

Two new build args have been added to the Dockerfile:

  - QTYPE_STACK_REMOTE
  - QTYPE_STACK_COMMIT

When both are specified, the qtype_stack libraries will be
retreived from the specified Git remote at the specified
commit hash (a tag may also be used). The asset file
maximalocal.mac.template will be dynamically generated
from the libraries cloned from Git.

These new build args can work in conjunction with the
MAXIMA_VERSION and SBCL_VERSION build args.

  - When no MAXIMA_VERSION or SBCL_VERSION arg is
    supplied, the appropriate versions to use are
    extracted from the version matrix specified
    in the versions file
  - When MAXIMA_VERSION or SBCL_VERSION is supplied
    the specified version(s) will be used and trump
    anything specified in the versions file.

The Dockerfile is backwards compatible, meaning that
buildimage.sh continues to work exactly as it did
before.

Thank you to Benjamin Southall for work on the
generate_maximalocal_template.php script.

Dockerfile

@@ -10,6 +10,11 @@ FROM debian:12
 ARG MAXIMA_VERSION
 # e.g. 2.0.2
 ARG SBCL_VERSION
+# e.g. https://github.com/maths/moodle-qtype_stack
+ARG QTYPE_STACK_REMOTE
+# e.g. 6aff282a
+# e.g. v4.8.1
+ARG QTYPE_STACK_COMMIT
 
 # number of maxima-%d user names/maximum number of processes
 ARG MAX_USER=32
@@ -22,20 +27,62 @@ ENV SRC=/opt/src \
     ASSETS=/opt/maxima/assets \
     BIN=/opt/maxima/bin
 
-COPY ./src/maxima_fork.c /
-COPY ./buildscript.sh /
-
-RUN bash /buildscript.sh
+COPY ./src/maxima_fork.c ./buildscript.sh ./versions /
+
+# Copy optimization scripts and template generation script.
+COPY assets/maxima-fork.lisp assets/optimize.mac.template ./assets/generate_maximalocal_template.php ${ASSETS}/
+
+# If QTYPE_STACK_REMOTE and QTYPE_STACK_COMMIT were both specified, we clone the repo and check
+# it out at the specified commit.
+RUN if [ -n "$QTYPE_STACK_REMOTE" ] && [ -n "$QTYPE_STACK_COMMIT" ]; then \
+    apt-get update && apt-get install -y git php \
+    && git clone ${QTYPE_STACK_REMOTE} qtype_stack && cd qtype_stack && git checkout ${QTYPE_STACK_COMMIT}; \
+fi
+
+# If building from qtype_stack directly, once the libraries are cloned we copy everything in to
+# the appropriate place and generate the maximalocal.mac.template file, also putting it in the
+# correct place.
+RUN if [ -n "$QTYPE_STACK_REMOTE" ] && [ -n "$QTYPE_STACK_COMMIT" ]; then \
+    mkdir -p ${LIB} && mkdir -p ${ASSETS} \
+    && cp -r qtype_stack/stack/maxima/* ${LIB} \
+    && cp qtype_stack/stack/cas/casstring.units.class.php ./ \
+    && sed -i 's/require_once/\/\/ require_once/g' casstring.units.class.php \
+    && php ${ASSETS}/generate_maximalocal_template.php > ${ASSETS}/maximalocal.mac.template; \
+fi
+
+# If building from qtype_stack, We then determine the stackmaxima version, and look it up in
+# our version matrix (similar to what the buildimage.sh script does) to find the appropriate
+# Maxima and SBCL versions to use. If MAXIMA_VERSION and SBCL_VERSION were specified as build
+# args, they trump any values determined here.
+#
+# Finally, we call buildscript (regardless of if QTYPE_STACK_REMOTE and QTYPE_STACK_COMMIT were set
+# because the values can still be optained from the original build args; and if they are missing the
+# build script will throw an error) to create the environment where we will ultimately configure Maxima.
+RUN if [ -n "$QTYPE_STACK_REMOTE" ] && [ -n "$QTYPE_STACK_COMMIT" ]; then \
+    stackver=$(tail -n1 qtype_stack/stack/maxima/stackmaxima.mac | cut -d ':' -f2 | tr -d '$') \
+    && verstring=$(awk '$1 == "'"$stackver"'"{ print $0 }' versions) \
+    && export MAXIMA_VERSION=${MAXIMA_VERSION:-$(echo "$verstring" | cut -f2)} \
+    && export SBCL_VERSION=${SBCL_VERSION:-$(echo "$verstring" | cut -f3)}; \
+fi && ./buildscript.sh
 
 # e.g. stack/20200701/maxima
 ARG LIB_PATH
 
-RUN echo ${LIB_PATH?Error \$LIB_PATH is not defined}
-# Copy Libraries
-COPY ${LIB_PATH} ${LIB}
-
-# Copy optimization scripts
-COPY assets/maxima-fork.lisp assets/optimize.mac.template ${LIB_PATH}/../maximalocal.mac.template ${ASSETS}/
+# If QTYPE_STACK_REMOTE or QTYPE_STACK_COMMIT are empty, we cannot retrieve the libraries using Git and must enforce
+# LIB_PATH is set so we can copy the libraries from there.
+RUN if ([ -z "$QTYPE_STACK_REMOTE" ] || [ -z "$QTYPE_STACK_COMMIT" ]) && [ -z "$LIB_PATH" ]; then \
+    echo "\$LIB_PATH is not defined" \
+    && exit 1; \
+fi
+
+# Copy Libraries. If LIB_PATH was not specified, nothing is copied (because LIB_PATH will
+# expand to DOESNOTEXIST, and DOESNOTEXIST* matches nothing in the build context) so the
+# libraries cloned from Git that are already in place will be used.
+COPY ${LIB_PATH:-DOESNOTEXIST}* ${LIB}
+
+# If LIB_PATH was not set, the maximalocal.mac.template file will not be copied and the one generated from
+# the libraries cloned from Git will be in place to use.
+COPY ${LIB_PATH}/../maximalocal.mac.template* ${ASSETS}/
 
 RUN grep stackmaximaversion ${LIB}/stackmaxima.mac | grep -oP "\d+" >> /opt/maxima/stackmaximaversion \
     && sh -c 'envsubst < ${ASSETS}/maximalocal.mac.template > ${ASSETS}/maximalocal.mac \

README.md

@@ -76,6 +76,7 @@ What Stackmaxima version do I need?
 Building a Docker Image
 =======================
 
+## Using a bundled stackmaxima
 There are prebuilt images are already available on the [dockerhub](https://hub.docker.com/r/mathinstitut/goemaxima).
 This section just describes the build process in case you want to build your own image anyway.
 Normally, you can just skip this step and go to [Using the Docker Image](#using-the-docker-image) directly.
@@ -91,6 +92,14 @@ The image should then be available as `goemaxima:2020061000-dev`.
 
 The supported stackmaxima versions can be seen by looking at the versions file of the root of this repository.
 
+## Dynamically building against qtype_stack
+The Docker buildfile can also build an image that will work with a specified version of [Moodle's qtype_stack plugin](https://github.com/maths/moodle-qtype_stack).
+By providing the build arguments `QTYPE_STACK_REMOTE` and `QTYPE_STACK_COMMIT` the appropriate stackmaxima libraries 
+will be extracted and the image will be built using the appropriate Maxima and SBCL versions (based on the versions
+file in this repository).
+
+If the build args `MAXIMA_VERSION` or `SBCL_VERSION` are specified alongside `QTYPE_STACK_REMOTE` and `QTYPE_STACK_COMMIT`
+then the specified Maxima or SBCL version will be used, instead of being inferred from the versions file.
 
 Environment Variables
 =====================

assets/generate_maximalocal_template.php

+<?php
+
+define('MOODLE_INTERNAL', true);
+class moodle_exception extends exception {};
+
+require_once('casstring.units.class.php');
+
+?>
+file_search_maxima:append( [sconcat("${LIB}/###.{mac,mc}")] , file_search_maxima)$
+file_search_lisp:append( [sconcat("${LIB}/###.{lisp}")] , file_search_lisp)$
+file_search_maxima:append( [sconcat("${LOG}/###.{mac,mc}")] , file_search_maxima)$
+file_search_lisp:append( [sconcat("${LOG}/###.{lisp}")] , file_search_lisp)$
+
+STACK_SETUP(ex):=block(
+    MAXIMA_VERSION_NUM_EXPECTED:"${MAXIMA_VERSION:2:4}",
+    MAXIMA_PLATFORM:"server",
+    maxima_tempdir:"${TMP}",
+    IMAGE_DIR:"${PLOT}",
+    PLOT_SIZE:[450,300],
+    PLOT_TERMINAL:"svg",
+    PLOT_TERM_OPT:"dynamic font \",11\" linewidth 1.2",
+    DEL_CMD:"rm",
+    GNUPLOT_CMD:"gnuplot",
+    MAXIMA_VERSION_EXPECTED:"${MAXIMA_VERSION}",
+    URL_BASE:"!ploturl!",
+<?php echo stack_cas_casstring_units::maximalocal_units(); ?>
+    true)$