test: Improve make detect-libs & Use it (Dockerfile.test-server)

* Fix the Makefile's var DUNE_ARGS to be opam+dune compliant
  href: https://dune.readthedocs.io/en/stable/opam.html#invocation-from-opam
* Ensure `make detect-libs` can be run within opam's sandbox
* Remove `*.sexp` files beforehand;
  Note: `make detect-libs` overwrites the binaries with "dynamic" ones
* Ensure `linking_flags.sh` also prints the final flags to STDERR
* Improve the Makefile documentation a bit:
  useful to debug the linking flags for static binaries using GHA logs

Dockerfile.test-server

@@ -30,6 +30,9 @@ RUN sudo chown -R opam:nogroup .
 
 ENV OPAMVERBOSE 1
 
+# Run "make detect-libs"
+ENV OPAMWITHTEST 1
+
 RUN opam install learn-ocaml --destdir /home/opam/install-prefix \
   && ls -l /home/opam/install-prefix/bin/learn-ocaml
 

Makefile

@@ -1,7 +1,7 @@
 all: static build
 
 DUNE = dune
-DUNE_ARGS = --profile=release
+DUNE_ARGS = --root . --profile=release --default-target @install
 INDEX_ODOC_PATH = docs/odoc.html
 
 build-deps:
@@ -100,20 +100,37 @@ static-binaries:
 	./scripts/static-build.sh
 
 BINARIES = src/main/learnocaml_client.bc.exe src/main/learnocaml_main.bc.exe src/main/learnocaml_server_main.exe
+SEXP = src/main/linking_client.sexp src/main/linking_main.sexp src/main/linking_server.sexp
 
 .PHONY: detect-libs
+# HINTS to rely on this target using GitHub Action logs:
+# * Open (old successful run, new run) for "build-macos.yml"
+# * Search for the string "# make detect libs", then Compare
+# * Open (old successful run, new run= for "build-and-test.yml (Dockerfile.test-server)"
+# * Search for the string "# make detect libs", then Compare
+#
+# * Update "src/main/linking_flags.sh" (common) or "src/main/dune" (ad-hoc) or:
+#
+# * Open (old successful run) for "static-builds.yml"
+# * Search for the string ";; generated by ./linking_flags.sh"
+# * Remember that "m" and "pthread" are built-in, then Conclude
+#
+# * Update "src/main/linking_flags.sh" (common) or "src/main/dune" (ad-hoc).
 detect-libs:
-	$(RM) $(addprefix _build/default/,$(BINARIES))
+	# Running: make LINKING_MODE=dynamic OCAMLPARAM="_,verbose=1"
+	$(RM) $(addprefix _build/default/,$(BINARIES) $(SEXP))
 	+sort=false; \
-	baseid="detect-libs.$$$$"; echo ...; \
-	$(MAKE) LINKING_MODE=dynamic OCAMLPARAM="_,verbose=1" > $$baseid.log 2>&1; \
+	baseid=$$(mktemp -d "$$PWD/detect-libs.XXXXXX"); \
+	$(MAKE) LINKING_MODE=dynamic OCAMLPARAM="_,verbose=1" > $$baseid/verb.log 2>&1 || exit 1; \
+	echo "# make detect-libs"; \
 	for bin in $(BINARIES); do \
-	  rm -f "_build/default/$$bin"; \
 	  base=$${bin#src/main/}; base=$${base%.*}; \
-	  grep -e "'$$bin'" $$baseid.log > $$baseid.$$base.log; \
+	  grep -e "'$$bin'" $$baseid/verb.log > $$baseid/verb.$$base.log; \
 	  printf "%s: " "$$base"; \
-	  ( sed -e "s/'//g; s/ /\\$$(printf '\n/g')" $$baseid.$$base.log | grep -e "^-l" | \
+	  ( sed -e "s/'//g; s/ /\\$$(printf '\n/g')" $$baseid/verb.$$base.log | grep -e "^-l" | \
 	    if [ "$$sort" = true ]; then printf "(sorted) "; sort -u; else cat; fi | xargs echo ); \
 	done; echo; \
-	cat $$baseid.*.log; \
-	$(RM) $$baseid.*log
+	cat $$baseid/verb.*.log; \
+	$(RM) $$baseid/verb*log; \
+	rmdir $$baseid
+	# Overwrote: $(addprefix _build/default/,$(BINARIES) $(SEXP))

learn-ocaml.opam

@@ -66,6 +66,7 @@ depends: [
 build: [
   [make "static"]
   ["dune" "build" "-p" name "-j" jobs]
+  [make "detect-libs"] {with-test}
 ]
 install: [
   ["mkdir" "-p" "%{_:share}%"]

src/main/dune

@@ -64,12 +64,12 @@
 (rule
   (targets linking_main.sexp)
   (action  (with-stdout-to %{targets}
-    (run ./linking_flags.sh %{env:LINKING_MODE=dynamic} %{ocaml-config:system} checkseum_c_stubs threads camlrun))))
+    (run ./linking_flags.sh linking_main.sexp %{env:LINKING_MODE=dynamic} %{ocaml-config:system} checkseum_c_stubs threads camlrun))))
 (rule
   (targets linking_client.sexp)
   (action  (with-stdout-to %{targets}
-    (run ./linking_flags.sh %{env:LINKING_MODE=dynamic} %{ocaml-config:system} threads camlrun))))
+    (run ./linking_flags.sh linking_client.sexp %{env:LINKING_MODE=dynamic} %{ocaml-config:system} threads camlrun))))
 (rule
   (targets linking_server.sexp)
   (action  (with-stdout-to %{targets}
-    (run ./linking_flags.sh %{env:LINKING_MODE=dynamic} -- checkseum_c_stubs threadsnat))))
+    (run ./linking_flags.sh linking_server.sexp %{env:LINKING_MODE=dynamic} -- checkseum_c_stubs threadsnat))))

