Documentation

Walnut packages

Share Walnut source modules across apps: local path packages, GitHub/git pins, and a hostable package registry.

walnut install vendors resolved packages into vendor/walnut/ (commit that tree) so CI and offline builds do not need the network.

Packages compose TEA modules (import Foo). Native host libraries still live in the app’s ios/project.yml (with optional auto-merge from package host.spm).

The standard library stays toolchain-bundled — it is not a normal package.

Quick start

cd MyApp
walnut install
walnut check

Commit walnut.lock and vendor/walnut/.

App manifest (`walnut.toml`)

name = "MyApp"
bundle_id = "com.example.myapp"
sources = "src"
# runtime is set by `walnut new` / Homebrew; override only if needed

[packages]
vendor = true
path = "vendor/walnut"

[[source]]
name = "walnut"
url = "https://packages.walnutlang.com"

[dependencies]
Greeter = "0.1.0"                       # registry version
Shout = { path = "packages/Shout" }     # local path (copied into vendor on install)
Remote = { github = "org/repo", tag = "v0.1.0" }

Field	Meaning
`[packages] vendor`	When `true` (default), materialize into `path` and expect it committed
`[packages] path`	Vendor root (default `vendor/walnut`)
`[[source]]`	Named registry base URL
string dep `"0.1.0"`	Version from the default (first) source
`path`	Local package directory (relative to the app)
`git` / `github`	Remote clone; lock stores commit; tree vendored without `.git`

Vendoring (offline / CI)

Declare deps and [[source]].
walnut install writes vendor/walnut/<Name>/ and walnut.lock.
Commit vendor + lock. Teammates / CI run walnut install against the vendor tree without contacting the registry.
walnut update may hit the network, then rewrites vendor.

Package layout (`walnut-package.toml`)

name = "Greeter"
version = "0.1.0"
modules = "src"

[dependencies]

modules — directory of .walnut files (default src)
organization — optional; publish as org/name
[[host.spm]] — merged into ios/project.yml on install

Each file declares module Prefixed.Name. Module names must be unique across the app and all packages. Prefer a package prefix (Greeter.Hello).

CLI

Command	Role
`walnut install [dir]`	Resolve → `vendor/walnut` + `walnut.lock`
`walnut add [email protected]`	Registry pin
`walnut add path:packages/Foo`	Path dep
`walnut update [dir] [name]`	Refresh pin(s)
`walnut login` / `publish`	Registry auth + upload

registry.md — login, publish, commercial seats
stdlib.md — toolchain libraries (not packages)
toolchain.md — CLI overview

Quick start

App manifest (walnut.toml)

Vendoring (offline / CI)

Package layout (walnut-package.toml)

CLI

Related

App manifest (`walnut.toml`)

Package layout (`walnut-package.toml`)