for main
for develop



for main
for develop

java-warp4j

Warp4J rewritten in Java — build platform-specific executables from Java JARs with minimal JREs.

---

Table of Contents

• Introduction
• Features
• Prerequisites
• Usage
  • Using the Compiled JAR
  • Using the Source Code
  • Command-Line Parameters
  • Offline Support
• Examples
  • Example 1: Create a Linux x64 executable
  • Example 2: Cross-compile for macOS and Windows
• Docker
  • Using Docker
  • Building the Docker Image
  • Running the Docker Container
  • Offline Usage with Docker
  • Prebuilt Docker Images
• Building the Project
• Contributing
• License
• Contact

---

Introduction

This project is a Java-based reimplementation of warp4j, which itself wraps warp — a powerful CLI tool for bundling Java apps into native-like executables.
In addition to the original projects, there are already improved forks with more features: warp4j and warp

Why a new implementation?

• The original projects haven't been maintained for years.

• The original warp project only supports x64 platforms. That means no Raspberry Pi or ARM builds.

• warp4j was a shell script, making it:

  • Incompatible with Windows
  • Hard to test and extend
  • Painful to debug or modularize

This version (java-warp4j) fixes all of that:

✅ Fully written in Java
✅ Easily testable and type-safe
✅ Runs on all systems that support Java
✅ Produces builds for any combination of platform and architecture
✅ Can build itself
✅ Offline Support

Tradeoffs

❌ Requires a working JDK to run the tool (unlike the shell-based original)
❌ Slightly larger in size due to embedded dependencies

Still, the added flexibility, stability, and cross-platform support make java-warp4j a practical alternative to the original tools.

Executable versions of java-warp4j are available under GitHub Releases.
These versions include the tool bundled with a minimal JRE, and can be used without Java being installed.

---

Features

• 💡 Java-based CLI tool for building native-like executables
• 🌐 Automatically fetches and caches the matching JDK (architecture + platform + version) from the Adoptium API when not already present
• 📦 Minimized JDK per target via jlink (only required modules included)
• 🧪 Testable & typed: fully unit-tested and type-safe (unlike shell scripts)
• 🔁 Self-hosted: the tool can package itself
• 🪟 🐧 🍏 Supports Linux, Windows, and macOS
• 🏗️ Generates .exe, .sh, .bat or .app bundles
• 🪄 Automatically extracts Spring Boot dependencies
• 🐳 Docker support for cross-compiling and CI pipelines
• 📦 Prebuilt Docker Images available
• 🧠 Gracefully skips targets when builds or downloads fail

---

Prerequisites

To use java-warp4j:

• Java 17 or higher
• Maven (if building from source)
• Docker (optional, for container-based builds)

---

Usage

Using the Compiled JAR

After building or downloading java-warp4j, run:

java -jar warp4j-1.1.1-jar-with-dependencies.jar \
  --jar my-app.jar \
  --output ./target \
  --optimize \
  --linux-x64 \
  --linux-aarch64 \
  --windows-x64 \
  --macos-x64 \
  --prefix myapp

Using the Source Code

If you want to build and run directly from source, see BUILD.md.

---

Command-Line Parameters

Usage: warp4j [-hsv] [--linux] [--linux-aarch64] [--linux-x64] [--macos]
              [--macos-aarch64] [--macos-x64] [--optimize] [--pull]
              [--spring-boot] [--windows] [--windows-aarch64] [--windows-x64]
              [--add-modules=<additionalModules>] [--arch=<architecture>]
              [-cp=<classPath>] [-j=<javaVersion>] --jar=<jarFilePath>
              [--jdk=<jdkPath>] [-o=<outputDirectoryPath>] [-p=<prefix>]
Turn JAR into a self-contained executable
      --add-modules=<additionalModules>
                             A list of additional java modules that should be
                              added to the optimized JDK. Separate each module
                              with commas and no spaces
      --arch=<architecture> Target architecture (x64 or aarch64) Default: both
      -cp, --class-path=<classPath>
                            Additional classpaths for jdeps seperated by comma
  -h, --help                Show this message and exit
  -j, --java-version=<javaVersion>
                            Override JDK/JRE version (default: 17)
      --jar=<jarFilePath>   JAR file to be converted
      --jdk=<jdkPath>       Path to JDK that contains the binaries jdep(.exe)
                              and jlink(.exe)
      --linux               Create binary for Linux
      --linux-aarch64       Create binary for Linux with aarch64 architecture
      --linux-x64           Create binary for Linux with x64 architecture
      --macos               Create binary for macOS
      --macos-aarch64       Create binary for macOS with aarch64 architecture
      --macos-x64           Create binary for macOS with x64 architecture
  -o, --output=<outputDirectoryPath>
                            Output directory (default: ./warped)
      --optimize            Use optimized JRE instead of JDK
  -p, --prefix=<prefix>     Prefix for extracted application folder
      --pull                Check if more recent JDK/JRE distro is available.
                              By default latest cached version that matches
  -s, --silent              Use javaw.exe instead of java.exe (Windows only)
      --spring-boot         Extract class-path from JAR to fetch BOOT-INF/lib/
                              modules
  -v, --verbose             Enable verbose logging
      --windows             Create binary for Windows
      --windows-aarch64     Create binary for Windows with aarch64 architecture
      --windows-x64         Create binary for Windows with x64 architecture

