# Tooling — the compiler and everything around it The decision this page settles: **which command answers the question you have.** Every one of them is offline and version-matched to the compiler in front of you; none of them needs a network. The one-line commands live in [ref.md](/docs/reference#cli). This page is the model: what each tool reads, what it produces, and when it is the wrong tool. ## 1. The build commands ```bash cpc build # multi-file: reads ./Cplus.toml, walks imports cpc FILE.cplus -o BIN # single file, no imports, no manifest cpc check # whole project, front-end only, no codegen cpc check FILE # one file, front end + codegen (discarded) cpc test # #[test] discovery and run ``` The distinction that costs people the most time: **`cpc check FILE` does not read the manifest.** A file with any `import` fails there with E0852. Single-file mode is for import-free snippets; anything real goes through `cpc build` or project-mode `cpc check`. The other asymmetry is deliberate: project-mode `check` stops after borrowck, so it is the fast feedback loop; file-mode `check` also runs codegen and throws the IR away, so a codegen-stage *fault* — a panic in the emitter — is caught too. **What `check` cannot catch: invalid IR.** It never invokes clang, so IR that cpc emits but LLVM rejects passes `check` and fails only in a real build. That gap is not hypothetical — `==` on an array type-checked, emitted `icmp eq [2 x i32]`, and died in clang with no error code and no span in the user's file. When the question is "does this actually compile", build it; `check` answers "is the front end happy". Build flags, all of which apply to `cpc FILE`, `cpc build`, and `cpc test`: | Flag | Effect | |---|---| | `--release` | `-O3`, no overflow checks on `+ - *` | | `--debug` | `-O0` with overflow traps — the default | | `-g` / `--debug-info` | DWARF metadata, and `-g` to clang | | `--asan` / `--ubsan` / `--tsan` / `--msan` | LLVM sanitizers; asan/tsan/msan are mutually exclusive, ubsan composes | | `--target NAME` | cross-compile ([platforms.md](/docs/targets)) | | `--min-os VERSION` | override a versioned triple's OS floor; place *after* `--target` | | `--fp-contract=off\|on\|fast` | float contraction; `off` keeps `a*b+c` as fmul+fadd for bit-identical-to-C output | | `--warn-deps` | show dependency warnings too | | `--timings` | build cost to stderr, per phase and per package | | `--diagnostics=human\|short\|json` | diagnostic rendering | **`--warn-deps` is worth knowing about.** By default warnings are shown for your own `src/` only, which keeps a cold build of a large app readable — but it also means a vendored package's warnings are invisible until you ask. Errors are never suppressed. **`--timings`** answers "why is this slow" with data instead of a guess. It prints the phase table (resolve+sema+borrowck / codegen / prune / clang+link) and then a per-package roll-up. On this project the answer is usually clang. ## 2. The code graph — use it instead of grep C+ ships a resolved, typed code-knowledge graph. For *any* "where is X", "who calls X", "what is the type here" question, query the graph. It returns the answer already resolved, which removes both the grep pass and the reasoning you would spend disambiguating names and stitching call sites together. Across a large vendor tree, grep also misses generated code and produces false positives that read as real. Three front ends over one index: | Front end | Shape | Use when | |---|---|---| | `cpc graph` | whole graph as JSON on stdout | you want to process it yourself | | `cpc query …` | one answer as JSON, exit code signals found | a one-off from a shell | | `cpc mcp` | resident MCP server on stdio | an agent or editor asking repeatedly | `cpc query` kinds: ``` def SYMBOL members TYPE symbols [FILE] refs SYMBOL callers FN callees FN call-hierarchy FN [--depth N] context FN type-at FILE:LINE:COL value-refs FILE:LINE:COL scope-at FILE:LINE:COL complete FILE:LINE:COL ``` `complete` is the composed one. `scope-at`, `type-at` and `members` are the three primitives a caret question decomposes into, and deciding *which* of the three a caret is asking — after a `.`, after a `::`, or neither — is C+'s own rules, not the caller's policy. So that decision lives in the compiler and one verb answers it: ``` after a `.` the receiver's fields and methods (variants are `::`, not `.`) after a `::` the module an alias binds, or a type's methods and variants otherwise everything in scope ``` The answer names its own `context` (`member` / `path` / `scope`), the `prefix` it filtered on, and the ranked `items`. `receiver_type` absent on a member answer means the receiver's type is not locally known — an empty list, never a guess. Every `cpc query` invocation pays the whole-project graph build (~2s). An editor asking on a keystroke wants `cpc mcp`, which builds once and answers from memory. `cpc mcp` is the one to reach for from an agent. Beyond the read tools (`find_definition`, `find_references`, `find_callers`, `find_callees`, `call_hierarchy`, `find_members`, `file_symbols`, `code_context`, `type_at`, `scope_at`, `complete_at`) it is **live**: - `did_change` hands over an unsaved buffer; every later answer is about that text. The caret is always in a buffer that differs from disk, so for anything at the caret this is not a refinement, it is the whole question. - Rebuilds run on a worker. Reads never block — they answer from the newest finished graph. Pass `wait: true` on the call right before a question whose answer must reflect this exact text. - **A buffer that does not parse is normal**, not an error state: the last good graph keeps answering and `graph_status` carries the parse error. - `reload` rebuilds from disk after a branch switch, a generator run, or a dependency update — changes the server cannot see. - `graph_status` observes without rebuilding. Ask it before concluding an answer is wrong. `cpc lsp` starts the language server on stdin/stdout over the same index (it delegates to the `cpc-lsp` binary on PATH or next to `cpc`). It is resident on the same terms as `cpc mcp` — one graph per project root, built on the first graph-backed request and kept warm, with open buffers overlaid onto it and rebuilds on a worker — and it serves `textDocument/completion` from the same `complete` composition, so an editor and an agent get the same answer at the same caret. Trigger characters are `.` and `:`. `code_context` deserves its own note: it is the one-shot edit pack for a function — signature, callers, callees, and the types it touches. Prefer it over three separate lookups when you are about to change something. **`#[test]` functions and completion.** `scope-at` and `complete` answer "what can I type here", and a test function is never the answer — it takes no arguments, only the harness calls it, and in a suite-carrying module the tests outnumber the API. So both omit them. They stay everywhere else: `def`, `refs`, `callers`, and `callees` all find them, because a test calling a helper is a real call edge and hiding it would make `callers` lie. In `symbols` — the file outline, which should list tests — each one carries `is_test: true`, so a consumer using that list for completion can filter on the same rule. ## 3. Diagnostics ```bash cpc explain E0502 # cause, fix, worked example — offline cpc explain --list # every code ``` The diagnostics are the designed teaching surface of this language. When an error and your intuition disagree, `cpc explain` before you edit: it carries the *redesign* the message alone cannot. `--diagnostics=json` emits NDJSON, one object per diagnostic — the shape a CI annotator or an editor wants. `short` is one line per diagnostic. Warnings worth reading rather than silencing: | Code | Says | |---|---| | `W0002` | a `drop` frees a raw-pointer field only conditionally | | `W0005` | a `.cplus` file under `src/` is unreachable from the entry — it never compiles, so nothing it says is checked | | `W0006` | a `#[deprecated]` item is used here | | `W0824` / `W0825` | a callback parameter is declared without its `_ctx` slot, so callers can never pass a bound method | W0005 matters more than a warning usually does: unreachable code is false evidence. A reader — human or agent — takes it for the live API. ## 4. Source and docs ```bash cpc fmt FILE|DIR … # rewrite in place cpc fmt --check DIR # no write; exit non-zero on any diff cpc fmt --emit FILE # print to stdout, leave the file alone cpc fmt --stdin # read stdin, write stdout — the editor hook cpc doc FILE # public items + `///` docs -> target/doc/.md cpc headers # lib/include/ for the package in this directory ``` `cpc fmt` settles layout arguments. If a file does not round-trip through the formatter, the file is wrong; there is nothing to discuss. `cpc headers` turns `src/` into C+ *declaration* files under `lib/include/`: a concrete module becomes signatures (`fn f(...) -> T;`), and a module that declares generics is copied verbatim, because a generic has no object code until a consumer instantiates it. This is what lets a prebuilt package be consumed without its source. `cpc --emit-header FILE` is a different thing: a **C** header for every C-ABI-representable `export` item, for a C consumer. ## 5. Reading the language itself ```bash cpc skill # the whole language reference for an agent cpc skill --lang-only # …without dependencies' own SKILL.md files ``` `cpc skill` prints [skill.md](/docs/llms) embedded in the binary — version-matched, no network. Inside a project it also prints the SKILL.md of every dependency that ships one, which is usually what you want: the language plus the packages actually in this build. ## 6. Packages ```bash cpc init [--kind cli|gui] [--platform P]... [NAME] cpc pm install [DIR] # resolve deps into the store cpc pm update [DIR] # re-resolve and refresh cpc pm add DIR NAME [SPEC] # add a package and its declared closure cpc pm add DIR --maven G:A:V # add a third-party Maven/AAR pin cpc pm remove DIR NAME # delete DIR/vendor/NAME cpc pm manifest [DIR] # normalized JSON of a manifest cpc pm maven [WHAT] [DIR] # list | classpath | manifests | res | jni cpc pm maven price G:A:V # what a coordinate would cost ``` `cpc init` with no `--platform` scaffolds the zero-config host app. With `--platform` (repeatable) it scaffolds a deliberately **scoped** app: one `[] entry` per named platform, and building for one you did not name is E0413 rather than a guess. `--kind gui` scaffolds a facet app with the backend's full dependency closure already in the manifest; without `--kind`, the platform decides — `--platform ios` is `gui` and cannot be anything else, because iOS has no console for a printing entry to print to. `cpc pm add` is the one to prefer over hand-editing `[dependencies]`: it writes the package **and its declared closure**, mapping platform sections onto your project's target platforms. Dependency resolution is flat — the resolver validates every import against your one manifest and never reads a dependency's own — so a missing transitive line is an error in *your* manifest (E0852 / E0866), which is exactly the class of error `add` exists to prevent. Store flags: `--local` installs into `DIR/vendor/` instead of the per-user store; `--store DIR` overrides the store root (default `$CPLUS_HOME`, else `~/.cplus`); `--repo-url URL` pointed at a local path is the offline mode. **Android's Java side, without Gradle.** `cpc pm add . --maven com.google.android.gms:play-services-maps:19.0.0` pins the coordinate in `[android.maven]`, resolves the POM closure (parent chains, property interpolation, `dependencyManagement`, BOM imports) and downloads it into `~/.cplus/m2`, exploding each AAR. Nothing in the Android toolchain resolves dependencies — Gradle *is* the resolver — but resolution over pinned coordinates is reading XML, so `cpc pm` does it. A build then reads the result back, always offline: ```bash d8 --release --min-api 26 --lib "$AJ" --output out $(cpc pm maven classpath) ``` `manifests`, `res` and `jni` name the other three things an AAR carries; merging those is still the build script's job. Run `cpc pm maven price ` before taking a dependency — an AAR is priced per library, and the number is printable. ## 7. Introspection ```bash cpc --tokens FILE # the token stream cpc --ast FILE # the AST cpc --emit-ll FILE # cpc's own IR cpc --emit-ll-opt FILE # post-optimization IR (through clang) cpc --emit-asm FILE # native assembly cpc --emit-obj FILE -o OUT.o # relocatable object cpc --emit-ll-project # merged IR for the whole project cpc build --print-link-args # what the dependencies add to the link line cpc --realtime-report[=json] # whole-project real-time contract digest ``` Place `--target` and `--fp-contract` **before** an inline emit flag and its file. When chasing a suspected miscompile, the useful ladder is `--emit-ll` (is cpc's IR right?) → `--emit-ll-opt` (did an optimizer pass change the meaning?) → `--emit-asm`. Comparing `--release` against `--debug` at each rung localizes an optimization-level bug quickly. ## 8. Gotchas - **`cpc` on PATH may not be the one you are building.** In this repo, always run `./target/release/cpc` after `cargo build --release`; a package-manager-installed `cpc` will not have your changes and will fail in ways that look like language bugs. - **`cpc test` with no file reads `Cplus.toml`.** Package suites are run from the package directory (`cd vendor/ && cpc test`), not from the repo root. - **Warnings from dependencies are hidden by default** — `--warn-deps` when you are auditing rather than building. - **`cpc query` rebuilds the graph every time.** Repeated questions want `cpc mcp`. - **`cpc headers` reads `src/` only** and never `target/`, so a module that exists solely as a generated file in `target/` is not in the published surface.