7.2 KiB
title, description, weight, type
| title | description | weight | type |
|---|---|---|---|
| Command Line Interface | The pit tool | 40 | docs |
ƿit provides a command-line interface for managing packages, running scripts, and building applications.
Basic Usage
pit <command> [arguments]
Commands
pit version
Display the ƿit version.
pit version
# 0.1.0
pit install
Install a package to the shop.
pit install gitea.pockle.world/john/prosperon
pit install /Users/john/local/mypackage # local path
pit update
Update packages from remote sources.
pit update # update all packages
pit update <package> # update specific package
pit remove
Remove a package from the shop. Removes the lock entry, the package directory (or symlink), and any built dylibs.
pit remove gitea.pockle.world/john/oldpackage
pit remove /Users/john/work/mylib # local path
pit remove . # current directory
pit remove mypackage --dry-run # show what would be removed
pit remove mypackage --prune # also remove orphaned dependencies
Options:
--prune— also remove packages that are no longer needed by any remaining root--dry-run— show what would be removed without removing anything
pit list
List installed packages.
pit list # list all installed packages
pit list <package> # list dependencies of a package
pit ls
List modules and actors in a package.
pit ls # list files in current project
pit ls <package> # list files in specified package
pit build
Build C modules for a package. Compiles each C file into a per-file dynamic library and installs them to ~/.pit/lib/<pkg>/<stem>.dylib. C files in src/ directories are compiled as support objects and linked into the module dylibs.
pit build # build all packages
pit build <package> # build specific package
pit build /Users/john/work/mylib # build local package
pit build . # build current directory
pit build -t macos_arm64 # cross-compile for target
pit build -b debug # build type: release (default), debug, minsize
pit build --list-targets # list available targets
pit build --force # force rebuild
pit build --dry-run # show what would be built
pit test
Run tests. See Testing for the full guide.
pit test # run tests in current package
pit test suite # run specific test file
pit test all # run all tests in current package
pit test package <name> # run tests in a named package
pit test package /Users/john/work/mylib # run tests for a local package
pit test package all # run tests from all packages
pit test suite --verify --diff # with IR verification and differential testing
pit link
Manage local package links for development.
pit link add <canonical> <local_path> # link a package
pit link list # show all links
pit link delete <canonical> # remove a link
pit link clear # remove all links
pit fetch
Fetch package sources without extracting.
pit fetch <package>
pit upgrade
Upgrade the ƿit installation itself.
pit upgrade
pit clean
Clean build artifacts.
pit clean
pit add
Add a dependency to the current package. Installs the package to the shop, builds any C modules, and updates cell.toml.
pit add gitea.pockle.world/john/prosperon # remote, default alias
pit add gitea.pockle.world/john/prosperon myalias # remote, custom alias
pit add /Users/john/work/mylib # local path (symlinked)
pit add . # current directory
pit add ../sibling-package # relative path
For local paths, the package is symlinked into the shop rather than copied. Changes to the source directory are immediately visible.
pit clone
Clone a package to a local path and link it for development.
pit clone gitea.pockle.world/john/prosperon ./prosperon
pit unlink
Remove a link created by pit link or pit clone and restore the original package.
pit unlink gitea.pockle.world/john/prosperon
pit search
Search for packages, actors, or modules matching a query.
pit search math
pit why
Show which installed packages depend on a given package (reverse dependency lookup).
pit why gitea.pockle.world/john/prosperon
pit resolve
Print the fully resolved dependency closure for a package.
pit resolve # resolve current package
pit resolve <package> # resolve specific package
pit resolve --locked # show lock state without links
pit graph
Emit a dependency graph.
pit graph # tree of current package
pit graph --format dot # graphviz dot output
pit graph --format json # json output
pit graph --world # graph all installed packages
pit graph --locked # show lock view without links
pit verify
Verify integrity and consistency of packages, links, and builds.
pit verify # verify current package
pit verify shop # verify entire shop
pit verify --deep # traverse full dependency closure
pit verify --target <triple>
pit pack
Build a statically linked binary from a package and all its dependencies.
pit pack <package> # build static binary (output: app)
pit pack <package> -o myapp # specify output name
pit pack <package> -t <triple> # cross-compile for target
pit config
Manage system and actor configuration values in cell.toml.
pit config list # list all config
pit config get system.ar_timer # get a value
pit config set system.ar_timer 5.0 # set a value
pit config actor <name> list # list actor config
pit config actor <name> get <key> # get actor config
pit config actor <name> set <key> <val> # set actor config
pit help
Display help information.
pit help
pit help <command>
Package Locators
Packages are identified by locators:
- Remote:
gitea.pockle.world/user/repo - Local:
/absolute/path/to/package
pit install gitea.pockle.world/john/prosperon
pit install /Users/john/work/mylib
Configuration
ƿit stores its data in ~/.pit/:
~/.pit/
├── packages/ # installed package sources
├── lib/ # installed per-file dylibs and mach (persistent)
│ ├── core/ # core package: .dylib and .mach files
│ └── <pkg>/ # per-package subdirectories
├── build/ # ephemeral build cache (safe to delete)
├── cache/ # downloaded archives
├── lock.toml # installed package versions
└── link.toml # local development links
Environment
ƿit reads the HOME environment variable to locate the shop directory.
Exit Codes
0— Success- Non-zero — Error (check output for details)