kbuild is the shared build and repo orchestration tool for the ktools ecosystem.

Its purpose is to keep the language workspaces predictable even when they have different compilers, package layouts, or backend requirements.

Core Responsibilities

• validate repo-local build configuration
• build SDKs and demos into named build slots
• orchestrate language workspace batch operations
• initialize and sync git state when a repo uses the standard kbuild workflow
• support multiple backend families behind one command model

What Stays Consistent

Across the ktools workspaces, kbuild is expected to preserve:

• a repo-root marker through ./.kbuild.json
• predictable output layout under build/<slot>/
• ordered batch forwarding into child components where a workspace uses them
• strict command combinations and early validation

Language Pages

The language-specific kbuild pages in the website describe how each workspace uses the shared build tool today. Some workspaces rely directly on the shared kbuild repo, while others may later grow language-specific backend work.

kbuild is a strict Python build and repo orchestration tool for ktools-style projects. It handles five related jobs:

• creating and validating repo-local kbuild config
• building core targets into named build slots
• building ordered demo trees against the core SDK and dependency SDKs
• scaffolding and helper operations such as repo initialization, git setup, and repo-local vcpkg
• batch-forwarding commands into child repos

Start Here

• Command guide
• Config guide
• Swift backend notes
• Common workflows
• Full operator reference

Typical Flow

Fresh directory:

kbuild --kbuild-config
# edit .kbuild.json
kbuild --kbuild-init
kbuild --vcpkg-install

Existing repo:

kbuild --build-latest
kbuild --build-demos
kbuild --clean-latest

kbuild selects exactly one backend from the repo config. The shared tree currently supports:

• cmake
• cargo
• java
• swift
• kotlin
• csharp
• javascript

Core Concepts

Repo root

• kbuild only runs from a directory containing ./.kbuild.json.

Primary config

• ./.kbuild.json is the required repo marker and primary config file.

Optional shared base

• ./kbuild.json is optional. When present, kbuild deep-merges ./.kbuild.json on top of it.

Build slots

• Core builds live under build/<slot>/.
• Demo builds live under demo/<demo>/build/<slot>/.
• The default slot is latest.

SDK-first demos

• Root builds install an SDK under build/<slot>/sdk.
• Demos consume that SDK, optional dependency SDKs, and optionally earlier demo SDK outputs in the requested order.

Repo-local vcpkg

• When the effective config defines vcpkg, kbuild expects a repo-local checkout under ./vcpkg/src and integrates it through CMake manifest mode.

Which Command Should I Reach For?

• Use kbuild --build-latest for the normal build path.
• Use kbuild --build-demos when you want explicit demo validation.
• Use kbuild --cmake-no-configure only for cmake repos when the target build directory already contains CMakeCache.txt.
• Use kbuild --vcpkg-install only for cmake repos the first time a repo-local vcpkg project is prepared.
• Use kbuild --git-initialize only once, after scaffold generation and remote creation.

Working References

If you want the code behind the behavior, start with:

• kbuild entry script
• libs/kbuild/engine.py
• libs/kbuild/config_ops.py
• libs/kbuild/repo_init.py
• templates/

If you want the exhaustive CLI and schema rules, use the full operator reference.

This page is the fast path through the kbuild command surface. For the full option-by-option reference, see kbuild.md.

Command Groups

Bootstrap Commands

kbuild --kbuild-config
kbuild --kbuild-init

What they do:

• --kbuild-config creates a starter ./.kbuild.json.
• --kbuild-init scaffolds a new repo from the effective kbuild config.

Build Commands

Normal build:

kbuild --build-latest

Alternate slot:

kbuild --build dev

Explicit demo builds:

kbuild --build-demos
kbuild --build-demos sdk/alpha sdk/beta exe/core

Important behavior:

• Core output is build/<slot>/.
• SDK install output is build/<slot>/sdk.
• Demo output is demo/<demo>/build/<slot>/.
• --build-demos with no demo names uses build.demos.
• --build-latest can auto-build demos from build.defaults.demos.

CMake Build Controls

kbuild --build-latest --cmake-configure
kbuild --build-latest --cmake-no-configure
kbuild --build-latest --cmake-jobs 8
kbuild --build dev --cmake-linkage both

Rules:

• --cmake-configure forces configure for the current run.
• --cmake-no-configure requires an existing CMakeCache.txt.
• --cmake-jobs <n> overrides configured job count.
• --cmake-linkage <t> accepts static, shared, or both.

