> ## Documentation Index
> Fetch the complete documentation index at: https://klyne-research.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Compile-Only Workflow

> Iterate on kernel codegen and source inspection without requiring a Metal device.

`enigma.compile` runs entirely in the compiler pipeline and does not require a Metal device. You can use this to develop and inspect kernels on any macOS machine with Xcode CLT, including CI runners without Apple Silicon.

## Basic usage

```python theme={null}
import enigma

@enigma.kernel
def add(A: enigma.f32, B: enigma.f32, C: enigma.f32):
    tid = enigma.thread_position_in_grid
    C[tid] = A[tid] + B[tid]

compiled = enigma.compile(add)

# All of these are available without a GPU:
print(compiled.kernel_name)
print(compiled.metallib_path)
print(compiled.metal_source)
```

## Enabling debug artifacts

Use compile flags to capture every stage of the pipeline:

```python theme={null}
compiled = enigma.compile(
    add,
    dump_ir=True,           # print traced IR to stdout
    dump_mlir=True,         # print MLIR before emission
    keep_metal_source=True, # write .metal file to work_dir
    work_dir="./build/enigma",
)
```

### What each flag does

| Flag                     | Effect                                                           |
| ------------------------ | ---------------------------------------------------------------- |
| `dump_ir=True`           | Prints the traced op graph (loads, stores, arithmetic) to stdout |
| `dump_mlir=True`         | Prints the Enigma dialect MLIR before MSL emission               |
| `keep_metal_source=True` | Writes `.metal` source to `work_dir` (default: temp dir)         |
| `work_dir=path`          | Directory for all intermediate build artifacts                   |

## Exporting Metal source

To save the generated source to a specific path for review or diffing:

```python theme={null}
path = compiled.export_metal("./artifacts/add.metal")
print(path)  # ./artifacts/add.metal
```

This is useful for:

* Code review of generated kernels
* Tracking codegen regressions in CI with `git diff`
* Profiling with Metal's GPU capture tools using the original source

## Vectorized kernels

Pass `vec_width` to request vectorized codegen. The pipeline will emit `float4`-style loads and stores when alignment allows:

```python theme={null}
compiled = enigma.compile(add, vec_width=4, keep_metal_source=True)
print(compiled.metal_source)
# Output will use float4 pointers where possible
```

## When to use this workflow

| Scenario                            | Use                                       |
| ----------------------------------- | ----------------------------------------- |
| Developing on a non-Metal machine   | Compile-only — no GPU needed              |
| CI codegen regression tests         | `keep_metal_source=True` + diff artifacts |
| Debugging incorrect output          | `dump_ir=True` + `dump_mlir=True`         |
| Performance tuning with Instruments | Export source with `export_metal()`       |