Advanced topics Distribution Native deployment

# KAR and KAB Archives

KAR and KAB are ZIP-compatible Klyn distribution formats. A `.kar` carries portable Klyn sources and resources. A `.kab`, or Klyn Archive Binary, carries native objects and resources for one precise target. These formats belong to the language toolchain and are not tied to a particular application or development environment.

Choosing the Format

Format | Contents | Portability | Typical use
--- | --- | --- | ---
`.kar` | Klyn sources and arbitrary resources | Portable wherever those sources can be compiled | Libraries, reusable modules, source distribution, and portable fallback
`.kab` | Native objects, compatibility metadata, and arbitrary resources | Bound to an OS, architecture, Klyn version, and object ABI | Fast production startup on a known target

Language-level packaging

Neither format imposes a manifest, entry class, lifecycle, or dependency-injection model. A consuming application may include and interpret its own metadata as an ordinary archive resource.

Source Directory Layout

    inventory/
    |-- src/
    |   `-- inventory/
    |       |-- Stock.kn
    |       `-- Product.kn
    |-- resources/
    |   `-- defaults.json
    `-- LICENSE

When a `src` directory exists, Klyn treats it as the source root and compiles every `.kn` file below it. Otherwise, the directory passed on the command line is itself the source root. Files outside the source root remain available as resources.

The directory must contain at least one Klyn source. Generated `.o`, `.obj`, `.kar`, and `.kab` files are never copied into a new archive.

Building a Portable KAR

    klyn --build-kar -o inventory.kar inventory

The command validates the source directory, stages its sources and resources in the versioned Klyn cache, and writes a deterministic ZIP-compatible archive. When `-o` is omitted, Klyn writes `<directory-name>.kar` beside the source directory.

Building a Native KAB

    klyn --build-kab -o inventory.kab inventory

Every source in the selected source root is compiled into a native object. Klyn also embeds the transitive concrete generic objects required at runtime, so the KAB does not depend on generated files left in the build machine's cache. Klyn omits the `.kn` files from the result and adds `binary.json`, which records the operating system, architecture, Klyn version, object ABI, object paths, and stable source identities required by a loader.

Normal object-cache rules apply: when a cached object is newer than its source, it is reused. Force a complete native rebuild only when necessary:

    klyn --rebuild --build-kab -o inventory.kab inventory

When `-o` is omitted, Klyn writes `<directory-name>.kab` beside the source directory.

Publishing Portable and Native Artifacts

    #!/usr/bin/env sh
    set -eu

    source_dir="inventory"
    output_dir="dist"

    mkdir -p "$output_dir"
    klyn --build-kar -o "$output_dir/inventory.kar" "$source_dir"
    klyn --build-kab -o "$output_dir/inventory.kab" "$source_dir"

A common release strategy publishes one portable KAR plus one KAB for every supported native target. Consumers can then prefer a compatible KAB for startup speed and retain the KAR for portability or source-based tooling.

Consuming an Archive

KAR and KAB define storage and compatibility, not how an application discovers or activates classes. A loader can expose the KAR source root to the Klyn class loader, or validate a KAB and load its object/source pairs as a native bundle. The consuming application remains free to select classes by package name, configuration, convention, or its own metadata.

This separation keeps the archive formats useful for general libraries, modular applications, command-line tools, desktop software, services, and any other Klyn deployment model.

Safety and Reproducibility

- Archive paths are relative and cannot escape the source directory.
- Symbolic links are rejected instead of being followed into unrelated directories.
- Generated archives and native object files are excluded from input.
- Entries are emitted in deterministic path order.
- KAB compatibility metadata must be validated before native objects are loaded.
- Temporary staging remains under the versioned Klyn cache, never in the source tree.