Merge pull request #501 from bci-oss/494-make-native-binaries-easier-…

…to-download-via-documentation

SAMM CLI: Make native binaries easier to download via documentation

.github/workflows/release-workflow.yml

@@ -94,6 +94,8 @@ jobs:
           mvn clean install -DskipTests -Dmaven.javadoc.skip=true
           mvn versions:set -DnewVersion=${{ github.event.inputs.release_version }}
           mvn versions:commit
+          
+          release_version=${{ github.event.inputs.release_version }}
 
           # Actual build of core SDK
           mvn -B -pl '!org.eclipse.esmf:samm-cli' clean deploy -Dmaven.wagon.httpconnectionManager.ttlSeconds=60 -DaltDeploymentRepository=local::default::file://nexus-staging -Psign
@@ -106,9 +108,9 @@ jobs:
           # Create .tar.gz of samm-cli
           pushd tools/samm-cli/target
           chmod a+x samm
-          tar cfvz samm-cli-linux.tar.gz samm
+          tar cfvz samm-cli-${{ github.event.inputs.release_version }}-linux-x86_64.tar.gz samm
           popd
-          mv tools/samm-cli/target/samm-cli-linux.tar.gz .
+          mv tools/samm-cli/target/samm-cli-${{ github.event.inputs.release_version }}-linux-x86_64.tar.gz .
           mv tools/samm-cli/target/samm-cli-*.jar .
         env:
           PGP_KEY_PASSWORD: ${{ secrets.PGP_KEY_PASSWORD }}
@@ -131,8 +133,10 @@ jobs:
           name: linux-artifacts
           path: |
             nexus-staging/
-            samm-cli-linux.tar.gz
-            samm-cli-*.jar
+            samm-cli-${{ github.event.inputs.release_version }}-linux-x86_64.tar.gz
+            samm-cli-${{ github.event.inputs.release_version }}-javadoc.jar
+            samm-cli-${{ github.event.inputs.release_version }}-sources.jar
+            samm-cli-${{ github.event.inputs.release_version }}-tests.jar
 
   # The Windows build will build the Windows-specific samm-cli
   # and upload the binary to the build artifacts
@@ -242,7 +246,7 @@ jobs:
       - name: Prepare release
         run: |
           # Create Windows CLI zip
-          zip -9 -r samm-cli-windows.zip samm.exe *.dll
+          zip -9 -r samm-cli-${{ github.event.inputs.release_version }}-windows-x86_64.zip samm.exe *.dll
 
       # Full release: Maven Central
       # The (apparently) only way to retrieve the staging profile id
@@ -302,8 +306,8 @@ jobs:
           draft: false
           prerelease: false
           files: |
-            samm-cli-windows.zip
-            samm-cli-linux.tar.gz
+            samm-cli-${{ github.event.inputs.release_version }}-windows-x86_64.zip
+            samm-cli-${{ github.event.inputs.release_version }}-linux-x86_64.tar.gz
             samm-cli-*.jar
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN  }}
@@ -367,8 +371,8 @@ jobs:
           draft: false
           prerelease: true
           files: |
-            samm-cli-windows.zip
-            samm-cli-linux.tar.gz
+            samm-cli-${{ github.event.inputs.release_version }}-windows-x86_64.zip
+            samm-cli-${{ github.event.inputs.release_version }}-linux-x86_64.tar.gz
             samm-cli-*.jar
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN  }}

documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

@@ -5,9 +5,15 @@
 
 The SAMM CLI is a command line tool for the validation of Aspect Models and the generation of artifacts, such as documentation or code, from Aspect Models.
 
-TIP: Download latest version: icon:download[] https://github.com/eclipse-esmf/esmf-sdk/releases/download/v{esmf-sdk-version}/samm-cli-{esmf-sdk-version}.jar[samm-cli-{esmf-sdk-version}.jar]
+The SAMM CLI is available as a native executable for multiple platforms and as an executable jar:
 
-NOTE: For technical reasons, Java 17 or newer is required to successfully run the tool.
+[TIP]
+.Downloading samm-cli
+====
+* Download executable for Windows (latest): https://github.com/eclipse-esmf/esmf-sdk/releases/download/v{esmf-sdk-version}/samm-cli-{esmf-sdk-version}-windows-x86_64.zip[samm-cli-{esmf-sdk-version}-windows-x86_64.zip]
+* Download exectuable for Linux (latest): https://github.com/eclipse-esmf/esmf-sdk/releases/download/v{esmf-sdk-version}/samm-cli-{esmf-sdk-version}-linux-x86_64.tar.gz[samm-cli-{esmf-sdk-version}-linux-x86_64.tar.gz]
+* Download executable jar for other platforms and architectures (latest): https://github.com/eclipse-esmf/esmf-sdk/releases/download/v{esmf-sdk-version}/samm-cli-{esmf-sdk-version}.jar[samm-cli-{esmf-sdk-version}.jar]. Running this version requires Java 17.
+====
 
 [[samm-cli-getting-started]]
 == Running the SAMM CLI
@@ -26,7 +32,21 @@ alias samm='java -jar /location/to/samm-cli-{esmf-sdk-version}.jar'
 ----
 ====
 
-Successful execution of a command is signaled by returning 0. In case of logical or some other internal problem error code 1 is returned.
+*For the Windows native executable:*
+. *Download*: Download via above link or visit the repository of the Java SDK which contains the SAMM CLI at the Github https://github.com/eclipse-esmf/esmf-sdk/releases[releases page] and download executable file for Windows.
+. *Extract*: extract it to a location of your choice.
+. *Open Command Prompt*: Launch the Command Prompt and navigate to the directory (samm-cli-windows) containing our application.
+. *Input*: Make sure to read the below documentation and provide model files in the correct xref:models-directory-structure[directory structure].
+. *Run*: In the command prompt, execute the command `samm` to start the application. See the below table for details.
+
+*For the Linux native executable:*
+. *Download*: Download via above link or visit the repository of the Java SDK which contains the SAMM CLI at the Github https://github.com/eclipse-esmf/esmf-sdk/releases[releases page] and download executable file for Linux.
+. *Extract*: Unpack the archive to your preferred directory.
+. *Open Terminal*: Open the Terminal and navigate to the directory with the application.
+. *Input*: Make sure to read the below documentation and provide model files in the correct xref:models-directory-structure[directory structure].
+. *Execute*: Run the application using the command `./samm`.
+
+Successful execution of a command is signaled by returning 0. In case of a logical or other internal error the error code 1 is being returned.
 Missing or wrong command parameters result in error code 2 being returned.
 
 To get help for a certain subcommand, add 'help' before the subcommand name or add `--help` to the end, e.g., `samm help aspect`