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"                       # public registry package
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.

Private registry deps need walnut login on the machine that fetches them (token in ~/.walnut/credentials).

Package layout (`walnut-package.toml`)

name = "greeter"
version = "0.1.0"
modules = "src"

[dependencies]

Org / private publish:

name = "shout"
version = "0.1.0"
organization = "acme"
visibility = "private"

modules — directory of .walnut files (default src)
organization — optional; publish as org/name
visibility — public (default) or private (org packages only)
[[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 greeter`	Registry pin (with version in the app manifest)
`walnut add path:packages/Foo`	Path dep
`walnut update [dir] [name]`	Refresh pin(s)
`walnut login` / `logout` / `publish`	Registry auth — registry.md

registry.md — login, publish, private packages, 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`)