Trac #23160: Add a library of common helper functions for use in spkg…

…-install

This idea has come up before but not been implemented.  My
implementation simply adds a collection of shell functions with names
prefixed by `sdh_` for Sage distribution helpers (this is somewhat
inspired by, but much simpler than, the `dh_` programs from the
`debhelper` package in Debian).

These functions are exported by `sage-spkg`, and so are immediately
usable by any `spkg-build`, `spkg-install`, or similar scripts executed
from `sage-spkg` (these are still not required to be shell scripts, but
as most are having such a library is convenient).

One piece of boilerplate I replaced with a function is the check in most
`spkg-install`s for `$SAGE_LOCAL`.  A downside to this is that if the
script is run outside the correct environment, then rather than getting
a useful error message we just get that `sdh_check_vars` is undefined.
I have two thoughts on this:

1) In general these scripts shouldn't be run directly in the first
place.  In the case that they are (such as testing) the person
developing the package should have some awareness of the fact that these
scripts are being run from `sage-spkg` and assume `sage-env` has been
sourced.

2) Most of the time these scripts are run, it's after they've been
copied to a temporary build directory for the package.  If nothing else,
`sage-spkg` could create a wrapper around these scripts that
automatically sets some default assumptions (such as sourcing `sage-env`
and the new `sage-dist-helpers`).

In general, though, I think having a library of helper functions will be
a big improvement to the consistency and legibility of theses scripts.

