Configuration
pith.toml
The project manifest, read from the current directory (or the nearest ancestor that has one).
[project]
| Key | Type | Description |
|---|---|---|
name | string | Project name |
version | string | Project version |
[build]
| Key | Type | Default | Description |
|---|---|---|---|
target | string | "native" | Lowering target |
linker | string | "auto" | Linker selection: "auto" uses mold (Darwin) or tcc (elsewhere) |
engine | string | "auto" | Execution backend: "auto" uses libtcc (Linux/NT/FreeBSD) or temp-exec (Darwin) |
embedSource | bool | false | Attach the workspace as a tar overlay when building |
When embedSource = true, every pith build in this project embeds
the workspace, the same as passing --embed-source on the command
line.
[toolchain]
| Key | Type | Default | Description |
|---|---|---|---|
pithVersion | string | (none) | Pin the compiler version; forwards via execv when it differs from the running binary |
pithPlugin | yes/no (or true/false) | no | Build this project as an installable plugin (.ppkg) rather than an executable |
With pithPlugin = yes, pith build produces <name>.ppkg: a
bundle containing the compiled plugin object (with exported
c_<author>_<module>_<fn> symbols) and a manifest (author, module,
fn list). Other projects install it with pith pkg and call its
functions as <author>.<module>.<fn> (see
pith build and pith pkg).
[project] author
| Key | Type | Description |
|---|---|---|
author | string | The project’s author scope: plugin symbols are exported under c_<author>_<module>_<fn> and consumed as <author>.<module>.<fn> |
[project]
name = "myos"
author = "alice"
[toolchain]
pithPlugin = "yes"
A consumer of this plugin calls alice.myos.identifyKernel.
[dependencies]
Keys are package names; values are versions or local paths:
[dependencies]
os-utils = "1.0.0" # resolved from the registry or cache
mylib = "./libs/mylib" # resolved from a local directory path
tools = "./packages/tools" # another local path
[tasks.<name>]
Custom command recipes, dispatchable via pith <name>:
[tasks.build]
run = "pith run main.pi"
[tasks.deploy]
prod = "pith build main.pi -o dist/app --embed-source"
Nested keys become subcommands: pith deploy prod looks up
tasks.deploy.prod, falling back to tasks.deploy if absent.
pith.lock
Generated by pith pkg sync and pith pkg install. Records concrete
resolved versions with FNV-1a integrity hashes:
# pith.lock, concrete resolved dependencies (generated by pith pkg)
os-utils@1.0.0 9c35886d5a608143
The hash covers the installed package’s contents (file paths + file bytes). On subsequent syncs, installed packages are re-hashed and verified against the lock.
Environment variables
All runtime behavior is overridable without editing config files:
| Variable | Default | Description |
|---|---|---|
PITH_QBE | qbe | Path to the QBE compiler binary |
PITH_CC | cc | Compiler driver / system linker |
PITH_MOLD | mold | mold linker override |
PITH_TCC | tcc | tcc binary override |
PITH_TCCDIR | auto-detected | Directory containing libtcc1.a |
PITH_RUNTIME | auto-detected | Path to runtime/libruntime.a |
PITH_CACHE | ~/.cache/pith | Dependency cache directory |
PITH_REGISTRY | (none) | Local package registry directory (for pith pkg sync tarball sources) |
PITH_TOOLCHAIN_ACTIVE | (unset) | Internal guard, prevents toolchain forward loops |
Auto-detection order
The engine discovers its resources in this order (first hit wins):
libtcc1.a (PITH_TCCDIR):
$PITH_TCCDIR(if it containslibtcc1.a)<prefix>/lib/pith/tcc/(installed layout, relative to the binary)<root>/vendor/tcc/(build-tree layout)<root>/../vendor/tcc/(relocated build tree)/usr/lib/tcc/(system tcc install)
libruntime.a (PITH_RUNTIME):
$PITH_RUNTIME(if the file exists)./runtime/libruntime.a(cwd, the normal case)<prefix>/lib/pith/runtime/libruntime.a(installed layout)<root>/runtime/libruntime.a(build-tree layout)<root>/../runtime/libruntime.a(relocated build tree)