john/cell
1
0
Fork 0
Code Issues 31 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

fix cell toml and add documentation for tools

Browse Source
This commit is contained in:
John Alanbrook
2026-02-17 02:36:53 -06:00
parent fbdfbc1200
commit 08515389d2
3 changed files with 409 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
cell.toml
View File

@@ -1,8 +1,2 @@
[dependencies]
cell-steam = "/Users/johnalanbrook/work/cell-steam"
cell-image = "/Users/johnalanbrook/work/cell-image"
cell-sdl3 = "/Users/johnalanbrook/work/cell-sdl3"
[compilation]
[compilation]
[compilation.playdate]
CFLAGS = "-DMINIZ_NO_TIME -DTARGET_EXTENSION -DTARGET_PLAYDATE -I$LOCAL/PlaydateSDK/C_API"
CFLAGS = "-DMINIZ_NO_TIME -DTARGET_EXTENSION -DTARGET_PLAYDATE -I$LOCAL/PlaydateSDK/C_API"

100
docs/c-modules.md
View File

@@ -228,11 +228,105 @@ var d = vector.dot(1, 0, 0, 1) // 0
C files are automatically compiled when you run:
```bash
pit build
pit update
cell --dev build
```
Each C file is compiled into a per-file dynamic library at `~/.pit/lib/<pkg>/<stem>.dylib`.
Each C file is compiled into a per-file dynamic library at `.cell/lib/<pkg>/<stem>.dylib`.
## Compilation Flags (cell.toml)
Use the `[compilation]` section in `cell.toml` to pass compiler and linker flags:
```toml
[compilation]
CFLAGS = "-Isrc -Ivendor/include"
LDFLAGS = "-lz -lm"
```
### Include paths
Relative `-I` paths are resolved from the package root:
```toml
CFLAGS = "-Isdk/public"
```
If your package is at `/path/to/mypkg`, this becomes `-I/path/to/mypkg/sdk/public`.
Absolute paths are passed through unchanged.
### Library paths
Relative `-L` paths work the same way:
```toml
LDFLAGS = "-Lsdk/lib -lmylib"
```
### Target-specific flags
Add sections named `[compilation.<target>]` for platform-specific flags:
```toml
[compilation]
CFLAGS = "-Isdk/public"
[compilation.macos_arm64]
LDFLAGS = "-Lsdk/lib/osx -lmylib"
[compilation.linux]
LDFLAGS = "-Lsdk/lib/linux64 -lmylib"
[compilation.windows]
LDFLAGS = "-Lsdk/lib/win64 -lmylib64"
```
Available targets: `macos_arm64`, `macos_x86_64`, `linux`, `linux_arm64`, `windows`.
### Sigils
Use `$LOCAL` in flags to refer to the `.cell/local` directory (for prebuilt libraries):
```toml
LDFLAGS = "-L$LOCAL -lmyprebuilt"
```
### Example: vendored SDK
A package wrapping an external SDK with platform-specific shared libraries:
```
mypkg/
├── cell.toml
├── wrapper.cpp
└── sdk/
├── public/
│ └── mylib/
│ └── api.h
└── lib/
├── osx/
│ └── libmylib.dylib
└── linux64/
└── libmylib.so
```
```toml
[compilation]
CFLAGS = "-Isdk/public"
[compilation.macos_arm64]
LDFLAGS = "-Lsdk/lib/osx -lmylib"
[compilation.linux]
LDFLAGS = "-Lsdk/lib/linux64 -lmylib"
```
```cpp
// wrapper.cpp
#include "cell.h"
#include <mylib/api.h>
// ...
```
## Platform-Specific Code

438
docs/cli.md
View File

@@ -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