Skip to content

build.md

Latest commit

 

History

History
217 lines (163 loc) · 8.44 KB

build.md

File metadata and controls

217 lines (163 loc) · 8.44 KB
Raw
description Toolchain and editor setup, the repository layout, and how to build every package — and the documentation site — in the monorepo.

Build & Setup

VS Code setup

Open bxp.code-workspace rather than the plain folder: it carries the recommended-extension list, and VS Code offers to install the whole set on first open (Extensions → Recommended, or Show Recommended Extensions from the command palette).

--8<-- "includes/vscode-extensions.md:table"

That table is not retyped here — it is generated from the same bxp.code-workspace list the editor reads, each row's purpose being the comment above the entry. Adding an extension for yourself and adding it to this page are one action.

ZLS (Zig Language Server) comes with ziglang.vscode-zig — the extension fetches a ZLS matching your Zig toolchain, giving completions, go-to-definition and inline diagnostics with nothing else to install.

The Dart and Flutter extensions matter only if you touch bxp-gui; the desktop side has its own prerequisites and first-run walkthrough in GUI setup.

!!! note "The workspace opens a second folder"

`bxp.code-workspace` also lists `../DEV`, a scratch folder that is not part
of this repository. VS Code shows it greyed out if you do not have one —
harmless, and removable from **File → Remove Folder from Workspace**.

Verify Zig language version

The required Zig version is pinned in build.zig.zon (minimum_zig_version), and CI installs exactly that version — .github/workflows/ci.yml is the second place to look if you want to see the pin in use. Install that toolchain from ziglang.org/download, or with a version manager such as zigup if you keep several around; the ZLS the Zig extension fetches follows whichever zig is on your PATH.

bxp-core has two external (fetch) dependencies — uucode (MIT), the Unicode case-mapping tables behind UPPER/LOWER, and zig_libs (MIT), supplying the whole primitive layer: the datefmt date core, the tz IANA offset lookup, the encoding code-page transcoder, the json5 preprocessor, the decimal fixed-point numeric core, the numparse grouped- number parser, the zipstream ZIP reader, the csvstream CSV reader, the diagnostics collector and the regex engine behind REGEX_MATCH/REGEX_EXTRACT (linear-time, ReDoS-safe), plus minisign and procrun (re-exported for bxp-gui-bridge) and mcp (the JSON-RPC transport re-exported for bxp-mcp). All are pinned in bxp-core/build.zig.zon. The fetches are cached after the first build; CI runners have network.

In VS Code terminal:

zig version   # must satisfy build.zig.zon's minimum_zig_version

Claude Code setup

BXP development in Zig works with Claude Code, locally. What the repository commits for it:

  • CLAUDE.md files — the root one plus one per package (bxp-cli/, bxp-core/, bxp-mcp/, bxp-gui/, bxp-gui-bridge/, bxp-gui/packages/json5_ast/) and docs/examples/. Claude loads them automatically; the root file's Project rules section is the one to read first.
  • .claude/rules/zig-pitfalls.md — Zig lessons specific to this repository (helpers to use, false-green checks, no zig fmt).
  • .claude/skills/zig-0.17/ — the zig-0.17 API-reference skill for the Zig version in .zigversion, vendored from an audited release of zaxified/zig-skills. Claude loads it before writing or reviewing Zig code. Never edit these files: the zig-skill workflow fails on any difference from the release named in .claude/skills/zig-0.17/.zig-skills-source.json. To move to a newer release, run that repository's scripts/install.py from the new tag and commit the result.

Everything else under .claude/ (settings, local permissions) stays on your machine and is ignored by git.

Repository layout

Generated by walking the repository, with each entry's note read from the file's own header — a //! line in Zig, the comment under a script's shebang, the description: front matter of a Markdown page. Directories are described in the generator's own catalog. Nothing here is retyped, so a new file arrives on this page with the commit that adds it.

--8<-- "includes/repo-tree.md:tree"

Clone and build

# Clone this repository
git clone https://github.com/zaxified/bxp.git

# Build bxp-cli (fetches dependencies on first run)
cd ./bxp/bxp-cli
zig build

# Run
./zig-out/bin/bxp-cli --help

Running bxp-cli without arguments processes every template defined in bxp-cli.json in the current working directory.
The typical dev workflow:

# From the monorepo root
./bxp-cli/zig-out/bin/bxp-cli --config ./datasets/anycoin_to_wealthfolio/sample.json --debug

Build the documentation site

The site you are reading is MkDocs Material, driven by one script:

# Regenerate every generated page + fragment, build, and serve on :8000
bash scripts/docs/gen-docs.sh

bash scripts/docs/gen-docs.sh --build   # regenerate + build into site/, no serve
bash scripts/docs/gen-docs.sh --check   # drift guard: fail if a generated page
                                        # differs from a fresh generation

The Python toolchain lives in a local venv the script expects to find, and is pinned in scripts/docs/requirements.txt — the same file the Pages workflow installs from, so a page that builds on a laptop builds on the runner:

python3 -m venv .venv-docs
.venv-docs/bin/pip install -r scripts/docs/requirements.txt

The social plugin renders the Open Graph preview cards through Cairo, so cairosvg and pillow in that file are not optional extras — and on Linux they need system libraries the venv cannot supply:

sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev \
    libjpeg-dev libpng-dev

That is the same list .github/workflows/docs.yml installs. Without them mkdocs build --strict fails inside the plugin rather than on your page.

Two things to know before editing:

  • Regenerating needs a working Zig and Flutter toolchain. The reference pages come out of tools/zig-doc-gen, and four GUI pages out of tools/dart-doc-gen, which runs as a flutter test. Editing hand-written prose does not need either — building the whole site does.
  • --check is a CI gate, not a test phase. .github/workflows/docs.yml runs the drift check, the wasm/native parity check and a --strict build; scripts/test.sh deliberately does not. See the note in Testing for why.

Markdown formatting is hand-maintained (prettier and markdownlint reflow MkDocs-specific syntax and break the rendered pages). bash scripts/docs/check-formatting.sh parses the Mermaid fences and is run before a release rather than on every commit.

The wasm playground target

bxp-core also builds for wasm32-freestanding, which is what powers the clickable expressions on the docs site — the reader's browser runs bxp's own evaluator rather than a JavaScript re-implementation. It is an opt-in target, never part of install:

cd bxp-core && zig build wasm -Dtarget=wasm32-freestanding -Doptimize=ReleaseSmall

In practice you do not run that by hand: scripts/docs/gen-wasm-playground.sh builds it into docs/assets/wasm/bxp-eval.wasm, and scripts/docs/gen-docs.sh calls that script for you. The .wasm is a build artifact and stays untracked — a checkout regenerates it, and a docs build without it leaves the panel reporting that it could not load the engine.

Agreement with the native engine is measured rather than assumed: scripts/docs/check-wasm-parity.sh runs the cross-runner expression corpus through both and requires byte-identical results. It needs a JS runtime, so it is a docs-workflow step rather than a test-NN phase.

Run the test suite

# From the monorepo root — runs unit tests + all regression tests
bash scripts/test.sh

Nine phases covering the bxp-core unit tests and the CLI build, the MCP server, the bridge, the Flutter desktop app, a coarse perf guard, the expression corpus, and three regression gates — datasets, the expressions printed on the example pages, and the examples' committed output. Testing has the full breakdown (generated from the phase scripts' own headers, so it counts itself), the individual sub-suite commands, and how to add a regression.