zb (Zero Dependencies Builder)

The entire build tool is a single ~30 KB zb.jar. No install, no daemon, no plugin tree, no ~/.m2 — one tiny jar and a Java 25 runtime is the whole story.

Built with pure Java 25, zb compiles and packages your project with zero external dependencies — its own and yours.

Why zb

• 🪶 ~30 KB, one jar — the whole build tool fits in a single zb.jar you can read, commit, and copy anywhere
• 🚀 Zero dependencies — nothing to download but the jar itself; pure Java 25, no third-party libraries
• ⚡ Instant builds — no dependency resolution, no daemon warm-up; just javac and packaging
• 🔍 Automatic main class detection — no manifest boilerplate
• 📦 Executable JAR generation out of the box
• 🎯 One command, zero config — sensible defaults, optional .zb file when you want control

Speed

No dependency resolution, no daemon, no warm-up — just javac and packaging. Cold-start, measured on LightMetal:

Project	Build	Tests (zunit)
zb (builds itself)	306 ms	6 unit tests in 547 ms
zsmith	679 ms	18 unit tests in 1.3 s
lightmetal	662 ms	5 unit tests in 2.6 s

Build = compile + package the executable JAR.

Prerequisites

• Java 25 or later
• Git (for cloning the repository)

Installation

Quick Install (from latest release)

zbinstall is a single-file Java 25 script that fetches zb.jar and zb.sh from the latest GitHub release into the current directory:

# Fetch the installer and run it
curl -fsSLO https://raw.githubusercontent.com/AdamBien/zb/main/zbinstall
chmod +x zbinstall
./zbinstall

# Move both files onto your PATH
mv zb.jar zb.sh ~/bin/

The download is atomic — a partial download cannot replace an existing zb.jar or zb.sh.

Based on the java-cli-script skill from airails.dev — single-file, zero-dependency, shebang-launched Java 25 utilities.

Build from Source

# Clone the repository
git clone https://github.com/AdamBien/zb.git
cd zb

# Bootstrap zb itself with the installer, then build
./zbinstall
java -jar zb.jar

# The executable JAR will be in zbo/app.jar
# Copy it (as zb.jar) along with the shell wrapper to your desired location
cp zbo/app.jar ~/bin/zb.jar
cp src/main/sh/zb.sh ~/bin/
chmod +x ~/bin/zb.sh

Shell Wrapper

The zb.sh script provides a convenient way to run zb without typing java -jar:

# Instead of: java -jar zb.jar
zb.sh

Usage

Basic Usage

# Compile and package with defaults
java -jar zb.jar

# Custom source directory
java -jar zb.jar src/main/java

# Custom source and output directories
java -jar zb.jar src/main/java target/classes target/jar

# Full customization (source, classes, jar directory, jar filename)
java -jar zb.jar src/main/java target/classes target/jar myapp.jar

Default Configuration

Parameter	Default Value
Source Directory	src/main/java, src or current directory
Classes Directory	<temp.dir> (temporary directory)
JAR Output Directory	zbo
JAR Filename	app.jar

Configuration File (.zb)

zb supports configuration through a .zb properties file in your project root. If not present, zb will automatically create one with default values on first run.

Supported Properties

Property	Description	Default Value
sources.dir	Source directory path	<discovered by zb>
resources.dir	Resources directory path	<discovered by zb>
classes.dir	Compiled classes output directory	<temp.dir>
jar.dir	JAR output directory	zbo/
jar.file.name	Name of the generated JAR file	app.jar
post.build.hook	Script to execute after a successful build	<none>

Example Configuration

# .zb configuration file
sources.dir=src/main/java
resources.dir=src/main/resources
classes.dir=<temp.dir>  # or specify a custom directory like target/classes
jar.dir=target/
jar.file.name=myapp.jar

Auto-Discovery

When sources.dir or resources.dir are set to <discovered by zb>, the tool will automatically:

• Search for source directories in common locations (src/main/java, src, or current directory)
• Locate resource directories relative to the source directory

Temporary Directory for Classes

When classes.dir is set to <temp.dir>, zb will:

• Create a unique temporary directory for compiled classes
• Display the temporary directory path during build
• Automatically clean up the directory after JAR creation
• This is the default behavior to avoid cluttering your project

Post-Build Hook

zb can execute any script after a successful build. Configure post.build.hook in your .zb file:

# Run zunit tests after every successful build
post.build.hook=zunit

The hook receives build context as environment variables: ZB_JAR_PATH, ZB_SOURCE_DIR, ZB_JAR_DIR, ZB_JAR_FILE_NAME. A non-zero exit code is logged as a warning but does not fail the build.

How It Works

1. Source Discovery: Automatically finds all Java files in the source directory
2. Main Class Detection: Identifies the main class for the executable JAR
3. Compilation: Compiles all Java files to bytecode
4. Packaging: Creates an executable JAR with proper manifest

Testing with zunit

zunit is a zero-dependency, single-file Java test runner that integrates with zb. It reads the .zb configuration file to resolve the JAR classpath automatically:

# Build with zb, then run tests with zunit
zb && zunit

A /zunit skill is available for AI-assisted generation and execution of zunit tests.

AI-Assisted Development

zb includes a SKILL.md for use with airails.dev AI-assisted development workflows.

Videos