Packages

zlow install reads the coordinates in zlow.json and fills kotlin_modules. Compiling stays on the Kotlin page.

How it fits

zlow does two different jobs for Kotlin. The compiler turns .kt files into a native binary with zlow native. The package manager downloads libraries and puts their .kt files on disk, where that compile can see them.

Installing zlow itself is npm install @zlow/cli. After that command exists, zlow install inside a Kotlin project installs that project’s dependencies. zlow install does not compile. When you want a binary, run zlow native ..

Install dependencies

Name each library as group:artifact and pin an exact version, or one Maven range:

zlow.json

{
  "language": "kotlin",
  "entry": "src/main.kt",
  "dependencies": {
    "com.example:math": "1.0.0",
    "com.example:leaf": "[1.0,2.0)"
  }
}

Terminal

zlow install
zlow install --offline

The first successful install writes zlow.lock next to zlow.json. Commit that file. Later installs repeat it and do not read a range again. The lock’s language is kotlin, so it is not an npm lock. A range such as [1.0,2.0) or [1.0,) becomes the highest version in that artifact’s maven-metadata.xml that the range admits. The lock stores that exact version. 1.0.0 with no brackets stays that version.

Downloads come from https://repo1.maven.org/maven2. Pass --registry to use another Maven-layout registry for this one command. A file: URL reads a directory on disk.

zlow fetches the .pom and the .jar, and checks each against its .sha256 file before keeping it. The jar is cached at ~/.cache/zlow/maven, or under $XDG_CACHE_HOME/zlow/maven when that variable is set. .kt files from the jar are written to kotlin_modules/<group>/<artifact>/. When that jar has no .kt files, zlow fetches <artifact>-<version>-sources.jar and its checksum, and writes the .kt files from that archive instead. The lock records which archive supplied them, and a later install extracts the same one. If the main jar already has .kt files, the sources jar is left alone. If neither archive has .kt files, zlow prints sources: none and the coordinate adds nothing to the compile. A missing or wrong sources checksum stops the install and leaves the lock and kotlin_modules as they were. zlow native compiles the extracted files together with yours, as one program.

Dependencies listed in the POM are installed too, when their scope is compile or runtime and they are not optional. A POM version that is one Maven range is resolved the same way. A ${property} zlow cannot see stops the install. Nothing is written when a download fails.

If zlow.json names dependencies and kotlin_modules is missing, zlow native stops with error[pm.not_installed].

Add and remove

Terminal

zlow add com.example:math@1.0.0
zlow add --dev com.example:math@1.0.0
zlow remove com.example:math

add updates zlow.json, zlow.lock, and kotlin_modules together. --dev records the coordinate under devDependencies. remove drops that direct dependency. A library that another installed library still needs stays on disk.

Install again

Terminal

zlow install
zlow install --offline
zlow install --production

A later zlow install repeats the lock. It does not go looking for newer versions on its own.

--offline uses the cache only. If a required jar is missing from the cache, install stops with error[pm.offline_miss].

--production leaves devDependencies out of kotlin_modules. The lock still lists them. zlow prints dependencies: production (dev omitted).

Edit a version in zlow.json so it no longer matches the lock, and install stops with error[pm.lock_stale]. It does not quietly pick a replacement. Change the lock with zlow add.

Kotlin has no lifecycle scripts. Install prints scripts: skipped (kotlin has no lifecycle scripts). zlow run and zlow exec are the TypeScript commands. In a Kotlin project they stop and tell you to use zlow native.

Publish

Say which coordinate this project is, then upload it:

zlow.json

{
  "language": "kotlin",
  "entry": "src/main.kt",
  "coordinates": "com.example:app",
  "version": "1.0.0"
}

Terminal

zlow publish --registry file:./repo

zlow publish packs the project’s .kt files into a jar, writes a POM, and writes a sha256 checksum, in Maven layout. kotlin_modules is not packed. Publishing to an https registry needs a token in ZLOW_MAVEN_TOKEN. The token is never printed. If coordinates, version, or that token is missing, nothing is sent, and zlow reports error[pm.publish_incomplete].

Publishing a version the registry already has stops with error[pm.version_exists].

Workspaces

A root zlow.json can list member directories in workspaces, either as an array or as { "packages": ["members/a"] }. zlow install at that root installs external libraries once and links each member’s .kt files under kotlin_modules using the member’s coordinates.

members/app/zlow.json

{
  "language": "kotlin",
  "entry": "src/main.kt",
  "dependencies": {
    "com.example:math": "workspace:*"
  }
}

workspace:* means that member. zlow native in the member compiles the linked sources with its own. zlow publish --workspace members/app uploads that member only. The POM records the other member’s exact version. The zlow.json on disk still says workspace:*.

Limits

These are refused before a library is kept:

A version that is not an exact pin or one Maven restriction (^1.0.0, LATEST, RELEASE, two ranges written together). A range that matches nothing in maven-metadata.xml, or an artifact with no metadata file, is the same pm.version_range.
A -SNAPSHOT version (pm.version_snapshot).
A version no POM states, or a ${property} that neither the POM nor its parents define (pm.version_unsatisfied).
A parent or BOM that is not in the registry (pm.parent_missing), a parent chain that loops (pm.parent_cycle) or passes 20 POMs (pm.parent_depth), and a parent that declares dependencies of its own (pm.parent_dependencies).
A test, provided, or system dependency. Optional dependencies are skipped.
A POM or jar with no .sha256 file (pm.integrity_missing), or one that does not match it (pm.integrity_mismatch). Maven Central publishes only .sha1 and .md5 for org.jetbrains.kotlin artifacts, so a library that depends on kotlin-stdlib or kotlin-reflect is refused today.
A jar entry whose path contains ... A jar that is not a readable zip (pm.archive_unreadable).
A workspaces value that is not a list of directories (pm.workspaces_shape), a member path outside the root, or a member that is not there (pm.workspace_missing).
Gradle plugins, version catalogs, and build.gradle.

The message looks like error[pm.version_range]. The name after pm. says which limit you hit. Python, Rust, and C++ stay compilers. Their zlow install stops with error[pm.not_a_package]. Go modules are covered on the Go packages page.