fix cell toml and add documentation for tools
This commit is contained in:
438
docs/cli.md
438
docs/cli.md
@@ -13,7 +13,7 @@ type: "docs"
|
||||
pit <command> [arguments]
|
||||
```
|
||||
|
||||
## Commands
|
||||
## General
|
||||
|
||||
### pit version
|
||||
|
||||
@@ -24,57 +24,32 @@ pit version
|
||||
# 0.1.0
|
||||
```
|
||||
|
||||
### pit install
|
||||
### pit help
|
||||
|
||||
Install a package to the shop.
|
||||
Display help information.
|
||||
|
||||
```bash
|
||||
pit install gitea.pockle.world/john/prosperon
|
||||
pit install /Users/john/local/mypackage # local path
|
||||
pit help
|
||||
pit help <command>
|
||||
```
|
||||
|
||||
### pit update
|
||||
## Package Commands
|
||||
|
||||
Update packages from remote sources.
|
||||
These commands operate on a package's `cell.toml`, source files, or build artifacts.
|
||||
|
||||
### pit add
|
||||
|
||||
Add a dependency to the current package. Installs the package to the shop, builds any C modules, and updates `cell.toml`.
|
||||
|
||||
```bash
|
||||
pit update # update all packages
|
||||
pit update <package> # update specific package
|
||||
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
|
||||
```
|
||||
|
||||
### pit remove
|
||||
|
||||
Remove a package from the shop. Removes the lock entry, the package directory (or symlink), and any built dylibs.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
pit list # list all installed packages
|
||||
pit list <package> # list dependencies of a package
|
||||
```
|
||||
|
||||
### pit ls
|
||||
|
||||
List modules and actors in a package.
|
||||
|
||||
```bash
|
||||
pit ls # list files in current project
|
||||
pit ls <package> # list files in specified package
|
||||
```
|
||||
For local paths, the package is symlinked into the shop rather than copied. Changes to the source directory are immediately visible.
|
||||
|
||||
### pit build
|
||||
|
||||
@@ -106,85 +81,23 @@ pit test package all # run tests from all packages
|
||||
pit test suite --verify --diff # with IR verification and differential testing
|
||||
```
|
||||
|
||||
### pit link
|
||||
### pit ls
|
||||
|
||||
Manage local package links for development.
|
||||
List modules and actors in a package.
|
||||
|
||||
```bash
|
||||
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 ls # list files in current project
|
||||
pit ls <package> # list files in specified package
|
||||
```
|
||||
|
||||
### pit fetch
|
||||
### pit audit
|
||||
|
||||
Fetch package sources without extracting.
|
||||
Test-compile all `.ce` and `.cm` scripts in package(s). Continues past failures and reports all errors at the end.
|
||||
|
||||
```bash
|
||||
pit fetch <package>
|
||||
```
|
||||
|
||||
### pit upgrade
|
||||
|
||||
Upgrade the ƿit installation itself.
|
||||
|
||||
```bash
|
||||
pit upgrade
|
||||
```
|
||||
|
||||
### pit clean
|
||||
|
||||
Clean build artifacts.
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
pit unlink gitea.pockle.world/john/prosperon
|
||||
```
|
||||
|
||||
### pit search
|
||||
|
||||
Search for packages, actors, or modules matching a query.
|
||||
|
||||
```bash
|
||||
pit search math
|
||||
```
|
||||
|
||||
### pit why
|
||||
|
||||
Show which installed packages depend on a given package (reverse dependency lookup).
|
||||
|
||||
```bash
|
||||
pit why gitea.pockle.world/john/prosperon
|
||||
pit audit # audit all installed packages
|
||||
pit audit <package> # audit specific package
|
||||
pit audit . # audit current directory
|
||||
```
|
||||
|
||||
### pit resolve
|
||||
@@ -220,16 +133,6 @@ pit verify --deep # traverse full dependency closure
|
||||
pit verify --target <triple>
|
||||
```
|
||||
|
||||
### pit audit
|
||||
|
||||
Test-compile all `.ce` and `.cm` scripts in package(s). Continues past failures and reports all errors at the end.
|
||||
|
||||
```bash
|
||||
pit audit # audit all installed packages
|
||||
pit audit <package> # audit specific package
|
||||
pit audit . # audit current directory
|
||||
```
|
||||
|
||||
### pit pack
|
||||
|
||||
Build a statically linked binary from a package and all its dependencies.
|
||||
@@ -253,13 +156,294 @@ pit config actor <name> get <key> # get actor config
|
||||
pit config actor <name> set <key> <val> # set actor config
|
||||
```
|
||||
|
||||
### pit help
|
||||
### pit bench
|
||||
|
||||
Display help information.
|
||||
Run benchmarks with statistical analysis. Benchmark files are `.cm` modules in a package's `benches/` directory.
|
||||
|
||||
```bash
|
||||
pit help
|
||||
pit help <command>
|
||||
pit bench # run all benchmarks in current package
|
||||
pit bench all # same as above
|
||||
pit bench <suite> # run specific benchmark file
|
||||
pit bench package <name> # benchmark a named package
|
||||
pit bench package <name> <suite> # specific benchmark in a package
|
||||
pit bench package all # benchmark all packages
|
||||
```
|
||||
|
||||
Output includes median, mean, standard deviation, and percentiles for each benchmark.
|
||||
|
||||
## Shop Commands
|
||||
|
||||
These commands operate on the global shop (`~/.pit/`) or system-level state.
|
||||
|
||||
### pit install
|
||||
|
||||
Install a package to the shop.
|
||||
|
||||
```bash
|
||||
pit install gitea.pockle.world/john/prosperon
|
||||
pit install /Users/john/local/mypackage # local path
|
||||
```
|
||||
|
||||
### pit remove
|
||||
|
||||
Remove a package from the shop. Removes the lock entry, the package directory (or symlink), and any built dylibs.
|
||||
|
||||
```bash
|
||||
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 update
|
||||
|
||||
Update packages from remote sources.
|
||||
|
||||
```bash
|
||||
pit update # update all packages
|
||||
pit update <package> # update specific package
|
||||
```
|
||||
|
||||
### pit list
|
||||
|
||||
List installed packages.
|
||||
|
||||
```bash
|
||||
pit list # list all installed packages
|
||||
pit list <package> # list dependencies of a package
|
||||
```
|
||||
|
||||
### pit link
|
||||
|
||||
Manage local package links for development.
|
||||
|
||||
```bash
|
||||
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 unlink
|
||||
|
||||
Remove a link created by `pit link` or `pit clone` and restore the original package.
|
||||
|
||||
```bash
|
||||
pit unlink gitea.pockle.world/john/prosperon
|
||||
```
|
||||
|
||||
### pit clone
|
||||
|
||||
Clone a package to a local path and link it for development.
|
||||
|
||||
```bash
|
||||
pit clone gitea.pockle.world/john/prosperon ./prosperon
|
||||
```
|
||||
|
||||
### pit fetch
|
||||
|
||||
Fetch package sources without extracting.
|
||||
|
||||
```bash
|
||||
pit fetch <package>
|
||||
```
|
||||
|
||||
### pit search
|
||||
|
||||
Search for packages, actors, or modules matching a query.
|
||||
|
||||
```bash
|
||||
pit search math
|
||||
```
|
||||
|
||||
### pit why
|
||||
|
||||
Show which installed packages depend on a given package (reverse dependency lookup).
|
||||
|
||||
```bash
|
||||
pit why gitea.pockle.world/john/prosperon
|
||||
```
|
||||
|
||||
### pit upgrade
|
||||
|
||||
Upgrade the ƿit installation itself.
|
||||
|
||||
```bash
|
||||
pit upgrade
|
||||
```
|
||||
|
||||
### pit clean
|
||||
|
||||
Clean build artifacts.
|
||||
|
||||
```bash
|
||||
pit clean
|
||||
```
|
||||
|
||||
## Developer Commands
|
||||
|
||||
Compiler pipeline tools, analysis, and testing. These are primarily useful for developing the ƿit compiler and runtime.
|
||||
|
||||
### Compiler Pipeline
|
||||
|
||||
Each of these commands runs the compilation pipeline up to a specific stage and prints the intermediate output. They take a source file as input.
|
||||
|
||||
### pit tokenize
|
||||
|
||||
Tokenize a source file and output the token stream as JSON.
|
||||
|
||||
```bash
|
||||
pit tokenize <file.cm>
|
||||
```
|
||||
|
||||
### pit parse
|
||||
|
||||
Parse a source file and output the AST as JSON.
|
||||
|
||||
```bash
|
||||
pit parse <file.cm>
|
||||
```
|
||||
|
||||
### pit fold
|
||||
|
||||
Run constant folding and semantic analysis on a source file and output the simplified AST as JSON.
|
||||
|
||||
```bash
|
||||
pit fold <file.cm>
|
||||
```
|
||||
|
||||
### pit mcode
|
||||
|
||||
Compile a source file to mcode (machine-independent intermediate representation) and output as JSON.
|
||||
|
||||
```bash
|
||||
pit mcode <file.cm>
|
||||
```
|
||||
|
||||
### pit streamline
|
||||
|
||||
Apply the full optimization pipeline to a source file and output optimized mcode as JSON.
|
||||
|
||||
```bash
|
||||
pit streamline <file.cm>
|
||||
```
|
||||
|
||||
### pit qbe
|
||||
|
||||
Compile a source file to QBE intermediate language (for native code generation).
|
||||
|
||||
```bash
|
||||
pit qbe <file.cm>
|
||||
```
|
||||
|
||||
### pit compile
|
||||
|
||||
Compile a source file to a native dynamic library.
|
||||
|
||||
```bash
|
||||
pit compile <file.cm> # outputs .dylib to .cell/lib/
|
||||
pit compile <file.ce>
|
||||
```
|
||||
|
||||
### pit run_native
|
||||
|
||||
Compile a module natively and compare execution against interpreted mode, showing timing differences.
|
||||
|
||||
```bash
|
||||
pit run_native <module> # compare interpreted vs native
|
||||
pit run_native <module> <test_arg> # pass argument to module function
|
||||
```
|
||||
|
||||
### pit run_aot
|
||||
|
||||
Ahead-of-time compile and execute a program natively.
|
||||
|
||||
```bash
|
||||
pit run_aot <program.ce>
|
||||
```
|
||||
|
||||
### Analysis
|
||||
|
||||
### pit explain
|
||||
|
||||
Query the semantic index for symbol information at a specific source location or by name.
|
||||
|
||||
```bash
|
||||
pit explain --span <file:line:col> # find symbol at position
|
||||
pit explain --symbol <name> [files...] # find symbol by name
|
||||
pit explain --help # show usage
|
||||
```
|
||||
|
||||
### pit index
|
||||
|
||||
Build a semantic index for a source file and output symbol information as JSON.
|
||||
|
||||
```bash
|
||||
pit index <file.cm> # output to stdout
|
||||
pit index <file.cm> -o index.json # output to file
|
||||
pit index --help # show usage
|
||||
```
|
||||
|
||||
### pit ir_report
|
||||
|
||||
Optimizer flight recorder — capture detailed information about IR transformations during optimization.
|
||||
|
||||
```bash
|
||||
pit ir_report <file.cm> # per-pass JSON summaries (default)
|
||||
pit ir_report <file.cm> --events # include rewrite events
|
||||
pit ir_report <file.cm> --types # include type deltas
|
||||
pit ir_report <file.cm> --ir-before=PASS # print IR before specific pass
|
||||
pit ir_report <file.cm> --ir-after=PASS # print IR after specific pass
|
||||
pit ir_report <file.cm> --ir-all # print IR before/after every pass
|
||||
pit ir_report <file.cm> --full # all options combined
|
||||
```
|
||||
|
||||
Output is NDJSON (newline-delimited JSON).
|
||||
|
||||
### Testing
|
||||
|
||||
### pit diff
|
||||
|
||||
Differential testing — run tests with and without optimizations and compare results.
|
||||
|
||||
```bash
|
||||
pit diff # diff all test files in current package
|
||||
pit diff <suite> # diff specific test file
|
||||
pit diff tests/<path> # diff by path
|
||||
```
|
||||
|
||||
### pit fuzz
|
||||
|
||||
Random program fuzzer — generates random programs and checks for optimization correctness by comparing optimized vs unoptimized execution.
|
||||
|
||||
```bash
|
||||
pit fuzz # 100 iterations with random seed
|
||||
pit fuzz <iterations> # specific number of iterations
|
||||
pit fuzz --seed <N> # start at specific seed
|
||||
pit fuzz <iterations> --seed <N>
|
||||
```
|
||||
|
||||
Failures are saved to `tests/fuzz_failures/`.
|
||||
|
||||
### pit vm_suite
|
||||
|
||||
Run the VM stability test suite (641 tests covering arithmetic, strings, control flow, closures, objects, and more).
|
||||
|
||||
```bash
|
||||
pit vm_suite
|
||||
```
|
||||
|
||||
### pit syntax_suite
|
||||
|
||||
Run the syntax feature test suite (covers all literal types, operators, control flow, functions, prototypes, and more).
|
||||
|
||||
```bash
|
||||
pit syntax_suite
|
||||
```
|
||||
|
||||
## Package Locators
|
||||
|
||||
Reference in New Issue
Block a user