# Tooling: `cpc`

`cpc` is the single command for building, checking, formatting, testing, and querying C+ code.

```bash
cpc build                      # multi-file project (reads Cplus.toml)
cpc FILE.cplus -o BIN          # single-file build
cpc check FILE                 # parse + sema only, fast feedback (single file)
cpc check                      # whole-project front-end check (reads Cplus.toml,
                               #   enforces [profile.realtime]); no codegen, the CI gate
cpc --realtime-report[=json]   # whole-project real-time contract digest
cpc fmt FILE                   # canonical format in place
cpc fmt --check DIR            # CI mode, exits 1 on drift
cpc test                       # run #[test] functions + doctests
cpc doc                        # generate Markdown documentation from public items
cpc lsp                        # language server: diagnostics, formatting, code-actions, navigation
cpc --emit-ll FILE             # pre-optimisation LLVM IR
cpc --emit-ll-opt FILE         # post-optimisation LLVM IR
cpc --emit-asm FILE            # native assembly
cpc --diagnostics=json         # machine-readable diagnostics
cpc --release                  # -O2 (default is debug -O0 with overflow traps)
cpc -V                         # print version
```

## Build versus check

`cpc build` compiles a project (reading `Cplus.toml`) or, in the `FILE.cplus -o BIN` form, a single file. `cpc check` runs only the front-end (lex, parse, sema, borrowck) and stops before codegen, which makes it the fast feedback loop and the CI gate. With no file argument it checks the whole project and enforces any [`[profile.realtime]`](/docs/realtime) contracts.

The default build is debug (`-O0`) with overflow traps; pass `--release` for `-O2`.

## Formatting and tests

`cpc fmt` gives one canonical layout, and `cpc fmt --check` exits non-zero on drift so CI can reject style noise without arguing about it. `cpc test` runs `#[test]` functions and doctests. Every feature is expected to ship three test shapes: a positive case that compiles and runs, a negative case that rejects with a specific `Exxxx` code, and an end-to-end case that drives `cpc build`.

A vendor package runs its own tests with `cd vendor/<pkg> && cpc test`; the driver auto-discovers the entry, propagates the package's link flags, and resolves sibling vendor dependencies one directory up.

## The code graph

`cpc` keeps the resolved, typed information the compiler already computes and exposes it as a queryable code graph, so navigation is by symbol and type rather than by text:

```bash
cpc query def    SYMBOL              # resolved definition site(s)
cpc query refs   SYMBOL              # every use site
cpc query callers FN                 # who calls FN
cpc query callees FN                 # what FN calls
cpc query type-at FILE:LINE:COL      # type at a position
cpc query members TYPE               # fields + methods
cpc query context FN                 # edit pack: signature, callers, callees, types
cpc mcp                              # resident MCP server over the graph (for agents)
cpc graph                            # whole-project graph as JSON
```

Every result is JSON with `file:line:col` locations. See [C+ for LLMs](/docs/llms) for why this matters to an agent loop.

## Linking against Apple frameworks

`cpc build` does not yet know framework search paths or the Objective-C runtime. For a program needing `-framework X` or `-lobjc`, emit IR and hand it to `clang`:

```bash
cpc --emit-ll src/main.cplus > out.ll
clang out.ll \
    -framework Cocoa \
    -lobjc \
    -Wno-override-module \
    -o my_binary
```