Clean Commands

kbuild --build-list
kbuild --clean-latest
kbuild --clean dev
kbuild --clean-all

Clean behavior is intentionally conservative:

• slot names must be simple tokens
• removal is restricted to expected build/ and demo/*/build/ layouts
• symlinked build directories are refused

Git Commands

kbuild --git-initialize
kbuild --git-sync "Update docs"

Important behavior:

• --git-initialize verifies configured remote access and non-interactive auth, initializes main, creates the first commit, and pushes origin/main.
• --git-sync only works when ./.git exists and the current directory is the git worktree root.

Vcpkg Commands

kbuild --vcpkg-install
kbuild --vcpkg-sync-baseline

Important behavior:

• --vcpkg-install clones or verifies ./vcpkg/src, bootstraps it, ensures repo-local cache directories, syncs the manifest baseline, then continues the normal build flow.
• --vcpkg-sync-baseline updates vcpkg/vcpkg.json from the current ./vcpkg/src HEAD commit.

Combination Rules

kbuild is strict about command mixing.

• Root help commands such as --kbuild, --cmake, --git, --vcpkg, and bare --clean/--build help forms must run alone.
• --kbuild-config, --kbuild-init, --git-initialize, --git-sync, and --vcpkg-sync-baseline are exclusive modes.
• Clean modes cannot be combined with build or git modes.
• Unknown flags and unexpected positional arguments hard-fail.

If you need the exhaustive matrix and all examples, use kbuild.md.

This page collects the normal operating sequences for kbuild.

Empty Directory To Scaffolded Repo

1. Create starter config in the empty directory.
2. Edit the config.
3. Scaffold the repo.
4. Initialize git if needed.
5. Install local vcpkg if the repo uses it.

kbuild --kbuild-config
# edit ./.kbuild.json
kbuild --kbuild-init
kbuild --git-initialize
kbuild --vcpkg-install

Notes:

• --kbuild-init requires the directory to be otherwise empty except for kbuild.json and .kbuild.json.
• scaffolded SDK repos include core CMake files, demo trees, test placeholders, and optional vcpkg/vcpkg.json.

Existing Repo Day-To-Day

Normal build:

kbuild --build-latest

Fast rebuild from an existing cache:

kbuild --build-latest --cmake-no-configure
kbuild --build-demos --cmake-no-configure

Fresh rebuild:

kbuild --clean-latest
kbuild --build-latest

Explicit Demo Validation

Build demos from config order:

kbuild --build-demos

Build an explicit chain:

kbuild --build dev --build-demos sdk/alpha sdk/beta exe/core

Why order matters:

• demos can consume the core SDK install under build/<slot>/sdk
• demos can consume SDK dependencies from cmake.dependencies
• later demos can consume SDKs installed by earlier demos in the same run

Multi-Repo SDK Stack

Use one shared slot name across the related repos, then build dependencies before consumers.

Example:

cd ../kcli
kbuild --build dev

cd ../ktrace
kbuild --build dev --vcpkg-install

cd ../myproject
kbuild --build dev --vcpkg-install
kbuild --build dev --build-demos

This works cleanly when cmake.dependencies uses version-aware prefixes such as:

"dependencies": {
  "KcliSDK": {
    "prefix": "../kcli/build/{version}/sdk"
  },
  "KTraceSDK": {
    "prefix": "../ktrace/build/{version}/sdk"
  }
}

Git Bring-Up

After scaffold generation and remote creation:

kbuild --git-initialize

For later full syncs:

kbuild --git-sync "Update project docs"

kbuild refuses to use a parent git worktree for sync operations. The repo must be rooted at the current directory.

Vcpkg Bring-Up

For repos that define a vcpkg object:

kbuild --vcpkg-install

This prepares:

• vcpkg/src
• vcpkg/build/downloads
• vcpkg/build/binary-cache

If you only need to update the manifest baseline from the checked-out vcpkg commit:

kbuild --vcpkg-sync-baseline

When To Stop And Reconfigure

Run a configure pass again when:

• toolchain settings changed
• dependency prefixes changed
• vcpkg state changed
• linkage mode changed
• you cleaned the build slot

Use:

kbuild --build-latest --cmake-configure

For the exhaustive command semantics and failure cases, see kbuild.md.