eclipse-uprotocol · sophokles73 · Aug 19, 2024 · Aug 15, 2024
diff --git a/.github/actions/run-oft/action.yaml b/.github/actions/run-oft/action.yaml
@@ -16,73 +16,85 @@
 
 name: "Run OpenFastTrace"
 description: |
-  Runs OpenFastTrace with the trace command on the local up-rust workspace.
+  Runs OpenFastTrace with the trace command on files in the local workspace.
 inputs:
   file-patterns:
     description: |
       A whitespace separated list of glob patterns which specify the files to include in the OFT trace run.
     default: "**/*.*"
     required: false
-  java-version:
-    description: |
-      The version of Java to use for running OpenFastTrace.
-    default: "21"
-    required: false
 outputs:
-  requirements-tracing-exit-code:
+  oft-exit-code:
     description: |
-      A flag indicating the outcome of running OpenFastTrace (0: success, 1: failure).
+      The exit code indicating the outcome of running OpenFastTrace (0: success, 1: failure).
       The report is created in any case, as long as OpenFastTrace could be run at all.
-    value: ${{ steps.run-oft.outputs.requirements-tracing-exit-code }}
-  requirements-tracing-report-url:
+    value: ${{ steps.run-oft.outputs.oft-exit-code }}
+  tracing-report-url:
     description: "The URL to the OpenFastTrace HTML report"
     value: ${{ steps.tracing-report-html.artifact-url }}
 
 runs:
   using: "composite"
   steps:
-    - name: Prepare Environment
-      shell: bash
+    - shell: bash
       run: |
-        echo "TRACING_REPORT_FILE_NAME=requirements-tracing-report.html" >> $GITHUB_ENV
-    - name: Set up JDK
-      uses: actions/setup-java@v4
-      with:
-        distribution: "temurin"
-        java-version: ${{ inputs.java-version }}
-    - name: Download OpenFastTrace JARs
-      shell: bash
+        # Prepare Environment
+        echo "TRACING_REPORT_FILE_NAME=oft-report.html" >> $GITHUB_ENV
+    - shell: bash
       env:
         OFT_REPO_BASE: "https://github.com/itsallcode"
         OFT_CORE_VERSION: "4.1.0"
         OFT_ASCIIDOC_PLUGIN_VERSION: "0.2.0"
+        LIB_DIR: ${{ github.workspace }}/lib
       run: |
-        mkdir "${{ github.workspace }}/lib"
-        curl -L -o "${{ github.workspace }}/lib/openfasttrace.jar" \
-          "${{ env.OFT_REPO_BASE }}/openfasttrace/releases/download/${{ env.OFT_CORE_VERSION }}/openfasttrace-${{ env.OFT_CORE_VERSION }}.jar"
-        curl -L -o "${{ github.workspace }}/lib/openfasttrace-asciidoc-plugin.jar" \
-          "${{ env.OFT_REPO_BASE }}/openfasttrace-asciidoc-plugin/releases/download/${{ env.OFT_ASCIIDOC_PLUGIN_VERSION }}/openfasttrace-asciidoc-plugin-${{ env.OFT_ASCIIDOC_PLUGIN_VERSION }}-with-dependencies.jar"
-    - name: Run OpenFastTrace
-      id: run-oft
+        # Download OpenFastTrace JARs
+        curl_opts="--silent --show-error --location --create-dirs --output-dir ${LIB_DIR} -O"
+        curl ${curl_opts} \
+          "${OFT_REPO_BASE}/openfasttrace/releases/download/${OFT_CORE_VERSION}/openfasttrace-${OFT_CORE_VERSION}.jar"
+        curl ${curl_opts} \
+          "${OFT_REPO_BASE}/openfasttrace-asciidoc-plugin/releases/download/${OFT_ASCIIDOC_PLUGIN_VERSION}/openfasttrace-asciidoc-plugin-${OFT_ASCIIDOC_PLUGIN_VERSION}-with-dependencies.jar"
+
+    - name: Determine Java executable
       shell: bash
       env:
