# C+

> C+ is a fast, safer systems programming language: native speed through LLVM, a borrow-checked ownership model, and two-way C ABI compatibility. The language core is small on purpose; everything else, including the standard library, is a package. This documents version 0.0.26.

> LLM version note: Search indexes and snippets may surface archived manual pages under `/docs/{version}`. Always verify the page version and prefer `/docs`, `/llms.txt`, or `/llms-full.txt` for the latest manual (v0.0.26). Older versioned pages are intentional archives, not documentation leakage.

## Introduction

- [Overview](https://cplus-lang.dev/docs/overview.md): What C+ is and what it leaves out: native code through LLVM, a borrow-checked ownership model, and the locked principles that keep every program locally legible.
- [Getting started](https://cplus-lang.dev/docs/getting-started.md): Install the cpc toolchain and compile your first C+ program, in both single-file and project mode.
- [Design FAQ](https://cplus-lang.dev/docs/faq.md): Why C+ is the way it is: why there is no null, no closures, no references, no exceptions, and no implicit conversions; why the language stays small; why capability lives in packages; and why a safe language need not be a slow one.

## Language

- [Primitives & literals](https://cplus-lang.dev/docs/primitives.md): C+ primitive types and literals: sized integers and floats, bool, unit, str, raw pointers, and how integer, float, hex, binary, and character literals are written.
- [Variables & mutability](https://cplus-lang.dev/docs/variables.md): Bindings in C+: let, type inference, opt-in var, deferred initialization, lexical scope, and module-scope const and static.
- [Operators & arithmetic](https://cplus-lang.dev/docs/operators.md): Arithmetic in C+: overflow-checked by default with explicit wrapping operators, bitwise and shifts, byte-swap intrinsics, comparisons, and explicit width casts.
- [Control flow](https://cplus-lang.dev/docs/control-flow.md): Control flow in C+: if as statement and expression, while, the two for flavours plus iterators, loop / break / continue, and while let.
- [Functions](https://cplus-lang.dev/docs/functions.md): Functions in C+: declaration, the unit return, default-public visibility, the explicit return rule, block tail expressions, generics with square brackets, and no overloading.
- [Arrays](https://cplus-lang.dev/docs/arrays.md): Fixed-size, stack-allocated, bounds-checked arrays in C+, the fill-array literal [EXPR; N] with its memset fast path, and const-named lengths.
- [Structs & methods](https://cplus-lang.dev/docs/structs-and-methods.md): Define data with struct and behaviour with impl: associated functions, instance methods, the three receiver forms, struct literals, and field visibility.
- [Enums](https://cplus-lang.dev/docs/enums.md): Plain C-like enums and tagged unions (sum types) in C+, including generic enums and the rule that type arguments are always written at the source level.
- [Pattern matching](https://cplus-lang.dev/docs/pattern-matching.md): Exhaustive match, catch-all arms, and the if let / guard let / while let binding forms for extracting values from tagged enums in C+.
- [Builder blocks](https://cplus-lang.dev/docs/builder-blocks.md): Contextual builder blocks: the @ctx { ... } construction DSL. Item expressions with leading-dot modifier lines, container elements, and Flutter-style if/for, lowered to an ordinary Builder::new / add / finish protocol — no macros.

## Ownership & safety

- [Ownership](https://cplus-lang.dev/docs/ownership.md): C+ ownership: borrow-by-default, the ref and take parameter markers, structural Copy, restrict, and what the compiler enforces versus what it trusts you to uphold.
- [Drop & defer](https://cplus-lang.dev/docs/drop-and-defer.md): Deterministic cleanup in C+: a drop method as your destructor, hand-freeing raw-pointer fields, and defer for LIFO scope-exit actions.
- [The borrow checker](https://cplus-lang.dev/docs/borrow-checker.md): Aliasing XOR mutability: the single rule the C+ borrow checker enforces at compile time, the common diagnostics, and how a scope boundary fixes them.
- [Error handling](https://cplus-lang.dev/docs/error-handling.md): Errors as values in C+: tagged-union results, exhaustive match, the guard let happy path, and stdlib Result and Option. No exceptions, no ? operator.

## Systems

- [FFI — calling C](https://cplus-lang.dev/docs/ffi.md): Calling C from C+ with extern fn: declaring symbols, c-string literals, raw pointers, #[repr(C)] layout, #[link_name], Objective-C interop, and the ABI gotchas that bite.
- [Function pointers](https://cplus-lang.dev/docs/function-pointers.md): Function pointers in C+: the fn(...) -> R type, bare-name coercion, structs of callbacks, and the C convention for stateful callbacks without closures.
- [Compile-time intrinsics](https://cplus-lang.dev/docs/intrinsics.md): The #name(...) compiler intrinsics in C+: typed queries (size_of, align_of, addr_of, zero), compile-time data embedding (include_bytes, include_str, env), and CPU hints.
- [Modules & packages](https://cplus-lang.dev/docs/modules-and-packages.md): Imports in C+: single-file vs project mode, the mandatory local (./) or vendored import form, the required alias, name-based visibility, and the Cplus.toml manifest.
- [Attributes](https://cplus-lang.dev/docs/attributes.md): Attributes in C+ are pure metadata: #[test], #[repr(C)], the loop hints #[unroll] and #[vectorize_width], #[inline] control, the real-time contracts, and doc comments.
- [Threads & atomics](https://cplus-lang.dev/docs/threads.md): Concurrency in C+: spawn and join, passing data with spawn_with, the partition-and-join pattern, atomics with explicit ordering, and refcounted mutexes.
- [Async / await](https://cplus-lang.dev/docs/async.md): Async in C+: async fn returning Future[T], await, the signature rules that ban borrow-shaped parameters, and the kqueue-backed reactor for concurrent I/O.
- [SIMD types](https://cplus-lang.dev/docs/simd.md): Fixed-width SIMD as primitive types in C+: the 64/128/256-bit lane families, constructors, per-element-type methods, lane conversions, widen/narrow, reductions, masks, and the FFI boundary.
- [Real-time](https://cplus-lang.dev/docs/realtime.md): Compiler-proven real-time contracts in C+: #[realtime], #[no_alloc], #[no_block], #[max_stack], the [profile.realtime] project gate, and the lock-free rt building blocks.
- [Inline assembly](https://cplus-lang.dev/docs/inline-assembly.md): Inline assembly in C+: the #asm block, named operands with in/out/inout and register constraints, clobbers, and #[naked] functions that supply their own prologue.
- [GPU & numerics](https://cplus-lang.dev/docs/gpu-numerics.md): How C+ talks to GPUs and BLAS: a consumer of vendor SDKs through plain C FFI, with Drop-managed handles. The backend matrix across Apple (Metal / Accelerate), NVIDIA (CUDA / cuBLAS), and cross-platform CPU (CBLAS, SIMD).
- [Agent surface](https://cplus-lang.dev/docs/agent-surface.md): How a C+ app exposes itself to an external agent: described, driven, and observed over a consent-gated JSON-RPC / MCP bridge. The agent_core authorization brain, the agent_appkit GUI backend, and the agent_mcp bridge.
- [Targets & cross-compilation](https://cplus-lang.dev/docs/targets.md): Cross-compiling C+ with --target: the named targets (host, iOS, Android, ESP32), per-target ABI selection, and the external-builder handoff that lets Xcode and the Android NDK own the final link.
- [Embedded & ESP32](https://cplus-lang.dev/docs/embedded.md): C+ on microcontrollers: the esp32-xtensa 32-bit target, the embedded package profile, heap types on the newlib heap, compiler-proven #[realtime] running on real hardware, and the espidf bindings.

## Packages

- [Overview](https://cplus-lang.dev/docs/packages.md): How packages work in C+: the small language core plus a curated set of vendored packages, including the standard library. Deployment model and the full package list.
- [Package manager](https://cplus-lang.dev/docs/package-manager.md): cplus-pm: a standalone tool that manages a project's vendor/ packages — install, remove, and update with git-tag versioning, pubgrub resolution, SHA-256 content addressing, a shared cache, and a lockfile.
- [stdlib](https://cplus-lang.dev/docs/packages/stdlib.md): The C+ standard library: I/O, vectors, hash maps, files, networking, ownership wrappers (Box, Arc, Rc), concurrency, and result/option types. A vendored package, imported per module.
- [accelerate](https://cplus-lang.dev/docs/packages/accelerate.md): Bindings to Apple's Accelerate.framework: pre-tuned CPU numerics (BLAS via cblas, element-wise and reductions via v_dsp) that ship in every macOS binary.
- [agent_appkit](https://cplus-lang.dev/docs/packages/agent_appkit.md): The macOS GUI backend for the agent surface: open(window) walks a live NSView tree into a Surface, describe_ui returns a UiNode snapshot, and authorized click / set_text / scroll_to run through the agent_core brain.
- [agent_core](https://cplus-lang.dev/docs/packages/agent_core.md): The framework-agnostic core for agent-controllable apps: a build-time-stable agent-id tree, curated describe, the consent AuthGate with exposure and an affordance ceiling, bubbling {node,verb,role} events, and optimistic-concurrency action/text authorization.
- [agent_mcp](https://cplus-lang.dev/docs/packages/agent_mcp.md): The MCP bridge for the agent surface: JSON-RPC 2.0 (describe_ui / actions / events) over Unix-domain sockets (serve_uds / serve_fd), with every request gated by an agent_core consent AuthGate.
- [android_view](https://cplus-lang.dev/docs/packages/android_view.md): Android View bindings for C+, layered on vendor/jni: build a native View tree from C+, and receive Button taps through a package-shipped DEX adapter. Validated end to end on the emulator.
- [appkit](https://cplus-lang.dev/docs/packages/appkit.md): Typed Cocoa / AppKit bindings for native macOS desktop apps: application lifecycle, windows, views, controls, and closure-free callbacks.
- [arena](https://cplus-lang.dev/docs/packages/arena.md): A growable, multi-chunk bump-pointer arena for allocate-many, free-all workloads like parsers, compilers, and request-scoped allocations.
- [cblas](https://cplus-lang.dev/docs/packages/cblas.md): Reference CBLAS bindings (OpenBLAS / Netlib / MKL): the cross-platform CPU BLAS path. Level 1/2/3 routines — sdot, saxpy, sscal, snrm2, sasum, sgemv, sgemm, and d-variants — with typed Order and Transpose enums.
- [clap](https://cplus-lang.dev/docs/packages/clap.md): Command-line argument parsing with a fluent builder: flags, long and short options, positional arguments, and typed match accessors.
- [coreai](https://cplus-lang.dev/docs/packages/coreai.md): A Swift bridge to Apple's CoreAI, adapted to the real API on Xcode 27 / macOS 27.
- [cuda](https://cplus-lang.dev/docs/packages/cuda.md): Typed CUDA Runtime + cuBLAS bindings for NVIDIA GPUs: device management, Drop-managed DeviceBuffer (cudaFree) and cuBLAS Handle (cublasDestroy_v2), and column-major sgemm / sgemv. Plain C FFI, no kernel language.
- [espidf](https://cplus-lang.dev/docs/packages/espidf.md): ESP-IDF bindings for the esp32-xtensa target: GPIO, the esp_timer microsecond clock, task sleep, and UART console output. The gpio/timer externs are #[no_alloc] + #[no_block], so a #[realtime] loop can use them.
- [jni](https://cplus-lang.dev/docs/packages/jni.md): Java Native Interface bindings: #[repr(C)] mirrors of the JVM dispatch tables covering the full JNI 1.6 function table, called through a function-pointer table exactly as C's JNI does.
- [json](https://cplus-lang.dev/docs/packages/json.md): A typed-enum JSON parser and serializer: a recursive Value enum, parse and to_text entry points, and is_* / as_* accessors. Drops payloads recursively.
- [llama_cpp](https://cplus-lang.dev/docs/packages/llama_cpp.md): C+ bindings for llama.cpp's C API: raw FFI generated from the upstream headers with cpc-bindgen, plus a hand-written safe Session facade (load / generate / tokenize / decode / sample).
- [log](https://cplus-lang.dev/docs/packages/log.md): A leveled, zero-allocation structured logger to stderr: configure level and colors once, then log at trace / debug / info / warn / error with no malloc per call.
- [metal](https://cplus-lang.dev/docs/packages/metal.md): Typed Metal bindings for Apple GPU compute: devices, command queues, buffers, libraries, functions, and compute pipeline state, generated over Apple's Metal framework.
- [simd](https://cplus-lang.dev/docs/packages/simd.md): 3D math on f32x4 plus integer-widening lane helpers: Vec3, Vec4, Mat4x4, and composable integer lane ops like a 16-lane signed-byte dot product.
- [static-arena](https://cplus-lang.dev/docs/packages/static-arena.md): A fixed-size bump-pointer arena whose buffer lives on the stack or in static storage: zero malloc, zero free, composes with the #[no_alloc] real-time contract.
- [uikit](https://cplus-lang.dev/docs/packages/uikit.md): Typed UIKit bindings for native iOS apps, mirroring vendor/appkit: windows, view controllers, controls, text, containers, data views, graphics, Auto Layout, and app-delegate synthesis, with the cplus_app_main entry convention.
- [uuid](https://cplus-lang.dev/docs/packages/uuid.md): RFC 4122 v4 UUIDs sourced from /dev/urandom, portable across macOS, Linux, and BSD. Generate, parse, and format with an infallible to_text.
- [rt](https://cplus-lang.dev/docs/packages/rt.md): Lock-free, allocation-free real-time building blocks: the SpscRingU64 ring and FixedPoolU64 object pool, plus the rt_darwin platform controls (clock, thread QoS, page locking).
- [facet](https://cplus-lang.dev/docs/packages/facet.md): A platform-free, declarative UI framework: describe a view tree in @facet { } builder blocks (label / button / stack + .on_click) that a per-platform renderer turns into native widgets.
- [facet_appkit](https://cplus-lang.dev/docs/packages/facet_appkit.md): The AppKit (macOS) renderer for facet: render walks a facet::Node tree into a native NSView/NSStackView/NSButton/NSTextField tree, and run opens a window and mounts it.
- [gtk](https://cplus-lang.dev/docs/packages/gtk.md): Typed GTK 4 bindings for native Linux desktop apps: application lifecycle, windows, widgets, controls, containers, dialogs, and closure-free signal handlers.
- [adwaita](https://cplus-lang.dev/docs/packages/adwaita.md): libadwaita 1 bindings for Linux — GNOME's adaptive widgets, boxed-list preferences, in-app toasts, and light/dark recoloring, layered on top of gtk.
- [win32](https://cplus-lang.dev/docs/packages/win32.md): Native Win32 GUI bindings for Windows: top-level windows, the common controls, menu bars, message + file dialogs, and GDI painting — direct extern calls to the always-present system DLLs.
- [agent_win32](https://cplus-lang.dev/docs/packages/agent_win32.md): The Windows GUI backend for the agent surface: open(window) walks a live HWND tree into a Surface, describe() returns a UiNode snapshot, and authorized click / set_text / focus run through the agent_core brain.
- [agent_gtk](https://cplus-lang.dev/docs/packages/agent_gtk.md): The GTK 4 GUI backend for the agent surface: open(window) walks a live GtkWidget tree into a Surface, describe() returns a UiNode snapshot, and authorized click / set_text / focus run through the agent_core brain.

## Reference

- [Language specification](https://cplus-lang.dev/docs/spec.md): The normative reference for C+ as of v0.0.26: lexical structure, the full EBNF grammar, the type and ownership systems, FFI, real-time contracts, builder blocks, the normative desugarings, and the diagnostic categories. The compiler is the ultimate authority; this fixes the categories.
- [Tooling — cpc](https://cplus-lang.dev/docs/tooling.md): The cpc command-line tool: build and check, release mode, fmt, test, the code-graph queries, MCP server, IR and assembly emission, and linking against Apple frameworks.
- [Error codes](https://cplus-lang.dev/docs/error-codes.md): The complete index of C+ compiler diagnostics — every E and W code, with what it means, a minimal example that triggers it, and the fix. Generated from the compiler's diagnostic catalog so the manual cannot drift from the compiler.
- [C+ for LLMs](https://cplus-lang.dev/docs/llms.md): Why C+ is shaped for model-generated code: a small surface, specific diagnostics, a resolved code graph queryable over MCP, hand-emitted LLVM IR, and contracts the compiler can check.
- [Stability and versioning](https://cplus-lang.dev/docs/stability.md): C+ keeps a small, stable language surface that changes only in versioned, archived releases. What stays stable, what changes between releases (soundness fixes, occasional surface refinements, diagnostics, performance, tooling, targets, packages), and how packages version independently of the language.

## Guides

- [Your first C+ program](https://cplus-lang.dev/guides/your-first-cplus-program): Install the toolchain, write a real C+ program, and learn the write, audit, run loop that C+ is built around. No prior systems experience needed.
- [Structs, ownership, and errors in C+](https://cplus-lang.dev/guides/structs-ownership-and-errors): Model your data with structs and methods, understand C+ ownership without the borrow-checker fight, and handle errors as plain values. With verified, runnable examples.
- [FFI, real-time, and performance in C+](https://cplus-lang.dev/guides/ffi-realtime-and-performance): Call C and let C call you back, give the optimizer the aliasing facts it needs, and let the compiler prove a hot path never allocates or blocks. All with verified examples.
- [Writing correct C+: a guide for language models](https://cplus-lang.dev/guides/writing-correct-cplus): A dense generation guide for an LLM about to write or edit C+. The compiler-enforced rules, the canonical patterns, the things never to propose, and the self-audit loop.
- [Navigate C+ by its code graph, not grep](https://cplus-lang.dev/guides/code-graph-not-grep): How a language model understands a C+ codebase using cpc's resolved, typed code graph (cpc query and cpc mcp) instead of grep: precise definitions, callers, and a one-call context pack.
- [Control a C+ desktop app from a language model](https://cplus-lang.dev/guides/control-cplus-desktop-app-from-llm): How a C+ macOS app built with AppKit exposes itself to a language model through the agent_core / agent_appkit / agent_mcp packages: described, driven, and observed, in-process or over MCP, behind a consent gate.
- [Should your team adopt C+?](https://cplus-lang.dev/guides/should-your-team-adopt-cplus): An honest evaluation brief for technical leaders: what C+ is, where it fits, how adoption works, what the risks are, and when not to use it.

## Examples

- [Ray tracer](https://cplus-lang.dev/examples/raytracer): A complete path tracer in one C+ file: 10 spheres with Lambertian, metal, and dielectric materials, rendered to a PPM image. Full source, a walkthrough, the numbers it produces, and how to reproduce them.
- [A proven allocation-free control kernel on the ESP32](https://cplus-lang.dev/examples/esp32-realtime-pid): C+ proves an embedded control kernel never allocates or blocks before any firmware is flashed. A fixed-point PID step marked #[realtime], cross-compiled to the ESP32, with the contract checked across the whole call graph at cpc check time.
- [Realtime audio meter](https://cplus-lang.dev/examples/realtime-audio-meter): A small audio-style hot path that is accepted under #[realtime], plus negative fixtures that prove hidden allocation, blocking, and oversized stack frames are rejected by the compiler.
- [A native iOS screen in C+](https://cplus-lang.dev/examples/ios-uikit-hello): A native iOS app whose UI is written in C+: a UIWindow with a centered label, built through the uikit bindings, cross-compiled with cpc, linked by Xcode, and rendered on the iPhone simulator. The only C is a two-line main shim.
- [AppKit agent surface](https://cplus-lang.dev/examples/appkit-agent-counter): The checked appkit_agent recipe from the C+ source tree: a macOS AppKit window exposed through agent_appkit and agent_mcp, with tagged controls, consent-gated JSON-RPC actions, and stale text rejection.
- [AppKit hello](https://cplus-lang.dev/examples/appkit-hello): The checked appkit_hello recipe from the C+ source tree: a native macOS AppKit window, typed controls, C+ Text to NSString bridging, a Quit callback, and the real AppKit event loop.
- [Build a construction DSL with @ctx](https://cplus-lang.dev/examples/builder-block-dsl): Create your own declarative DSL in a few lines: a package that ships the Builder protocol, then a @ctx { ... } block that uses it — with modifiers, a setup let, and a container. No macros; it lowers to ordinary calls.
- [C ABI consumer](https://cplus-lang.dev/examples/c-abi-consumer): The checked c_consumer reference example from the C+ source tree: build a C+ library, generate a C header, link it from C, and exercise scalar, struct, enum, pointer, and function-pointer ABI classes.
- [SIMD dot product](https://cplus-lang.dev/examples/simd-dot): The checked simd_dot recipe from the C+ source tree: compare a scalar dot product with an explicit f32x4 FMA loop and exit 0 only when both produce 347.
- [Metal compute](https://cplus-lang.dev/examples/metal-compute): The macOS-only metal_compute reference recipe from the C+ source tree: compile a Metal shader, embed the metallib, dispatch it through Objective-C FFI, and verify GPU readback.
- [Threads and atomics](https://cplus-lang.dev/examples/threads-atomics): The checked parallel_sum and concurrent_counter recipes from the C+ source tree: partition-and-join threading, plus the explicit atomic pattern for shared mutable state.
- [Async / await](https://cplus-lang.dev/examples/async-await): Checked async recipes from the C+ source tree: chained async fn + await, cooperative spawn_local/yield_now, and method-form async TCP I/O driven by executor::block_on.

## Optional

- [Full documentation](https://cplus-lang.dev/llms-full.txt): every manual page for v0.0.26 concatenated as one markdown document