Offline Support

java-warp4j works fully offline as long as the required components are available locally:

• The appropriate warp-packer binary must exist at ~/.local/share/warp4j/warp/warp-packer (or the equivalent for the platform).

• For each target platform and architecture, a corresponding JDK must be pre-downloaded under:

~/.local/share/warp4j/jdk/<platform>/<architecture>/jdk-<version>+<build>

Example:

~/.local/share/warp4j/jdk/windows/x64/jdk-21.0.7+6

Prebuilt Docker Images

Prebuilt Docker images are published to GitHub Container Registry (GHCR) and follow a semantic versioning scheme:

• ghcr.io/kirbylink/java-warp4j:latest - always points to the newest stable version
• ghcr.io/kirbylink/java-warp4j:v1.2.3 - full release version
• ghcr.io/kirbylink/java-warp4j:v1.2 - latest patch of v1.2
• ghcr.io/kirbylink/java-warp4j:v1 - latest of major version 1

To use it directly in Docker:

docker pull ghcr.io/kirbylink/java-warp4j:latest

---

Examples

Example 1: Create a Linux aarch64 executable for java-warp4j

java -jar warp4j-1.1.1-jar-with-dependencies.jar \
    --jar /home/developer/git/java-warp4j/target/warp4j-1.1.1-jar-with-dependencies.jar \
	--output /home/developer/git/java-warp4j/target \
	--optimize \
	--class-path /home/developer/git/java-warp4j/target/classes \
	--add-modules jdk.crypto.ec \
	--linux-aarch64 \
	--prefix warp4j

Example 2: Cross-compile for macOS and Windows for java-e-liquid-calculator

java -jar warp4j-1.1.1-jar-with-dependencies.jar \
    --jar /home/developer/git/java-e-liquid-calculator/target/e-liquid-calculator-1.1.6-jar-with-dependencies.jar \
	--output /home/developer/git/java-e-liquid-calculator/target \
	--optimize \
	--spring-boot \
	--windows-x64 \
	--macos-x64 \
	--prefix e-liquid-calculator

---

Docker

Using Docker

You can use Docker to bundle your app into native executables without installing Java locally.

Building the Docker Image

docker build --build-arg TARGET_ARCH=x64 -t java-warp4j .

or

docker buildx build --platform linux/amd64 --build-arg TARGET_ARCH=x64 -t java-warp4j .

Running the Docker Container

docker run --rm \
  -v /home/developer/warp4j:/data \
  java-warp4j \
  --spring-boot \
  --jar /data/e-liquid-calculator-1.1.6-jar-with-dependencies.jar \
  --linux-x64 \
  --pull \
  --output /data \
  --optimize \
  --prefix e-liquid-calculator

Offline Usage with Docker

The application can also run completely offline if the required dependencies are pre-downloaded and mounted into the container:

docker run --rm \
  -v /home/developer/warp4j/output:/data \                              # Output folder for the generated bundle
  -v /home/developer/warp4j/cache/jdk:/root/.local/share/warp4j/jdk \   # Cached JDKs for different platforms
  -v /home/developer/warp4j/cache/warp:/root/.local/share/warp4j/warp \ # Cached warp-packer binary
  java-warp4j \
  --spring-boot \
  --jar /data/e-liquid-calculator-1.1.6-jar-with-dependencies.jar \
  --linux-x64 \
  --output /data \
  --optimize \
  --prefix e-liquid-calculator

💡 Note: For offline use, the following files must already exist:

• warp4j/cache/jdk/linux/x64/jdk-21.0.7+6 → extracted full JDK directory
• warp4j/cache/warp/warp-packer → warp binary for the platform

These directories can be populated:

• manually (e.g. by downloading and extracting the JDKs yourself),
• or by running the tool once online (it will cache all needed components).

For more information about offline capabilities, see Offline Support.

---

Building the Project

For detailed instructions on how to build the project from source, please refer to BUILD.md.

---

Contributing

Contributions to the project from the community are welcome. Please read the CONTRIBUTING.md for guidelines on how to contribute.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Contact

For any questions or feedback, please open an issue on GitHub.

---