Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,23 @@ Scaffold for creating double-clickable apps using Java

This project uses Apache Ant and JDK 25 to compile, bundle, and package a Java application into native installers (.dmg for macOS, .deb for Ubuntu, and .msi for Windows).

---
## Common Requirements (All Systems)
Before running the build, ensure the following are installed and configured:
- JDK 21 or 25: Must be installed. Although jpackage was introduced in JDK 14, JDK 21+ is recommended for modern macOS/Linux/Windows support.
- Apache Ant: Installed and available in your PATH.
- `JAVA_HOME`: This environment variable must point to your JDK installation directory.
- Check via: `ant -version` and `java -version`

---
## macOS Setup
To build the .dmg installer, your Mac needs the following:
- Xcode Command Line Tools: Required for various build utilities.
- Install via: `xcode-select --install`
- Icon Asset: A file named icon.icns must be in the project root.
- Note on Security: Since the app is not "Signed" with an Apple Developer Certificate, users may need to Right-Click > Open the app the first time to bypass the "Unidentified Developer" warning.

---
## Ubuntu / Debian Setup
To build the .deb package on Linux, jpackage requires external tools to create the Debian archive structure.

Expand All @@ -27,6 +32,8 @@ sudo apt install ant fakeroot dpkg-dev
- fakeroot: Allows the package to be built with correct file permissions without requiring root access.
- dpkg-dev: Provides the core utilities to create Debian packages.
- Icon Asset: A file named icon.png (512x512 recommended) must be in the project root.

---
## Windows Setup
To build the .msi installer on Windows, ensure the following:
- JDK 21 or 25: Must be installed with JAVA_HOME configured.
Expand All @@ -37,6 +44,8 @@ To build the .msi installer on Windows, ensure the following:
- After installation, verify WiX is in your PATH by running: `candle -?`
- Icon Asset: A file named icon.ico must be in the project root.
- Note on Security: Windows may show a SmartScreen warning for unsigned installers. Users will need to click "More info" > "Run anyway" to install the app.

---
## Project Directory Structure
Ensure your project looks like this for the build.xml to find all resources:

Expand All @@ -49,6 +58,8 @@ MyAppName/
├── icon.ico # Required for Windows MSI
└── build.xml # The Ant build script
```

---
## Usage Commands
Open a terminal in the project root and use the following targets:

Expand All @@ -59,6 +70,7 @@ Open a terminal in the project root and use the following targets:
| ant run | Compiles and launches the app immediately for testing. |
| ant clean | Deletes the build/ and dist/ folders to start fresh. |
| ant -p | Displays a help menu of all available targets. |

## Troubleshooting
<table>
<tr>
Expand All @@ -79,6 +91,8 @@ Open a terminal in the project root and use the following targets:
</tr>
</table>

---

## Automated Releases
This project uses GitHub Actions to automatically build and distribute native installers. The workflow is split into two phases: Build and Release.

Expand Down Expand Up @@ -113,3 +127,18 @@ git push origin v1.0.1
When ready to bump the version, remember to update the version number in **two** places to keep everything in sync:
- The Git Tag (the v1.0.1 above).
- The **app.version** property at the top of `build.xml`. This ensures that when the user installs the app, the OS sees the correct version number in the "About" or "Get Info" screens.

---
## Native Java App Website

https://metrocs.github.io/NativeJavaApp/

---
## References

### jpackage

- https://docs.oracle.com/en/java/javase/25/docs/specs/man/jpackage.html

### Alternatives
- **jDeploy:** https://www.jdeploy.com
Loading