Skip to content

distribution.md

Latest commit

 

History

History
112 lines (85 loc) · 7.15 KB

distribution.md

File metadata and controls

112 lines (85 loc) · 7.15 KB
Raw

SDK distribution

How the chunk SDK is packaged, installed and published. A release of the SDK has two parts that share one version:

  • The CLI archives, chunk-<version>-<os>-<arch>.tar.gz with .sha256 checksums for linux-x64, linux-arm64, darwin-x64, darwin-arm64 and windows-x64, attached to a GitHub release. Each holds the chunk executable, the native TypeScript compiler it type-checks projects with (under toolchain/), and the license. The CLI embeds the TypeScript SDK, the project templates, the Gradle wrapper and the version pins that chunk create writes.
  • The JVM artifacts, published to https://maven.chunkzero.com (nightlies to https://maven.chunkzero.com/nightlies) under com.chunkzero.chunk: proto, backend-api, backend-client, backend-client-kotlin, runtime, multistom, multistom-kotlin, minestom, the Gradle plugin and its two plugin markers. Each library has -sources.jar and -javadoc.jar (Dokka HTML) artifacts. Projects resolve these through Gradle; the CLI archives contain no JARs.

Linux archives are built on Ubuntu 24.04 and need its glibc and OpenSSL 3; macOS and Windows archives link OpenSSL statically. Users need Java to run Gradle; the Minestom runtime needs Java 25, which the generated projects download through Gradle's toolchain resolver. Building a project needs no Rust, Node, pnpm or chunk checkout. Minestom itself is a pinned nightly of chunkzero/multistom, com.chunkzero.multistom:multistom, served from https://maven.chunkzero.com/nightlies.

Versions

The Cargo workspace version is the upcoming release, e.g. 0.1.0 or 0.1.0-beta.1, and the chunk version in gradle/libs.versions.toml must equal it: packaging refuses to run otherwise, and the CLI refuses to create projects from a checkout of another version. Change both together, and bump them right after publishing a release.

Every build gets one version, shared by the CLI, its archives, the JVM artifacts and the plugin version that chunk create pins:

  • a release is the workspace version itself, tagged v<version>;
  • a nightly is <X.Y.Z>-nightly.<UTC commit time, YYYYMMDDHHMMSS>.g<12-character commit>, so a commit always gets the same version and later commits sort higher.

Release builds set it through CHUNK_RELEASE_VERSION for the CLI and -Pchunk.version for Gradle; local builds use the workspace version. Projects created by a nightly CLI read Chunk's JVM artifacts from the nightlies repository. A project keeps the versions it was created with in settings.gradle.kts.

Published versions never change: GitHub releases and Maven artifacts are immutable, and nightlies are never deleted.

The Gradle wrapper files in the repository root are generated by Gradle and embedded in the CLI. To update Gradle, regenerate them with the wrapper task and rebuild the CLI.

Install

Install with mise. Releases come from GitHub; nightlies and betas come from the chunkzero mise plugin, which reads chunkzero/mise-registry:

[plugins]
chunkzero = "https://github.com/chunkzero/mise-chunkzero"

[tools]
"github:chunkzero/chunk" = "latest"
# or the newest nightly:
"chunkzero:chunk-nightly" = { version = "latest", prerelease = true }

Keep the installed directory intact: the CLI finds its TypeScript compiler next to its executable.

scripts/install.sh VERSION [ARCHIVE] installs a Linux x64 archive from the GitHub release, or a local ARCHIVE with the ARCHIVE.sha256 beside it, verifying both the checksum and the CLI's version, to ~/.local/share/chunk/VERSION and links ~/.local/bin/chunk to it. CHUNK_INSTALL_DIR replaces the ~/.local prefix. It refuses to overwrite an installed version, or a bin/chunk that is not a symlink.

Build and verify locally

just package-cli
python3 scripts/check-sdk.py target/dist/chunk-0.1.0-linux-x64.tar.gz target/dist/maven

just package-cli builds the release CLI and runs scripts/package-sdk.py, which writes the archive, its checksum and a maven/ repository with every JVM artifact to target/dist/. It refuses to replace existing outputs; pass --output DIRECTORY for another candidate of the same version, or --chunk PATH to package another CLI build.

scripts/check-sdk.py checks the sources and documentation JARs, installs the archive into a temporary prefix, serves the Maven directory over local HTTP, and creates, generates and builds a Java and a Kotlin project against them, checking the resulting releases. Those projects neither include the chunk build nor read this checkout.

To try unpublished artifacts in your own project, set its chunk.mavenRepository Gradle property to file:///absolute/path/to/target/dist/maven.

Publishing

The Release workflow (.github/workflows/release.yml) publishes a nightly every day main has changed. Run it manually from main with the nightly or release channel to publish one now. It:

  1. computes the version with chunkzero/release-tools, and only registers it (step 6) when it's already published;
  2. builds and packages the CLI on every platform, and stages the JVM artifacts on Linux x64;
  3. installs the Linux x64 archive in a clean Ubuntu 24.04 container that has only Java and the verification scripts, then creates, generates and builds a Java and a Kotlin project against the staged Maven files;
  4. publishes the staged Maven files to default/nightlies or default/releases through the Maven R2 CLI with scripts/publish-maven.py, and checks the public endpoint serves the published POM;
  5. publishes the archives as a GitHub release, a prerelease for any version with a - suffix; and
  6. registers the release in the mise registry through an auto-merging pull request.

Maven goes first, so a published CLI never pins JVM artifacts that don't resolve. Publication uses the exact files that passed verification. Maven R2 makes a publication visible all at once and rejects different files at an existing version, so never reuse a version for different artifacts. Rerun failed jobs to retry with the same files; the run's artifacts are deleted once publishing succeeds. If the final Maven commit fails transiently, the CLI leaves the session open and prints its ID; maven-r2 session status, commit or abort with that ID, the same server and publishing credentials inspects, finishes or discards it within 24 hours.

The SDK distribution workflow (.github/workflows/sdk.yml) runs the same Linux packaging and verification on pull requests that change distribution inputs once they are ready for review.

Publishing needs the organization secrets MAVEN_R2_TOKEN, a Maven R2 token that can publish com/chunkzero/ to default/nightlies and default/releases, and REGISTRY_APP_ID with REGISTRY_APP_PRIVATE_KEY, for the GitHub App that opens registry pull requests. The workflow installs Maven R2 CLI v0.1.0; keep it compatible with the deployed service (see the Maven R2 publishing guide).