Workspaces

A workspace is a set of member packages in one repository that are built, tested and resolved together. An application member can consume a sibling library member through the workspace dependency mechanism — the Phase 117 workspace dependency fix made cross-member calls resolve deterministically.

When to use a workspace

Use a workspace when one repository contains several .kark packages and an application must call functions that live in a sibling package. For a single package, the Your First Karkain Project layout is enough.

The minimal workspace

Create a workspace root with two members, app and library:

workspace/
  karkain.toml       # workspace manifest (karkain init / workspace)
  app/
    karkain.toml     # app manifest
    src/
      main.kark
  library/
    karkain.toml     # library manifest
    src/
      api.kark

Setup

$ karkain workspace init              # in the workspace root
$ karkain workspace add app
$ karkain workspace add library

Each member directory gets a manifest. The library member exposes its API from a non-main module (the assembly keeps only the root file’s func main), e.g. library/src/api.kark:

func greet() {
    print("hi from library api")
}

The app member declares the workspace dependency in its manifest and calls the library function from app/src/main.kark:

func main() {
    greet()
}

Build, test and run the whole workspace:

$ karkain workspace build
$ karkain workspace test
$ karkain workspace run

Members are processed in dependency order — a member that depends on another builds after it. A dependency cycle is rejected before any build. The workspace graph command prints the member dependency graph.

Behavior on the Phase 117 fix

Cross-member calls resolve through the workspace dependency sources: an app member may call a function exported by a sibling library member. The reverse is also true only if a dependency is declared. A cross-member call without a declared dependency fails at build/run with an undefined-identifier error on both engines — it is never silently dropped.

The runnable example lives at examples/workspace/ in the repository and is exercised by the release-candidate gate (pkg/cli/phase118_rc_test.go).

Real surfaces and boundaries

  • workspace list | build | test | run | graph | init | add | remove | clean | lint | check are implemented.

  • Workspace dependencies are resolved from the local repository only — there is no public package registry (see Stable API Snapshot (1.2.0)).

  • The package manager also supports --source local (path) dependencies for a single project; see Dependencies.

See also

Dependencies — single-project dependency resolution. Your First Karkain Project — the minimal single-package project. Project Layout — the manifest and directory conventions. Command-Line Interface — the workspace command reference.