+        CLASSPATH: ${{ github.workspace }}/lib/*
+      run: $GITHUB_ACTION_PATH/determine_java_executable.sh
+
+    - name: Set up JDK
+      if: ${{ env.JAVA_CMD == '' }}
+      uses: actions/setup-java@v4
+      with:
+        distribution: "temurin"
+        java-version: 22
+
+    - id: run-oft
+      shell: bash
+      env:
+        CLASSPATH: ${{ github.workspace }}/lib/*
         INPUT_FILE_PATTERNS: ${{ inputs.file-patterns }}
+        JAVA_CMD: ${{ env.JAVA_CMD || 'java' }}
       run: |
-        if java -cp "${{ github.workspace }}/lib/*" \
+        if [[ ! -x ${JAVA_CMD} ]]; then
+          echo "Cannot find Java command ${JAVA_CMD}"
+          exit 127
+        fi
+        # Run OpenFastTrace
+        if (${JAVA_CMD} -cp "${CLASSPATH}" \
           org.itsallcode.openfasttrace.core.cli.CliStarter trace -o html \
-          -f "${{ env.TRACING_REPORT_FILE_NAME }}" \
-          ${{ env.INPUT_FILE_PATTERNS }};
+          -f "${TRACING_REPORT_FILE_NAME}" \
+          ${INPUT_FILE_PATTERNS})
         then
-          echo "requirements-tracing-exit-code=0" >> $GITHUB_OUTPUT
-          echo "All requirements from uProtocol Specification are covered by crate." >> $GITHUB_STEP_SUMMARY
+          echo "oft-exit-code=0" >> $GITHUB_OUTPUT
+          echo "All specification items are covered." >> $GITHUB_STEP_SUMMARY
         else
-          echo "requirements-tracing-exit-code=1" >> $GITHUB_OUTPUT
-          echo "Some requirements from uProtocol Specification are not covered by crate. See attached report for details." >> $GITHUB_STEP_SUMMARY
+          echo "oft-exit-code=1" >> $GITHUB_OUTPUT
+          echo "Some specification items are not covered. See attached report for details." >> $GITHUB_STEP_SUMMARY
         fi
 
     - name: Upload tracing report (html)
       uses: actions/upload-artifact@v4
       id: tracing-report-html
+      if: ${{ steps.run-oft.outputs.oft-exit-code != '' }}
       with:
         name: tracing-report-html
         path: ${{ env.TRACING_REPORT_FILE_NAME }}
diff --git a/.github/actions/run-oft/determine_java_executable.sh b/.github/actions/run-oft/determine_java_executable.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# try to find most recent JDK that is (usually) available on ubuntu-latest runner
+if [[ -n ${JAVA_HOME_21_X64} && -d ${JAVA_HOME_21_X64}/bin ]]; then
+  java_home_bin=${JAVA_HOME_21_X64}/bin
+elif [[ -n ${JAVA_HOME_17_X64} && -d ${JAVA_HOME_17_X64}/bin ]]; then
+  java_home_bin=${JAVA_HOME_17_X64}/bin
+else
+  # fall back to whatever is on the path
+  javap_path=$(which javap)
+  java_home_bin=$(dirname "${javap_path}")
+fi
+
+javap_executable=${java_home_bin}/javap
+
+function get_class_file_format_version() {
+  class_name=$1
+  ${javap_executable} -verbose -cp "${CLASSPATH}" "${class_name}" | grep "major version" | cut -d " " -f5
+}
+
+# determine if the installed JRE is sufficient for running OFT
+if [[ -x ${javap_executable} ]]; then
+  installed_jre_class_file_format_version=$(get_class_file_format_version java.lang.String)
+  echo "Installed JRE supports class file format version ${installed_jre_class_file_format_version}"
+
+  oft_core_class_file_format_version=$(get_class_file_format_version org.itsallcode.openfasttrace.core.cli.CliStarter)
+  asciidoc_plugin_class_file_format_version=$(get_class_file_format_version org.itsallcode.openfasttrace.importer.asciidoc.AsciiDocImporter)
+
+  # determine the minimum class file format version needed for running OFT
+  if [[ ${oft_core_class_file_format_version} -ge ${asciidoc_plugin_class_file_format_version} ]]; then
+    minimum_class_file_format_version=${oft_core_class_file_format_version}
+  else
+    minimum_class_file_format_version=${asciidoc_plugin_class_file_format_version}
+  fi
+  echo "OpenFastTrace requires JRE supporting class file format version ${minimum_class_file_format_version}"
+
+  # check if the installed JRE is sufficient
+  if [[ ${installed_jre_class_file_format_version} -ge ${minimum_class_file_format_version} ]]; then
+    java_executable=${java_home_bin}/java
+    if [[ -x ${java_executable} ]]; then
+      echo "Using installed JRE (${java_executable}) for running OpenFastTrace"
+      echo "JAVA_CMD=${java_executable}" >> "$GITHUB_ENV"
+    else
+      echo "could not find java command (${java_executable})"
+    fi
+  else
+    echo "OpenFastTrace cannot be run with installed JRE."
+    echo "JRE only supports class file format <= ${installed_jre_class_file_format_version} but OFT requires class file format ${minimum_class_file_format_version}."
+  fi
+
+else
+  echo "OpenFastTrace requires a JRE to be installed"
+fi
diff --git a/.github/workflows/check-up-spec-compatibility.yaml b/.github/workflows/check-up-spec-compatibility.yaml
@@ -51,6 +51,8 @@ jobs:
       # a tracing report
       - name: Run OpenFastTrace
         uses: ./.github/actions/run-oft
+        with:
+          file-patterns: 'up-spec/*.adoc up-spec/*.md up-spec/basics up-spec/up-l2/api.adoc *.adoc *.md *.rs .github examples src tests tools'
 
       # now try to build and run the tests which may fail if incomaptible changes
       # have been introduced in up-spec

diff --git a/.github/workflows/requirements-tracing.yaml b/.github/workflows/requirements-tracing.yaml
@@ -11,8 +11,8 @@
 #  SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************/
 