This ticket also updates the `spkg-install` for `patch` for
demonstration purposes only.  I don't intend with this to go on a mass
rewriting of install scripts, but having this will be helpful for some
other work (e.g. #22509, #22510).

URL: https://trac.sagemath.org/23160
Reported by: embray
Ticket author(s): Erik Bray
Reviewer(s): Jeroen Demeyer

build/bin/sage-spkg

@@ -21,6 +21,9 @@
 #      SAGE_ROOT      -- root directory of sage install
 #      SAGE_LOCAL     -- $SAGE_ROOT/local
 #      SAGE_DISTFILES -- directory that stores upstream tarballs
+#      PKG_BASE       -- the base name of the package itself (e.g. 'patch')
+#      PKG_VER        -- the version number of the package
+#      PKG_NAME       -- $PKG_BASE-$PKG_VER
 #      LIBRARY_PATH, PYTHONPATH, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH
 #      CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS, MAKE
 #
@@ -153,6 +156,7 @@ fi
 # than exiting.  Using dot suggested by W. Cheung.
 . sage-env
 
+
 if [ $? -ne 0 ]; then
     error_msg "Error setting environment variables by sourcing sage-env"
     exit 1
@@ -673,9 +677,23 @@ export SAGE_ROOT="$SAGE_ROOT"
 export SAGE_SRC="$SAGE_SRC"
 export SAGE_PKG_DIR="$pkgdir"
 
-source "\$SAGE_SRC/bin/sage-env"
+export PKG_NAME="$PKG_NAME"
+export PKG_BASE="$PKG_BASE"
+export PKG_VER="$PKG_VER"
+
+for lib in env dist-helpers; do
+    lib="sage-\$lib"
+    source "\$SAGE_SRC/bin/\$lib"
+    if [ \$? -ne 0 ]; then
+        echo >&2 "Error: failed to source \$lib"
+        echo >&2 "Is \$SAGE_ROOT the correct SAGE_ROOT?"
+        exit 1
+    fi
+done
+
+sdh_guard
 if [ \$? -ne 0 ]; then
-    echo >&2 "Error: failed to source sage-env; is \$SAGE_ROOT the correct SAGE_ROOT?"
+    echo >&2 "Error: sdh_guard not found; Sage environment was not set up properly"
     exit 1
 fi
 
@@ -786,6 +804,7 @@ export rsync_proxy=$http_proxy
 # Actually install
 ##################################################################
 
+
 if [ -f spkg-build ]; then
     # Package has both spkg-build and spkg-install; execute the latter with SAGE_SUDO
     time ./spkg-build

build/pkgs/patch/spkg-install

@@ -1,9 +1,3 @@
-if [ -z "$SAGE_LOCAL" ]; then
-    echo >&2 "Error: SAGE_LOCAL undefined - exiting..."
-    echo >&2 "Maybe run 'sage -sh'?"
-    exit 1
-fi
-
 # Let the user define the environment variable CFLAG64 to
 # something if their C compiler needs a compiler flag other than
 # -m64 to build 64-bit objects. This would be the case with IBM's
@@ -32,24 +26,9 @@ if [ "x$UNAME" = xAIX ] ; then
 fi
 
 cd src
-
-./configure --prefix="$SAGE_LOCAL"
-if [ $? -ne 0 ]; then
-    echo >&2 "Error configuring GNU patch"
-    exit 1
-fi
-
-$MAKE
-if [ $? -ne 0 ]; then
-    echo >&2 "Error building GNU patch"
-    exit 1
-fi
-
-$MAKE install
-if [ $? -ne 0 ]; then
-    echo >&2 "Error installing GNU patch"
-    exit 1
-fi
+sdh_configure
+sdh_make
+sdh_make_install
 
 if [ "$UNAME" = "CYGWIN" ] ; then
     cp ../patch.exe.manifest "$SAGE_LOCAL/bin/"

src/bin/sage-dist-helpers

@@ -0,0 +1,87 @@
+# Shell functions for making spkg-install scripts a little easier to write,
+# eliminating duplication.  All Sage helper functions begin with sdh_ (for
+# Sage-distribution helper).  Consult the below documentation for the list of
+# available helper functions:
+#
+# - sdh_check_vars [VARIABLE ...]
+#
+#    Check that one or more variables are defined and non-empty, and exit with
+#    an error if any are undefined or empty. Variable names should be given
+#    without the '$' to prevent unwanted expansion.
+#
+# - sdh_guard
+#
+#    Wrapper for `sdh_check_vars` that checks some common variables without
+#    which many/most packages won't build correctly (SAGE_ROOT, SAGE_LOCAL,
+#    SAGE_SHARE). This is important to prevent installation to unintended
+#    locations.
+#
+# - sdh_configure [...]
+#
+#    Runs `./configure --prefix="$SAGE_LOCAL"`.  Additional arguments to
+#    `./configure` may be given as arguments.
+#
+# - sdh_make [...]
+#
+#    Runs `$MAKE` with the default target.  Additional arguments to `make` may
+#    be given as arguments.
+#
+# - sdh_make_install [...]
+#
+#    Runs `$SAGE_SUDO $MAKE install`.  Additional arguments to `make` may be
+#    given as arguments.
+
+set -o allexport
+
+sdh_check_vars() {
+    local varname
+    while [ -n "$1" ]; do
+        if [ -z "$(eval "echo "\${${1}+isset}"")" ]; then
+            echo >&2 "${1} undefined ... exiting"
+            echo >&2 "Maybe run 'sage --sh'?"
+            exit 1
+        fi
+        shift
+    done
+}
+
+
+sdh_guard() {
+    sdh_check_vars SAGE_ROOT SAGE_LOCAL SAGE_SHARE
+}
+
+
+sdh_configure() {
+    local ret
+    ./configure --prefix="$SAGE_LOCAL" "$@"
+    ret=$?
+    if [ $ret -ne 0 ]; then
+        echo >&2 "Error configuring $PKG_NAME"
+        exit $ret
+    fi
+}
+
+
+sdh_make() {
+    local ret
+    ${MAKE:-make} "$@"
+    ret=$?
+    if [ $ret -ne 0 ]; then
+        echo >&2 "Error building $PKG_NAME"
+        exit $ret
+    fi
+}
+
+
+sdh_make_install() {
+    local ret
+    $SAGE_SUDO ${MAKE:-make} install "$@"
+    ret=$?
+    if [ $ret -ne 0 ]; then
+        echo >&2 "Error installing $PKG_NAME"
+        exit $ret
+    fi
+}
+
+
+set +o allexport