> ## 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.

# enigma.compile()

> Full reference for the enigma.compile() function and the CompiledKernel it returns.

Runs the full Enigma compilation pipeline and returns a `CompiledKernel`.

## Signature

```python theme={null}
enigma.compile(
    fn,
    *jit_args,
    vec_width: int = 0,
    dump_ir: bool = False,
    dump_mlir: bool = False,
    keep_metal_source: bool = False,
    work_dir: str | None = None,
    emit_only: bool | None = None,
) -> CompiledKernel
```

## Parameters

| Parameter           | Type                              | Default  | Description                                                                                      |
| ------------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `fn`                | `@enigma.kernel` or `@enigma.jit` | required | The kernel or JIT function to compile                                                            |
| `*jit_args`         | `Tensor`, ...                     | —        | For `@enigma.jit`: positional arguments passed to the JIT function at compile time               |
| `vec_width`         | `int`                             | `0`      | Vectorization lane width. `0` = scalar. `4` = `float4` paths                                     |
| `dump_ir`           | `bool`                            | `False`  | Print the traced IR to stdout                                                                    |
| `dump_mlir`         | `bool`                            | `False`  | Print the Enigma dialect MLIR to stdout                                                          |
| `keep_metal_source` | `bool`                            | `False`  | Write `.metal` source file to `work_dir`                                                         |
| `work_dir`          | `str \| None`                     | `None`   | Directory for build artifacts. Defaults to a temp directory                                      |
| `emit_only`         | `bool \| None`                    | `None`   | Skip Metal compilation. `None` = auto (True on non-macOS). `True` = emit MSL only (no .metallib) |

## Returns: `CompiledKernel`

### Attributes

| Attribute        | Type                           | Description                                                   |
| ---------------- | ------------------------------ | ------------------------------------------------------------- |
| `kernel_name`    | `str`                          | Metal function name, e.g. `enigma_kernel_vector_add`          |
| `metallib_path`  | `str`                          | Absolute path to the compiled `.metallib` file                |
| `metallib_bytes` | `bytes`                        | Raw bytes of the `.metallib`                                  |
| `metal_source`   | `str`                          | Generated Metal Shading Language source                       |
| `mlir_source`    | `str \| None`                  | Enigma dialect MLIR (when `dump_mlir=True`)                   |
| `grid`           | `tuple[int, int, int] \| None` | For `@jit` kernels: launch grid computed at compile time      |
| `block`          | `tuple[int, int, int] \| None` | For `@jit` kernels: threadgroup size computed at compile time |

### Methods

#### `export_metal(path: str) -> str`

Write the generated Metal source to a file. Returns the resolved path.

```python theme={null}
saved = compiled.export_metal("./artifacts/my_kernel.metal")
```

## Usage

### Compiling a `@enigma.kernel`

```python theme={null}
@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)
```

### With debug output

```python theme={null}
compiled = enigma.compile(
    add,
    dump_ir=True,
    dump_mlir=True,
    keep_metal_source=True,
    work_dir="./build/enigma",
)
print(compiled.metal_source)
```

### Vectorized compilation

```python theme={null}
compiled = enigma.compile(add, vec_width=4)
# kernel uses float4 loads/stores when alignment permits
```

### Compiling a `@enigma.jit` function

Pass the `Tensor` arguments that the JIT function receives at compile time:

```python theme={null}
m, n = 256, 512
A = enigma.Tensor("A", 0, "float", enigma.Layout((m, n), (n, 1)))
B = enigma.Tensor("B", 1, "float", enigma.Layout((m, n), (n, 1)))
C = enigma.Tensor("C", 2, "float", enigma.Layout((m, n), (n, 1)))

compiled = enigma.compile(tiled_add, A, B, C)
# compiled.grid and compiled.block are set
```

## Errors

| Error                               | Cause                                                                                                |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `xcrun` exit code error             | Metal compiler toolchain not found. Run `xcrun -sdk macosx metal -v` to diagnose.                    |
| `EnigmaError: tiler exceeds tensor` | A layout division produced a tiler larger than the tensor in some mode.                              |
| `TypeError` in tracer               | Invalid operand types — check that you are not mixing Python values with `IRValue` in kernel bodies. |