kwenza(1)

NAME

kwenza - A simple, declarative build tool for the JVM

SYNOPSIS

kwenza [options] command [options] [command [options]]…

kwenza [--version | --list | --help]

DESCRIPTION

kwenza builds the Java project in the current directory, described by its kwenza.toml (see Manifest Reference). There’s no --project <path> option yet: cd into the project first, as with Maven, Gradle or Cargo.

Commands can be chained, and run in the order given: kwenza clean build run. Resolving and compiling happen at most once per invocation, however many commands in the chain need them, so kwenza build run compiles once and run reuses the result. clean starts that over: kwenza build clean package compiles again after clean, rather than packaging the classes it deleted. Every argument is checked before any command runs, so a mistyped command at the end of a chain fails before the first one does anything.

Running kwenza with no command prints a short usage summary.

COMMANDS

Build Commands

kwenza-build(1): Compile the current project.
kwenza-test(1): Compile and run the tests.
kwenza-run(1): Run the project’s main class.
kwenza-package(1): Package the project as a jar.
kwenza-clean(1): Remove the output directory.

Dependency Commands

kwenza-resolve(1): Write kwenza.lock if it is missing or out of date.

General Commands

kwenza-help(1): Display help for a kwenza command.
kwenza-version(1): Show version information.

OPTIONS

These go before the first command:

-V
--version: Print version information and exit.
--list: List all commands.

These go anywhere on the command line:

-v
--verbose: Print extra detail: one line per resolved dependency when resolving from Maven Central, and the full java command (binary path and every classpath entry) when running something.
-h
--help: Print help: the usage summary before the first command, or a command’s options after it.

Each command’s own options go after it, and apply to that command only.

OUTPUT

kwenza’s own status lines go to standard error, one per step, labelled with the step: resolve: …, compile: …, test: …, package: …, clean: …. That includes the steps a command runs implicitly, such as kwenza run resolving and compiling first. Standard output is left to the program kwenza run starts and the test report kwenza test prints, so kwenza run > out.txt captures only the program’s own output. Help, --list and --version print to standard output.

In a terminal, status lines are cyan, errors red, and --verbose detail grey, so they stand apart from a program’s own output. Colour is off when output isn’t a terminal, or when NO_COLOR is set.

With --verbose, a resolution from Maven Central (a missing or outdated lock) prints one grey line per resolved artifact:

resolve: fetching dependencies from Maven Central...
  com.google.guava:guava:33.2.1-jre  (direct)
  com.google.guava:failureaccess:1.0.2  (via com.google.guava:guava)
resolve: 7 artifact(s) resolved -> kwenza.lock

Resolving from a lock that already matches has no per-artifact lines to print.

ENVIRONMENT

KWENZA_REPO: The local dependency cache, in Maven’s layout. Defaults to ~/.m2/repository, shared with any Maven or Gradle install. Useful for CI, or for keeping a cache separate from your own.
KWENZA_TIMING: Set to any value to print a timing breakdown to standard error: JVM startup, then how long each phase that ran took (loading the manifest, resolving, compiling, packaging), and the total. A phase that didn’t run, because an earlier command in the chain already did it, isn’t listed. See Architecture for what it shows.
NO_COLOR: Set to any value to turn colour off. See no-color.org.

Example KWENZA_TIMING output:

resolve: using locked dependencies (kwenza.lock)
compile: target/classes
package: target/hello-world-0.1.0.jar
[timing] jvm-bootstrap-to-main: 18ms
[timing] load manifest: 6ms
[timing] resolve (from lock): 30ms
[timing] resolve main classpath: 42ms
[timing] compile: 268ms
[timing] package: 4ms
[timing] total (main to report): 379ms

EXIT STATUS

0: every command succeeded.
1: kwenza failed, for a reason you can fix; the error message says what and how.
2: the command line was invalid: an unknown command or option.
101: kwenza hit a bug in itself. Please report it at github.com/kwenza-build/kwenza/issues, with the output of --verbose, which adds the stack trace.
Anything else: the exit code of the program kwenza run started, or of the test launcher after a test failed, passed through unchanged.

A chain stops at the first command that fails, and kwenza exits with that command’s code.

EXAMPLES

Build and run the project:

kwenza run

Rebuild from scratch, run the tests, and package the jar:

kwenza clean test package