-# Perform requirements tracing against the uProtocol Specification using OpenFastTrace (https://github.com/itsallcode/openfasttrace)
-# Upload tracing report for potential re-use in publication workflow, returns the corresponding download URL as an output on workflow_call
+# Performs requirements tracing using OpenFastTrace (https://github.com/itsallcode/openfasttrace)
+# Uploads tracing report, returns the corresponding download URL as an output
 
 name: Requirements tracing
 
@@ -25,18 +25,24 @@ on:
           If not specified, defaults to all files relevant for checking up-rust against the uProtocol Specification.
         type: string
     outputs:
-      tracing_report_url:
+      tracing-report-url:
         description: 'URL of the requirements tracing report'
-        value: ${{ jobs.tracing.outputs.requirements-tracing-report-url }}
+        value: ${{ jobs.tracing.outputs.tracing-report-url }}
   workflow_dispatch:
+    inputs:
+      oft-file-patterns:
+        description: |
+          A whitespace separated list of glob patterns which specify the files to include in the OFT trace run.
+          If not specified, defaults to all files relevant for checking up-rust against the uProtocol Specification.
+        type: string
   pull_request:
 
 jobs:
   tracing:
     name: Run OpenFastTrace
     runs-on: ubuntu-latest
     outputs:
-      requirements-tracing-report-url: ${{ steps.run-oft.outputs.requirements-tracing-report-url }}
+      tracing-report-url: ${{ steps.run-oft.outputs.tracing-report-url }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -46,8 +52,8 @@ jobs:
         id: run-oft
         uses: ./.github/actions/run-oft
         with:
-          file-patterns: ${{ inputs.oft-file-patterns || '*.md *.rs .github examples src tests tools up-spec/*.adoc up-spec/*.md up-spec/basics up-spec/up-l2/api.adoc' }}
+          file-patterns: ${{ inputs.oft-file-patterns || 'up-spec/*.adoc up-spec/*.md up-spec/basics up-spec/up-l2/api.adoc *.adoc *.md *.rs .github examples src tests tools' }}
 
       - name: "Determine exit code"
         run: |
-          exit ${{ steps.run-oft.outputs.requirements-tracing-exit-code }}
+          exit ${{ steps.run-oft.outputs.oft-exit-code }}