Implements #318 - better Windows installer support (#331)

Author: kwart

.github/workflows/do-release.yml

@@ -15,9 +15,13 @@ env:
   GIT_AUTHOR_EMAIL: <>
   GIT_COMMITTER_NAME: Terminator the Kitty
   GIT_COMMITTER_EMAIL: <>
+
 jobs:
   do-release:
     runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.maven_release.outputs.TAG }}
+      version: ${{ steps.maven_release.outputs.VERSION }}
     steps:
     - name: Checkout
       uses: actions/checkout@v6
@@ -60,16 +64,13 @@ jobs:
         mvn -P release --batch-mode release:perform \
             -DstagingProgressTimeoutMinutes=30 -Dmaven.wagon.rto=7200000 \
             -Dmaven.wagon.httpconnectionManager.maxPerRoute=60 -Dmaven.wagon.httpconnectionManager.maxTotal=100
-        docker run --rm -v "$(pwd):/mnt" \
-          -u $(id -u):$(id -g) kwart/innosetup \
-          /mnt/distribution/windows/create-jsignpdf-installer.sh
         cd distribution/target
         ls -R
         mkdir "JSignPdf-$VERSION"
-        mv *.zip *.exe "$FULL_VERSION/"
+        mv *.zip "$FULL_VERSION/"
         cp generated-docs/JSignPdf.pdf "$FULL_VERSION/$FULL_VERSION.pdf"
         cp "../doc/release-notes/${BASE_VERSION}.md" "$FULL_VERSION/README.md"
-        
+
         echo "${{ secrets.SSH_PRIVATE_KEY }}" >> private_key
         chmod 600 private_key
         sftp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -i private_key kwart@frs.sourceforge.net:/home/frs/project/jsignpdf/stable <<EOF
@@ -78,6 +79,7 @@ jobs:
         EOF
         mv "$FULL_VERSION" upload
         echo "TAG=$TAG" >> $GITHUB_OUTPUT
+        echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
         echo "BASE_VERSION=$BASE_VERSION" >> $GITHUB_OUTPUT
       env:
         MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }}
@@ -92,3 +94,49 @@ jobs:
         tag:   ${{ steps.maven_release.outputs.TAG }}
         overwrite: true
         body_path: distribution/doc/release-notes/${{ steps.maven_release.outputs.BASE_VERSION }}.md
