Merge branch 'main' into v1.0.2

compiler/README.adoc

@@ -87,10 +87,12 @@ and test artifacts.
 
 == Building Native Binaries
 
+*Running the release script:*
 You can use the `release` script in this directory to build native
 binaries of the FPP tools.
-The script uses the `native-image` tool of GraalVM to convert JAR
-files to native binaries.
+The script uses the `native-image` tool of GraalVM to convert JVM (Java
+Virtual Machine) programs stored as Java Archive (JAR) files to
+native binaries.
 
 To use the `release` script, you must carry out the following steps:
 
@@ -120,3 +122,23 @@ of sync, and the native image build may not work.
 . Run `./release` in this directory.
 The script will build the native binary tools and install them at
 `native-fpp-[platform name]`.
+
+*Running the tracing agent:*
+Before running `native-image` on a JVM program, you must first run the
+JVM program with a tracing agent enabled and record the results,
+The directory `lib/src/main/resources/META-INF` stores the results of
+running the FPP unit tests with the tracing agent enabled.
+Occasionally when developing FPP, you may need to re-run the tracing
+agent to capture new runtime behavior.
+To do that, use the following procedure:
+
+. Run `./install-trace` to install JVM versions of the FPP tools with
+tracing enabled in the `bin` directory.
+
+. Run `./test` to use the installed tools to run the unit tests.
+This will run the tracing agent and update the trace files.
+
+. Commit the updated trace files to the repository.
+
+Remember to run `./install` to install the standard version
+of the tools if you no longer want to run the tracing agent.

compiler/install

@@ -5,10 +5,22 @@
 # ----------------------------------------------------------------------
 # To pass flags to sbt, set the environment variable
 # FPP_SBT_FLAGS
+#
+# To override the java command and/or set java flags, set the
+# environment variable
+# FPP_INSTALL_JAVA
 # ----------------------------------------------------------------------
 
 scala_version="3.1.2"
 
+if test -n "$FPP_INSTALL_JAVA"
+then
+  java=$FPP_INSTALL_JAVA
+else
+  java=java
+fi
+echo "java command: $java"
+
 if test $# -gt 1
 then
   echo 'usage: install dest-dir' 1>&2
@@ -25,8 +37,6 @@ fi
 
 wd=`dirname $0`
 cd $wd
-top=`pwd`
-meta=$top/lib/src/main/resources/META-INF/native-image
 
 dir=`dirname $dest`
 dir=`cd $dir; pwd`
@@ -64,13 +74,11 @@ mkdir -p $dest
 
 echo "Installing tools at $dest"
 for tool in $tools
-# See https://www.graalvm.org/22.1/reference-manual/native-image/Agent/
-#java -agentlib:native-image-agent=config-merge-dir='$meta' -jar '$dest'/'$tool'.jar "$@"' > $dest/$tool
 do
   jar=`find tools/$tool -name "*$name*assembly*.jar" | grep "target/scala-$scala_version"`
   echo "  $jar"
   cp $jar $dest/$tool.jar
   echo '#!/bin/sh
-  java -jar "`dirname $0`/'$tool'.jar" "$@"' > $dest/$tool
+  '$java' -jar "`dirname $0`/'$tool'.jar" "$@"' > $dest/$tool
   chmod +x $dest/$tool
 done

compiler/install-trace

@@ -0,0 +1,19 @@
+#!/bin/sh -e
+
+# ----------------------------------------------------------------------
+# Install FPP tools configured to run the GraalVM tracing agent
+# See https://www.graalvm.org/22.1/reference-manual/native-image/Agent/
+# ----------------------------------------------------------------------
+
+if test -z "$GRAALVM_JAVA_HOME"
+then
+  echo "trace: environment variable GRAALVM_JAVA_HOME is not set" 1>&2
+  exit 1
+fi
+
+dir="`pwd`"
+merge_dir="$dir/lib/src/main/resources/META-INF/native-image"
+
+export FPP_INSTALL_JAVA="$GRAALVM_JAVA_HOME/bin/java -agentlib:native-image-agent=config-merge-dir=$merge_dir"
+
+$dir/install "$@"