Getting started (new repo)
This guide shows how to start a brand new Bosatsu repository using the bosatsu launcher script and a pinned CLI release. It assumes you have git and curl installed. For the CLI runtime, pick one of:
native(recommended on macOS/Linux)java(requires a JVM)node(requires Node.js)
1) Create a new git repo
mkdir my-bosatsu-project
cd my-bosatsu-project
git init
2) Add the bosatsu launcher
Download the launcher script and make it executable:
curl -L -o bosatsu https://raw.githubusercontent.com/johnynek/bosatsu/main/bosatsu
chmod +x bosatsu
3) Find the latest release version
Open the latest release page and note the version:
https://github.com/johnynek/bosatsu/releases/latest/
Example of a direct asset URL from a release:
https://github.com/johnynek/bosatsu/releases/download/v0.0.25/bosatsu
(The exact asset filename varies by platform; the launcher handles this for you.)
4) Pin the Bosatsu release version
Create .bosatsu_version with the latest Bosatsu release tag (without the leading v). For example, if the latest release is v0.0.25, write 0.0.25:
echo '0.0.25' > .bosatsu_version
5) Choose a platform (per-machine)
Create .bosatsu_platform with one of native, java, or node. Start with native on macOS/Linux.
echo 'native' > .bosatsu_platform
If you are on Windows, use java or node instead of native.
6) Ignore per-machine/cache files
You generally want .bosatsu_platform to be per-machine, and the download cache should stay out of git. Add both to .gitignore:
cat >> .gitignore <<'EOF'
.bosatsu_platform
.bosatsuc/
EOF
Commit .bosatsu_version so everyone uses the same CLI release.
7) Fetch the CLI
Download the release artifact for your platform:
./bosatsu --fetch
This will download into .bosatsuc/cli/<version>/ based on the value in .bosatsu_version and your chosen platform.
8) Install the C runtime
./bosatsu c-runtime install
The runtime install picks up your compiler toolchain and flags from standard variables:
CCCFLAGSCPPFLAGSLDFLAGSLIBS
On Linux/macOS, Boehm GC flags are discovered with pkg-config bdw-gc when available, with common-path fallbacks.
Use --profile debug for debug-friendly runtime builds (release is the default profile):
./bosatsu c-runtime install --profile debug
9) Initialize a library config
Pick a source root for your Bosatsu packages (e.g. src) and initialize the library config:
mkdir -p src
./bosatsu init \
--name mylib \
--repo_uri <your repo URL> \
--src_root src \
--version 0.1.0
Notes:
initsearches for a.gitentry to find the repo root. This works for standard checkouts and git worktrees. If you need to override that, add--repo_root <path>.- It writes
bosatsu_libs.jsonin the repo root andsrc/mylib_conf.jsonin the source root you selected.
10) Add code
Put your .bosatsu files under src/. For example, create src/MyLib/Hello.bosatsu with a type, a function, and a test:
package MyLib/Hello
enum Mood: Happy, Sad
def greet(m: Mood) -> String:
match m:
case Happy: "hello"
case Sad: "cheer up"
test = Assertion(greet(Happy) matches "hello", "greet Happy")
Use ./bosatsu --help to explore the available commands. The default repo and library workflows now live at the top level, for example: ./bosatsu check, ./bosatsu test, and ./bosatsu eval. Use ./bosatsu tool ... for the lower-level file-based compiler commands such as ./bosatsu tool transpile.
Read package headers for a build
tool headers reads explicit source files using the Bosatsu header parser. It can scan sources whose imports have not been built yet. A body can still be under edit when you run it.
./bosatsu tool headers --src src/Api.bosatsu --src src/Types.bosatsu --out gen/headers.json
The JSON object has schema_version: 1 and a packages array ordered by source path. Each entry records the path, declared package name, imports and explicit exposures. For example, from Demo/Types import Token as Item produces this entry.
{"package":"Demo/Types","names":[{"original":"Token","local":"Item"}]}
Paths supplied relative to the working directory stay relative. Reordering --src arguments or changing only a body preserves the output bytes. A scan reports missing files and header parse errors with their paths and exits with a failure status. On the JVM a failed scan preserves an existing index.
On local rebuilds the JVM file commands follow output symlinks, including a link whose target will be created by the first build. A readable artifact keeps its timestamp when the generated bytes match. Before replacing a file, the runner checks its access controls. It reports an error for a POSIX policy it cannot reproduce, such as an extended macOS ACL or a Linux security label. It can replace a write-only artifact and restore it if publishing a later output fails.
Compile a package group
Build a group in one invocation. Pass its signature to a downstream group.
./bosatsu tool compile-packages --src src/Types.bosatsu --src src/Api.bosatsu \
--packages-out gen/api.bosatsu_package --sig-out gen/api.bosatsig
./bosatsu tool compile-packages --src app/Main.bosatsu \
--direct-interface gen/api.bosatsig \
--error-unused-interfaces \
--packages-out gen/main.bosatsu_package --sig-out gen/main.bosatsig
Both outputs are required. The implementation contains just the listed packages, including their private test entries. The compiler supplies Predef implicitly. Use a --direct-interface for each provider required by imports and their public exposures. A multi-package signature can contain other roots whose dependencies are unavailable. The compiler decodes only the roots this group needs. A private body or opaque field edit can change the implementation while preserving the signature bytes.
--error-unused-interfaces fails if a declared signature supplies none of the packages the group needs. For example, if the API exposes a type from a second provider, pass both signatures. A provider used only inside the API’s implementation can be omitted. Build tools can add --interface-labels FILE to include target labels in missing, ambiguous and unused dependency errors.
Emit C for tests from compiled groups
To run tests defined inside a compiled group, list the group and its reachable implementation bundles in a runtime manifest. For a group using only Predef’s native bindings, gen/runtime.json can contain the following JSON.
{
"schema_version": 1,
"kind": "local",
"packages": ["gen/api.bosatsu_package", "gen/main.bosatsu_package"],
"externals": []
}
./bosatsu tool emit-c --runtime-manifest gen/runtime.json \
--test-packages gen/main.bosatsu_package --out gen/test_runner.c
Paths are relative to the working directory. The test runner includes the suites in the selected file and can use helpers from any listed dependency. Emission fails if the selected group contains no tests. Compile and link the C file with the matching Bosatsu runtime and any native dependencies. The compiler does not need a local C runtime installation to emit C.
11) Run tests
From the repo root:
./bosatsu test
To override compile/link flags for a single invocation, use repeatable flags:
./bosatsu test --cc_flag=-O0 --cc_lib=-lm
./bosatsu build --main_pack MyLib/Hello --exe_out app --cc_flag=-O0