{"id":13777742,"url":"https://github.com/wiverson/maven-jpackage-template","last_synced_at":"2025-04-06T13:10:40.899Z","repository":{"id":37206937,"uuid":"307010251","full_name":"wiverson/maven-jpackage-template","owner":"wiverson","description":"Sample project illustrating building nice, small cross-platform JavaFX or Swing desktop apps with native installers while still using the standard Maven dependency system.","archived":false,"fork":false,"pushed_at":"2022-10-11T17:46:09.000Z","size":146219,"stargazers_count":329,"open_issues_count":10,"forks_count":51,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-05-02T02:19:42.922Z","etag":null,"topics":["cross-platform-javafx","java","javafx","javafx-application","javafx-desktop-apps","jpackage","macos","maven","native-installers"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wiverson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"wiverson"}},"created_at":"2020-10-25T02:33:34.000Z","updated_at":"2024-04-29T01:04:18.000Z","dependencies_parsed_at":"2023-01-19T10:40:22.719Z","dependency_job_id":null,"html_url":"https://github.com/wiverson/maven-jpackage-template","commit_stats":null,"previous_names":[],"tags_count":6,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiverson%2Fmaven-jpackage-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiverson%2Fmaven-jpackage-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiverson%2Fmaven-jpackage-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiverson%2Fmaven-jpackage-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wiverson","download_url":"https://codeload.github.com/wiverson/maven-jpackage-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485287,"owners_count":20946398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform-javafx","java","javafx","javafx-application","javafx-desktop-apps","jpackage","macos","maven","native-installers"],"created_at":"2024-08-03T18:00:48.051Z","updated_at":"2025-04-06T13:10:40.873Z","avatar_url":"https://github.com/wiverson.png","language":"Java","funding_links":["https://github.com/sponsors/wiverson"],"categories":["Community","Libraries, Tools and Projects"],"sub_categories":["Tools"],"readme":"# Java + Maven + GitHub Actions = Native Desktop Apps\n\n[JavaFX](https://openjfx.io) or Swing + [jpackage](https://docs.oracle.com/en/java/javase/18/docs/specs/man/jpackage.html) +\n  [Maven](http://maven.apache.org) template project for generating native desktop applications.\n\n# Goals\n\n1. Build nice, small cross-platform JavaFX or Swing desktop apps with native installers!\n2. Just use Maven - no shell scripts required!\n3. Use standard Maven dependency system to manage dependencies.\n4. Generate [MacOS (.dmg), Windows (.msi) and Unix (e.g. deb/rpm)](https://github.com/wiverson/maven-jpackage-template/releases)\ninstallers/packages in the cloud\nwith [GitHub Actions](https://github.com/wiverson/maven-jpackage-template/tree/main/.github/workflows).\n\nOut of the box, this template generates \"Hello World\" installers - 30-40mb .dmg, .msi and .deb files. Check out the\nexample builds in\n[releases](https://github.com/wiverson/maven-jpackage-template/releases).\n\nIf you are on MacOS, you notice the MacOS builds are not signed. Current versions of MacOS will report\ninstallers downloaded via browsers as damaged/unopenable. You can [clear this flag via the command-line](docs/apple-sign-notarize.md). As this is not a reasonable solution for end users, a GitHub Action is included to notarize, sign, and staple \nMacOS installers, but the secrets aren't set up for this repository by default. You will need an Apple Developer account\nto get this working. [More information on MacOS signing](docs/apple-sign-notarize.md).\n\n# Overview\n\nThis template uses a [Maven plugin](https://github.com/wiverson/jtoolprovider-plugin) to generate a custom JVM and\ninstaller package for a JavaFX application. It can easily be adapted to work with Swing instead.\n\nCheck out the [announcements and recent updates](https://github.com/wiverson/maven-jpackage-template/discussions/categories/announcements).\n\n## Requirements\n\n- [Java 18](https://bell-sw.com/pages/downloads/#/java-18-current).\n    - If you are using JavaFX, use an SDK that has JavaFX bundled:\n      - [Liberica with JavaFX](https://bell-sw.com/pages/downloads/#/java-18-current)\n      - [Azul Zulu with JavaFX](https://www.azul.com/downloads/?version=java-18-sts\u0026package=jdk-fx)\n    - If you are using Swing, pretty much any Java 17 or 18 JDK will work.\n- [Maven](https://maven.apache.org/).\n- On MacOS XCode is required.\n- On Windows the free [WiX Toolset](https://wixtoolset.org/) is required.\n\n## Installation\n\nIf you are on Windows, you will need to install Java, Maven, and Wix manually.\n\nIf you are on MacOS or Linux, you can use [SDKMAN!](https://sdkman.io/) to simplify installing Java and Maven. Once \nSDKMAN! is installed, you can run the following to install Liberica or Azul Zulu and Maven.\n\n```bash\nsdk install java 18.0.2.fx-librca\n# or\nsdk install java 18.0.2.fx-zulu\nsdk current java\nsdk install maven\n```\n\n## Installation Verification\n\n1. Verify that Java is installed by opening a fresh Terminal/Command Prompt and enter `java --version`. As of this \nwriting, the Java version should be 18.0.2 or later.\n2. Verify that Maven is installed with `mvn --version`. Maven should be version 3.8.6 or later.\n3. Install platform-specific tools.\n   1. **MacOS only:** Verify that XCode is installed \u0026 license accepted by a) launching it and b)\n      running `sudo xcodebuild -license`.\n   2. **Windows only:** Install [Wix 3 binaries](https://github.com/wixtoolset/wix3/releases/).\n4. Clone/download this project.\n5. Run `mvn clean install` from the root of the project to generate the `target\\TestApp.dmg` or `target\\TestApp.msi`\n   installers.\n    - The generated installer will include a version number in the file name.\n    - For reference, here is a complete run log for [a successful run](docs/sample-run.md).\n\nBecause these builds use stripped down JVM images, the\n[generated installers are in the 30-40mb range](https://github.com/wiverson/maven-jpackage-template/releases).\n\nOn MacOS you should [add signing to avoid error messages](https://github.com/wiverson/maven-jpackage-template/issues/49)\nrelated to the security system(s).\n\nTo [re]generate an installer, run...\n\n`mvn clean install`\n\nTo do everything up until the actual installer generation (including generating the custom JVM)...\n\n`mvn clean package`\n\nTo generate reports, include to check if you are using the current version[s] of your dependencies, run...\n\n`mvn site`\n\n...and open target/site/index.html to see the generated reports.\n\n## Key Features\n\nHere are few cool things in this template:\n\n- Only uses Java and Maven. No shell scripts required.\n- Includes sample [GitHub Actions](https://github.com/wiverson/maven-jpackage-template/tree/main/.github/workflows) to\n  build MacOS, Windows and Linux installers. These GitHub Actions are configured to use the Liberica JDK 18 with \nJavaFX to simplify the build process. If you prefer to use Azul Zulu, modify the distribution name to `distribution: 'zulu'` as described on the [Usage description of setup-java](https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#Zulu) \n- Demonstrates setting the application icon\n- Builds a .dmg on MacOS, .msi on Windows, and .deb on Linux, but can be easily tweaked to generate other jpackage\nsupported installers (e.g. .pkg)\n- Includes a JavaFX demo to simplify getting started.\n    - Just delete the JavaFX stuff if you are using Swing\n- Template includes several examples of JavaFX / native desktop integration\n    - Drag \u0026 drop with Finder / Explorer\n    - Change the Dock icon dynamically on MacOS\n    - Menu on the top for MacOS, in the window itself on Windows\n    - Request user attention (bouncing dock icon) on MacOS\n    - Removing the code and the demonstration dependencies gets a \"Hello World\" build size closer to 30mb than\n      40mb.\n- Java + Java modules are used to build a trimmed\n  JVM ([a few thoughts on Java modules](https://changenode.com/articles/fomo-java-modules))\n- The user application uses ordinary Maven dependencies and classpath to run the application\n    - Nice illustration of how to use jlink to build a slim JVM, point jpackage at that JVM and still use the ordinary\n      Maven managed classpath for the application\n\nOnce you get started, you might find these lists of tutorials, tools, libraries for\n[JavaFX](https://gist.github.com/wiverson/6c7f49819016cece906f0e8cea195ea2)\nand general [Java desktop integration](https://gist.github.com/wiverson/e9dfd73ca9a9a222b2d0a3d68ae3f129) helpful.\n\n### Version Numbering\n\nUsually you want a \"marketing version\" of an app as released to customers, and a \"developer version\" for use in internal\ntesting. For example, to the end user it's just \"Windows 11\" but there are countless build numbers for all the\ndifferent versions of Windows 11.\n\nThe end-user value is set in the pom.xml as `app.version`. This value is updated to use a GitHub environment variable\nwhen the installers are run on GitHub.\n\nIf you look in the `src/main/resources` you will see a version.txt file. This file has information in it that will\nbe useful for creating a developer build UI. You might want to convert this to a properties file or a JSON file and\ndisplay the information in your about UI.\n\nMost projects will want to set up a coherent versioning strategy to manage both the user visible and development\nbuild version numbers. This is usually project specific.\n\n### Does this work with Apple Silicon aka M1/M2?\n\nYes, although as of this writing I don't believe there are GitHub Action runners that support M1. But building locally\non my M1/M2 systems works great and generates native Apple Silicon builds.\n\n### Does this support macOS signing, notarization, and stapling?\n\nYes, there is a GitHub Action and a Maven profile to assist with setting all of this up\nfor macOS applications.\n\nFor more information, see\nthe [documentation on getting MacOS signing/notarization/stapling](/docs/apple-sign-notarize.md) set\nup. \n\nTo get this working, you will need to:\n\n1. You need to sign up for an Apple Developer account.\n2. Add [four GitHub Secrets based on information from Apple]((/docs/apple-sign-notarize.md)).\n3. Update the [build all installer GitHub Action yaml](https://github.com/wiverson/maven-jpackage-template/blob/6d4ef8a80a562f2d49ec41204927d07aa8990d25/.github/workflows/maven-build-all-installer.yml#L14) \n4. Update the [pom.xml](https://github.com/wiverson/maven-jpackage-template/blob/6d4ef8a80a562f2d49ec41204927d07aa8990d25/pom.xml#L331).\n\n### What about Linux?\n\nThe JavaFX builds include several other architectures, including aarch64 and arm32. In theory,\nyou should be able to add those just like the other builds. Haven't tested it though, as I only use Linux for\nserver-side stuff. Feel free to post in\nthe [discussion](https://github.com/wiverson/maven-jpackage-template/discussions) section and\nalso check the [Q\u0026A](docs/qna.md) if you are using Linux.\n\n### Can I Use this with Swing instead of JavaFX?\n\ntl;dr absolutely.\n\nJust delete the JavaFX stuff, including the JavaFX modules declarations in `pom.xml` and add a Swing main class instead.\nIf you are reasonably familiar with Maven this shouldn't be very hard to do.\n\nI *highly* recommend the [FlatLaf](https://www.formdev.com/flatlaf/) as a must for working with Swing in 2022. That\nlook-and-feel plus designers such as\nthe [IntelliJ GUI Designer](https://www.jetbrains.com/help/idea/gui-designer-basics.html)\nor [JFormDesigner](https://www.formdev.com/jformdesigner/) can work very well, arguably with an easier learning curve\nthan JavaFX.\n\nSuggested changes to the pom.xml for Swing:\n\n1. Remove the javafx modules from the jvm.modules property\n2. Remove the javafx.version property.\n3. Remove the three org.openjfx dependencies\n4. Remove the configuration/excludeGroupIds section from the maven-dependency-plugin\n5. Remove javafx-maven-plugin from the plugins list\n6. Remove the modulePath delcaration from the jtoolprovider-plugin execution/configuration\n\n# Debugging\n\n1. If the built app fails to run, make sure the JavaFX app runs as expected first by using the `mvn javafx:run` command.\n   This will run the app in development mode locally, and you should see standard System.out debug lines appear in your\n   console.\n    - Many flavors of Linux fail to run here for a variety of reasons. Head over to\n      the [discussions](https://github.com/wiverson/maven-jpackage-template/discussions) or perhaps consider your\n      [consulting budget](https://changenode.com) or\n      a [JavaFX support contract from Gluon](https://gluonhq.com/services/javafx-support/).\n2. Check the Maven build logs (of course).\n3. By default, the app will generate debug*****.log files containing the output from System.out. You can look at the\n   main method of `BaseApplication.java` to see how this is done. For a production app, you would want to place these\n   logs in the correct OS specific location. On a Unix machine you can `tail -f` the log normally.\n\n# Help\n\nProblems? Make sure everything is installed and working right!\n\n- Compiler not recognizing the --release option? Probably on an old JDK.\n- Can't find jdeps or jpackage? Probably on an old JDK.\n- Unrecognized option: --add-modules jdk.incubator.jpackage\n    - Could be a left-over MAVEN_OPTS setting when you switched from Java 15 to Java 16/17\n    - If you are still on Java 15, you may not have\n      [MAVEN_OPTS set correctly](https://github.com/wiverson/maven-jpackage-template/issues/2).\n- No certificate found matching [Developer ID Application: Company Name, Inc. (BXPXTXC35S)] using keychain [] -\u003e Update the Developer ID info at the top of your build all installers and also in the macOS signing profile in the pom.xml.\n\n- Getting errors about not being able to find JavaFX classes in your IDE? Make \nsure your IDE is pointing to the right JDK. For example, MacOS IntelliJ -\u003e select \nFile, Project Structure and make sure you have Liberica with JavaFX selected.\n\nIf you need consulting support, feel free to reach out at [ChangeNode.com](https://changenode.com/). I've helped several\ncompanies with Swing and JavaFX clean up/modernize their old apps to include updated look \u0026 feels, add MacOS \nsign/staple/notarization, or even in a few cases helped port the app to Spring Boot.\n\n# Q\u0026A\n\nIf you are using the template, browsing the [Q\u0026A](docs/qna.md) is highly recommended.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiverson%2Fmaven-jpackage-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiverson%2Fmaven-jpackage-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiverson%2Fmaven-jpackage-template/lists"}