src/main/linking_flags.sh

@@ -8,26 +8,35 @@ set -ue
 LC_ALL=C
 
 help_exit() {
-    echo "Usage: $0 dynamic|static linux|macosx [extra-libs]" >&2
+    echo "Usage: $0 descriptiveID dynamic|static linux|macosx [extra-libs]" >&2
     exit 2
 }
 
-[ $# -lt 2 ] && help_exit
+echo2() {
+    echo "$*" >&2
+    echo "$*"
+}
+
+[ $# -lt 3 ] && help_exit
+
+descID="$1"
+shift
 
-echo ";; generated by $0"
+echo2 ";; $descID"
+echo2 ";; generated by $0"
 
 case "$1" in
-    dynamic) echo "()"; exit 0;;
+    dynamic) echo2 "()"; exit 0;;
     static) ;;
-    *) echo "Invalid linking mode '$1'."; help_exit
+    *) echo "Invalid linking mode '$1'." >&2; help_exit
 esac
 
 shift
 case "$1" in
     macosx) shift; EXTRA_LIBS="curses $*";;
     linux) shift; EXTRA_LIBS="$*";;
     --) shift; EXTRA_LIBS="$*";;
-    *) echo "Not supported %{ocamlc-config:system} '$1'."; help_exit
+    *) echo "Not supported %{ocamlc-config:system} '$1'." >&2; help_exit
 esac
 
 ## Static linking configuration ##
@@ -45,29 +54,29 @@ case $(uname -s) in
             alpine)
                 COMMON_LIBS="camlstr ssl_threads_stubs ssl crypto cstruct_stubs bigstringaf_stubs lwt_unix_stubs unix c"
                 # `m` and `pthread` are built-in musl
-                echo '(-noautolink'
-                echo ' -cclib -Wl,-Bstatic'
-                echo ' -cclib -static-libgcc'
+                echo2 '(-noautolink'
+                echo2 ' -cclib -Wl,-Bstatic'
+                echo2 ' -cclib -static-libgcc'
                 for l in $EXTRA_LIBS $COMMON_LIBS; do
-                    echo " -cclib -l$l"
+                    echo2 " -cclib -l$l"
                 done
-                echo ' -cclib -static)'
+                echo2 ' -cclib -static)'
                 ;;
             *)
-                echo "Error: static linking is only supported in Alpine, to avoids glibc constraints (use scripts/static-build.sh to build through an Alpine Docker container)" >&2
+                echo2 "Error: static linking is only supported in Alpine, to avoids glibc constraints (use scripts/static-build.sh to build through an Alpine Docker container)" >&2
                 exit 3
         esac
         ;;
     Darwin)
         COMMON_LIBS="camlstr ssl_threads_stubs /usr/local/opt/openssl/lib/libssl.a /usr/local/opt/openssl/lib/libcrypto.a cstruct_stubs bigstringaf_stubs lwt_unix_stubs unix"
         # `m` and `pthread` are built-in in libSystem
-        echo '(-noautolink'
+        echo2 '(-noautolink'
         for l in $EXTRA_LIBS $COMMON_LIBS; do
-            if [ "${l%.a}" != "${l}" ]; then echo " -cclib $l"
-            else echo " -cclib -l$l"
+            if [ "${l%.a}" != "${l}" ]; then echo2 " -cclib $l"
+            else echo2 " -cclib -l$l"
             fi
         done
-        echo ')'
+        echo2 ')'
         ;;
     *)
         echo "Static linking is not supported for your platform. See $0 to contribute." >&2