# Attributes

Attributes are pure metadata: they flip flags the compiler reads. They never generate code, transform the AST, or run user logic.

## `#[test]`: register a test function

```cplus
#[test]
fn it_adds() {
    let r: i32 = add(2, 3);
    assert r == 5;
}
```

Run with `cpc test`. The `assert` intrinsic sets a failure flag in a test build and traps in a regular build.

## `#[repr(C)]` and `#[link_name = "..."]`

Layout and symbol control for FFI. Both are covered on the [FFI](/docs/ffi) page: `#[repr(C)]` promises platform C-ABI layout for a struct that crosses an `extern fn` boundary, and `#[link_name]` binds one C symbol under several typed shapes.

## Loop hints: `#[unroll(N)]` and `#[vectorize_width(N)]`

Statement-level attributes that flow through to LLVM's loop optimizer as `!llvm.loop` metadata. Apply them to a `while`, `loop`, or `for`. `N` is a literal in `[1, 256]`.

```cplus
#[unroll(4)]
while i < n {
    sum = sum + buf[i as usize];
    i = i +% 1;
}

#[vectorize_width(8)]
for i in 0..count {
    out[i as usize] = a[i as usize] * b[i as usize];
}
```

They are marginal for general code but load-bearing for the tight inner loops the compiler does not vectorize well by default.

## `#[inline]`: inlining control

A function- or method-level attribute, in three forms:

- `#[inline]` becomes LLVM `inlinehint`. Only the optimizer acts on it, so it matters at `--release` and is a no-op at debug `-O0`.
- `#[inline(always)]` becomes `alwaysinline`. It inlines even at `-O0` and past LLVM's cost threshold, the lever for hot kernels built from small over-threshold helpers.
- `#[inline(never)]` becomes `noinline`. It pins a call boundary for cold paths or code-size control.

These are pure hints with no behavioural change, so reach for them only on measured hot or deliberately cold paths.

## Real-time contracts

`#[no_alloc]`, `#[no_block]`, `#[bounded_recursion]`, `#[max_stack(N)]`, and the `#[realtime]` bundle are compiler-verified contracts, not optimizations. They are documented in full on the [Real-time](/docs/realtime) page.

## Doc comments

```cplus
/// Returns the square of x.
fn sq(x: i32) -> i32 { return x *% x; }
```

`///` comments are doc comments, and `cpc test` picks up fenced code blocks inside them as doctests.