From 89812f3e3580f66fdecbf7332df5555b8a65caf9 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Sun, 18 Oct 2026 13:14:12 +0200 Subject: [PATCH] Offer running OFT via JBang Adds a JBang catalog so `jbang oft@itsallcode/openfasttrace` runs the latest release from Maven Central, and documents JBang as an installation alternative in the README and the per-OS installation guides. Co-Authored-By: Claude Opus 5.5 --- README.md | 12 +++++++++++- doc/changes/changes_4.11.0.md | 1 + doc/user_guide/installation/linux.md | 19 +++++++++++++++++++ doc/user_guide/installation/macos.md | 21 ++++++++++++++++++++- doc/user_guide/installation/windows.md | 21 ++++++++++++++++++++- jbang-catalog.json | 8 ++++++++ 6 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 jbang-catalog.json diff --git a/README.md b/README.md index 7ad57a2d..c3e1d04a 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Note that only the latest version of OFT is actively supported. ### Installation -You can get OFT via our [Debian APT repository](https://github.com/itsallcode/itsallcode-apt-repository), through [Homebrew](https://formulae.brew.sh/formula/openfasttrace), as [Maven plugin](https://central.sonatype.com/artifact/org.itsallcode/openfasttrace-maven-plugin) or [Gradle plugin](https://plugins.gradle.org/plugin/org.itsallcode.openfasttrace). Or you can get the [jar archive](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#JAR%20Manifest) via [releases on GitHub](https://github.com/itsallcode/openfasttrace/releases). +You can get OFT via our [Debian APT repository](https://github.com/itsallcode/itsallcode-apt-repository), through [Homebrew](https://formulae.brew.sh/formula/openfasttrace), via [JBang](https://www.jbang.dev/), as [Maven plugin](https://central.sonatype.com/artifact/org.itsallcode/openfasttrace-maven-plugin) or [Gradle plugin](https://plugins.gradle.org/plugin/org.itsallcode.openfasttrace). Or you can get the [jar archive](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#JAR%20Manifest) via [releases on GitHub](https://github.com/itsallcode/openfasttrace/releases). Check the chapter about [Installation](https://openfasttrace.itsallcode.org/user_guide/installation/installation.html) in the user guide for details. @@ -102,6 +102,16 @@ If you want to run OFT automatically as part of a continuous build, we recommend For more details about how to run OFT please consult the [user guide](https://openfasttrace.itsallcode.org/user_guide/user_guide.html). +### Run via JBang + +With [JBang](https://www.jbang.dev/) installed (`curl -Ls https://sh.jbang.dev | bash -s - app setup`, see [other installation options](https://www.jbang.dev/documentation/jbang/latest/installation.html)), you can run the latest OFT release without downloading it manually: + +```sh +jbang oft@itsallcode/openfasttrace trace /path/to/directory/being/traced +``` + +`jbang app install oft@itsallcode/openfasttrace` installs it as `oft` command. + ### Download and Execute in Continuous Integration If you want to run OFT in a CI build, you can use the OFT wrapper script [oftw.sh](product/oftw.sh). The script only requires Java 17 and Maven and downloads the OFT JAR from Maven Central if it is not yet available in the local Maven repository `$HOME/.m2/repository`. diff --git a/doc/changes/changes_4.11.0.md b/doc/changes/changes_4.11.0.md index 36bc0b7f..e82f9c40 100644 --- a/doc/changes/changes_4.11.0.md +++ b/doc/changes/changes_4.11.0.md @@ -16,6 +16,7 @@ The user guide documentation now has automatic lateral navigation. * #610: Allow adding plugins via configuration using `Oft.builder().addPlugin(name, jars...)` * #612: Add support for Visual Basic in the source tag importer +* n/a: Run OFT via JBang using `jbang oft@itsallcode/openfasttrace` ## Bugfixes diff --git a/doc/user_guide/installation/linux.md b/doc/user_guide/installation/linux.md index dd9a19d7..f5a75237 100644 --- a/doc/user_guide/installation/linux.md +++ b/doc/user_guide/installation/linux.md @@ -29,6 +29,25 @@ If you use Homebrew on Linux, you can install OpenFastTrace directly: brew install openfasttrace ``` +### JBang + +[JBang](https://www.jbang.dev/) runs OpenFastTrace straight from Maven Central and downloads a suitable Java runtime if none is installed. + +1. Install JBang (see the [JBang installation guide](https://www.jbang.dev/documentation/jbang/latest/installation.html) for other options): + ```bash + curl -Ls https://sh.jbang.dev | bash -s - app setup + ``` +2. Install OpenFastTrace as `oft` command: + ```bash + jbang app install oft@itsallcode/openfasttrace + ``` +3. Run OFT: + ```bash + oft --help + ``` + +To run OFT once without installing it, use `jbang oft@itsallcode/openfasttrace --help`. + ### Manual Installation If you prefer a manual setup, you can use the executable JAR file directly. diff --git a/doc/user_guide/installation/macos.md b/doc/user_guide/installation/macos.md index c2c64ea8..ed4b6256 100644 --- a/doc/user_guide/installation/macos.md +++ b/doc/user_guide/installation/macos.md @@ -8,7 +8,7 @@ nav_order: 2 ## macOS Installation -OpenFastTrace can be installed on macOS using Homebrew or manually via a JAR file. +OpenFastTrace can be installed on macOS using Homebrew, JBang or manually via a JAR file. ### Homebrew @@ -18,6 +18,25 @@ If you use Homebrew, you can install OpenFastTrace directly: brew install openfasttrace ``` +### JBang + +[JBang](https://www.jbang.dev/) runs OpenFastTrace straight from Maven Central and downloads a suitable Java runtime if none is installed. + +1. Install JBang (see the [JBang installation guide](https://www.jbang.dev/documentation/jbang/latest/installation.html) for other options): + ```bash + curl -Ls https://sh.jbang.dev | bash -s - app setup + ``` +2. Install OpenFastTrace as `oft` command: + ```bash + jbang app install oft@itsallcode/openfasttrace + ``` +3. Run OFT: + ```bash + oft --help + ``` + +To run OFT once without installing it, use `jbang oft@itsallcode/openfasttrace --help`. + ### Manual Installation If you prefer a manual setup, you can use the executable JAR file directly. diff --git a/doc/user_guide/installation/windows.md b/doc/user_guide/installation/windows.md index 7363fa06..1f3f9e6b 100644 --- a/doc/user_guide/installation/windows.md +++ b/doc/user_guide/installation/windows.md @@ -8,7 +8,26 @@ nav_order: 3 ## Windows Installation -On Windows, OpenFastTrace is typically run manually via the JAR file. +On Windows, OpenFastTrace can be run via JBang or manually via the JAR file. + +### JBang + +[JBang](https://www.jbang.dev/) runs OpenFastTrace straight from Maven Central and downloads a suitable Java runtime if none is installed. + +1. Install JBang (see the [JBang installation guide](https://www.jbang.dev/documentation/jbang/latest/installation.html) for other options): + ```powershell + iex "& { $(iwr -useb https://ps.jbang.dev) } app setup" + ``` +2. Install OpenFastTrace as `oft` command: + ```powershell + jbang app install oft@itsallcode/openfasttrace + ``` +3. Run OFT: + ```powershell + oft --help + ``` + +To run OFT once without installing it, use `jbang oft@itsallcode/openfasttrace --help`. ### Manual Installation diff --git a/jbang-catalog.json b/jbang-catalog.json new file mode 100644 index 00000000..f633250b --- /dev/null +++ b/jbang-catalog.json @@ -0,0 +1,8 @@ +{ + "aliases": { + "oft": { + "script-ref": "org.itsallcode.openfasttrace:openfasttrace:RELEASE", + "description": "OpenFastTrace requirement tracing" + } + } +}