+
+    - name: Publish PDF guide for downstream jobs
+      uses: actions/upload-artifact@v4
+      with:
+        name: jsignpdf-pdf-guide
+        path: distribution/target/generated-docs/JSignPdf.pdf
+        if-no-files-found: error
+        retention-days: 1
+
+  windows-installers:
+    needs: do-release
+    runs-on: windows-latest
+    steps:
+    - name: Checkout release tag
+      uses: actions/checkout@v6
+      with:
+        ref: ${{ needs.do-release.outputs.tag }}
+
+    - name: Set up JDK 21
+      uses: actions/setup-java@v5
+      with:
+        java-version: 21
+        distribution: 'temurin'
+        cache: 'maven'
+
+    - name: Build jsignpdf and installcert jars
+      shell: bash
+      run: mvn -B -DskipTests -pl jsignpdf,installcert -am package
+
+    - name: Download PDF guide from the release job
+      uses: actions/download-artifact@v4
+      with:
+        name: jsignpdf-pdf-guide
+        path: distribution/target/pdf-guide
+
+    - name: Build Windows installers (EXE / MSI / ZIP)
+      shell: pwsh
+      run: ./distribution/windows/build-windows-installers.ps1 -Version ${{ needs.do-release.outputs.version }}
+
+    - name: Upload Windows installers to release
+      uses: svenstaro/upload-release-action@29e53e917877a24fad85510ded594ab3c9ca12de
+      with:
+        file: distribution/target/upload/*
+        file_glob: true
+        tag: ${{ needs.do-release.outputs.tag }}
+        overwrite: true

design-doc/3.0.0-jpackage-installer.md

@@ -0,0 +1,206 @@
+# Replace InnoSetup+launch4j+Ant with jpackage for the Windows installer
+
+## Context
+
+The old Windows installer was produced by a Docker image (`kwart/innosetup`) that
+ran Ant + Launch4j to wrap the shaded jar into `.exe` launchers, copied bundled
+JREs from `/opt/jre32` and `/opt/jre64`, and ran `iscc` (InnoSetup) under Wine to
+produce a single fat `.exe` installer that selected 32- or 64-bit at install
+time. This setup was brittle — it depended on a custom Docker image, Wine, Ant,
+Launch4j, and prebuilt JREs.
+
+It has been replaced with `jpackage`, running natively on a `windows-latest`
+GitHub Actions runner. Three artifact types (EXE, MSI, ZIP) are produced for
+x64 only. 32-bit Windows is dropped (Temurin no longer ships 32-bit JDKs),
+but the existing cross-arch no-JRE distribution zip (`jsignpdf-${VERSION}.zip`)
+is kept so that 32-bit users (and Linux/Mac users) can run JSignPdf with their
+own JRE.
+
+## Final artifact set per release
+
+Produced by the ubuntu Maven job:
+
+- `jsignpdf-${VERSION}.zip` — cross-arch, no JRE (existing assembly, unchanged)
+
+Produced by the windows-latest jpackage job:
+
+- `JSignPdf-${VERSION}-win-x64.exe` — WiX-based EXE installer with MPL-2.0 license page
+- `JSignPdf-${VERSION}-win-x64.msi` — WiX-based MSI installer with MPL-2.0 license page
+- `JSignPdf-${VERSION}-win-x64.zip` — zipped jpackage app-image (portable, bundled JRE)
+
+All four are uploaded to the same GitHub Release tag. The cross-arch zip also
+goes to SourceForge.
+
+## Source tree layout
+
+### `distribution/jpackage/` — configuration
+
+- **`common-jvm-options.txt`** — single source of truth for JVM module
+  exports/opens shared across all launchers. One option per line, `#` comments
+  supported. The heap settings (`-Xms1g`/`-Xmx1g`) were intentionally removed
+  to let the JVM use its defaults. Current contents:
+  ```
+  --add-exports=jdk.crypto.cryptoki/sun.security.pkcs11=ALL-UNNAMED
+  --add-exports=jdk.crypto.cryptoki/sun.security.pkcs11.wrapper=ALL-UNNAMED
+  --add-exports=java.base/sun.security.action=ALL-UNNAMED
+  --add-exports=java.base/sun.security.rsa=ALL-UNNAMED
+  --add-opens=java.base/sun.security.util=ALL-UNNAMED
+  ```
+
+- **`JSignPdfC.properties`** — console add-launcher; contains only
+  `win-console=true`. All other settings (java-options, icon) are inherited
+  from the main JSignPdf launcher.
+
+Two additional add-launcher files are **generated at build time** by the
+PowerShell script into `distribution/target/jpackage-generated/`:
+
+- **`JSignPdf-swing.properties`** — Swing GUI. Generated because it must
+  override `java-options` to add `-Djsignpdf.swing=true` alongside the common
+  options (jpackage replaces rather than merges java-options). Generating it
+  from `common-jvm-options.txt` avoids duplicating the option list.
+
+- **`InstallCert.properties`** — console launcher for `InstallCert.jar`.
+  Generated so it can carry an absolute path to `Certificate.ico` (jpackage
+  resolves add-launcher icon paths against the working directory, which varies
+  between CI and local builds).
+
+The legacy `-Djsignpdf.home="%EXEDIR%"` flag was intentionally dropped. jpackage
+sets the working directory itself; if a regression surfaces during testing, it
+can be re-added via `--java-options "-Djsignpdf.home=$APPDIR"`.
+
+### `distribution/windows/build-windows-installers.ps1` — build script
+
+PowerShell script invoked by the workflow. Lives in the repo so it can be
+tested locally on a Windows box. Key responsibilities:
+
+1. **Version sanitization**: `$Version` is split into a jpackage-compatible
+   numeric `$appVersion` (strips `-RC1`, `-SNAPSHOT`, `.Final` etc., keeps up
+   to three numeric components). `$Version` is preserved for release-aligned
+   filenames; `$appVersion` is what jpackage receives via `--app-version`.
+
+2. **WiX fallback**: checks for `light.exe` on PATH; if absent, installs WiX
+   3.14 via `choco install wixtoolset` and adds its bin directory to the
+   session PATH.
+
+3. **Artifact cleanup**: removes `JSignPdf-*-win-x64.*` from `upload/` so
+   repeat local runs don't accumulate stale artifacts.
+
+4. **Jar staging**: copies the shaded `JSignPdf.jar` and `InstallCert.jar`
+   from module target directories.
+
+5. **PDF guide**: if `distribution/target/pdf-guide/*.pdf` exists (downloaded
+   from the ubuntu job's workflow artifact in CI), stages it into
+   `jpackage-app-content/docs/JSignPdf.pdf` and passes it as
+   `--app-content` to jpackage. The PDF ends up at `<install>/app/docs/`
+   in the installed tree. If absent (local builds), logs a warning and
+   proceeds without it.
+
+6. **Common JVM options**: reads `common-jvm-options.txt` and expands into
+   `--java-options` pairs for the main launcher. Also generates the Swing
+   and InstallCert add-launcher `.properties` files from the same source.
+
+7. **App-image build**: `jpackage --type app-image` with four launchers
+   (JSignPdf as main, plus JSignPdf-swing, JSignPdfC, InstallCert as
+   add-launchers). Icons: `icons.ico` for the main + console + swing
+   launchers, `Certificate.ico` for InstallCert.
+
+8. **Zip**: `Compress-Archive` of the app-image directory (includes the
+   `JSignPdf/` parent folder at the zip root).
+
+9. **EXE + MSI**: `jpackage --type exe` and `--type msi` from the app-image,
+   with `--license-file` (MPL-2.0), `--win-menu`, `--win-shortcut`,
+   `--win-dir-chooser`, and a stable `--win-upgrade-uuid`.
+
+10. **Rename + move**: jpackage output files use `$appVersion` in the
+    filename; the script renames them to `$Version` for release-tag alignment
+    and moves them into `distribution/target/upload/`.
+
+### `.github/workflows/do-release.yml` — release workflow
+
+Two jobs:
+
+- **`do-release`** (ubuntu-latest, JDK 11):
+  - Verifies per-version release notes file exists
+    (`distribution/doc/release-notes/${BASE_VERSION}.md`).
+  - Maven Central deploy via `release:prepare` / `release:perform`.
+  - Organizes artifacts and uploads to SourceForge + GitHub Release (with
+    `body_path` pointing at the release notes markdown).
+  - Publishes `distribution/target/generated-docs/JSignPdf.pdf` as a workflow
+    artifact (`jsignpdf-pdf-guide`) for the windows job.
+  - Outputs: `tag`, `version`, `base_version`.
+
+- **`windows-installers`** (windows-latest, JDK 21, `needs: do-release`):
+  - Checks out the release tag.
+  - Builds `jsignpdf` and `installcert` jars
+    (`mvn -B -DskipTests -pl jsignpdf,installcert -am package`).
+  - Downloads the PDF guide workflow artifact into
+    `distribution/target/pdf-guide/`.
+  - Runs `build-windows-installers.ps1 -Version <version>`.
+  - Uploads the EXE/MSI/ZIP to the same GitHub Release.
+
+Only `jsignpdf` and `installcert` modules are built in the windows job —
+the distribution module (with asciidoctor) is skipped to keep the job fast.
+The PDF guide is passed via workflow artifact instead.
+
+## Deleted files
+
+- `distribution/windows/JSignPdf.iss`
+- `distribution/windows/ant-build-create-launchers.xml`
+- `distribution/windows/create-jsignpdf-installer.sh`
+- `distribution/windows/launch4j-template.l4j.ini`
+- `distribution/windows/JSignPdf-swing.l4j.ini`
+- `distribution/doc/icon/splash08.bmp`
+- `distribution/doc/icon/splash08.xcf`
+- `distribution/doc/icon/splash_1.0.0.bmp`
+- `distribution/doc/icon/splash_1.0.0.xcf`
+
+## Important constraints
+
+- **`--win-upgrade-uuid` is fixed** (`7b3d6e4c-9a51-4a8b-9b1c-7e8c1a4d2f10`).
+  It must remain stable across releases so MSI upgrades work correctly (single
+  entry in Add/Remove Programs). Do NOT regenerate it.
+
+- **WiX 3.x required**. jpackage on JDK 17+ uses WiX 3 for both EXE and MSI.
+  GitHub `windows-latest` runners ship WiX 3 preinstalled. The script falls
+  back to `choco install wixtoolset --version=3.14.0` if `light.exe` is
+  missing.
+
+- **Version format**: jpackage `--app-version` accepts only
+  `MAJOR[.MINOR[.MICRO]]` (numeric). The script strips non-numeric suffixes
+  automatically, but future releases should use clean version numbers.
+
+## Verification
+
+1. **Local Windows smoke test** (JDK 21 + WiX 3):
+   ```
+   mvn -B -DskipTests -pl jsignpdf,installcert -am package
+   pwsh ./distribution/windows/build-windows-installers.ps1 -Version 3.0.0
+   ```
+   Confirm `distribution/target/upload/` contains
+   `JSignPdf-3.0.0-win-x64.{exe,msi,zip}`.
+
+2. **Install + launch test**:
+   - EXE installer: verify MPL-2.0 license page, Start menu entries, JSignPdf
+     launches.
+   - MSI installer: same.
+   - Portable zip: extract, run `JSignPdf.exe`, `JSignPdf-swing.exe`,
+     `JSignPdfC.exe --help`, `InstallCert.exe`.
+   - Verify InstallCert has the Certificate.ico icon.
+   - Sign a sample PDF from both JavaFX and Swing UIs.
+
+3. **Upgrade test**: install version N via MSI, then install N+ε over the top,
+   confirm a single entry in Add/Remove Programs.
+
+4. **PDF guide**: after installing, confirm `<install>/app/docs/JSignPdf.pdf`
+   exists (when built in CI with the workflow artifact).
+
+5. **Artifact set on GitHub Release**: confirm the release page shows
+   `jsignpdf-${VERSION}.zip` (cross-arch) plus the three Windows artifacts,
+   with release notes as the body.
+
+## Out of scope
+
+- 32-bit Windows installers.
+- macOS / Linux installer packaging.
+- Code-signing the EXE/MSI (no certificate set up; can be added later via
+  `signtool sign` in the workflow).

distribution/doc/icon/splash08.bmp

@@ -0,0 +1 @@
+win-console=true

distribution/doc/icon/splash08.xcf

@@ -0,0 +1,15 @@
+# Shared JVM options for every JSignPdf launcher.
+#
+# Single source of truth consumed by distribution/windows/build-windows-installers.ps1:
+#   * Main launcher (JSignPdf) — passed as --java-options on the jpackage command line.
+#   * JSignPdfC / InstallCert — inherited automatically from the main launcher
+#     because their add-launcher .properties files leave java-options unset.
+#   * JSignPdf-swing — the build script generates the add-launcher .properties file
+#     at build time, concatenating these options with the Swing-specific ones.
+#
+# Format: one option per line; blank lines and lines starting with '#' are ignored.
+--add-exports=jdk.crypto.cryptoki/sun.security.pkcs11=ALL-UNNAMED
+--add-exports=jdk.crypto.cryptoki/sun.security.pkcs11.wrapper=ALL-UNNAMED
+--add-exports=java.base/sun.security.action=ALL-UNNAMED
+--add-exports=java.base/sun.security.rsa=ALL-UNNAMED
+--add-opens=java.base/sun.security.util=ALL-UNNAMED

distribution/doc/icon/splash_1.0.0.bmp

@@ -50,5 +50,9 @@
                 <include>*.pdf</include>
             </includes>
         </fileSet>
+        <fileSet>
+            <directory>demo</directory>
+            <outputDirectory>/demo/</outputDirectory>
+        </fileSet>
     </fileSets>
 </assembly>