# `zig_binary`

Zig executable target.

## Description

Compiles a Zig executable with `zig build-exe`. The root can be set with
`main`, or omitted when `deps` contains exactly one Zig module dependency.
Zig module deps are passed through `--dep` and `-M`. C provider deps contribute
headers, definitions, include directories, static libraries, dynamic libraries,
and linker flags.

`once run` first builds the binary, then executes it with the configured
`env` and `args`.

Canonical module names are generated from target labels with collision-safe
escaping. `import_names` keys must match exactly one Zig module dependency by
full label, short label name, import name, or canonical name; ambiguous or
unknown keys fail validation.

## Attributes

| Attribute | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `zig` | string | no | `zig` on PATH | Zig compiler path |
| `zig_version` | string | no | empty | Expected `zig version` output |
| `bootstrapped` | int | no | `-1` | Compatibility selector for bootstrapped Zig toolchains; choose the compiler with `zig` |
| `main` | string | no |  | Package-relative root module, or omit with one Zig module dependency |
| `import_name` | string | no | target name | Name downstream modules use with `@import` |
| `import_names` | map<string, string> | no | `{}` | Rename dependency imports by dependency label, short name, or import name |
| `extra_srcs` | list<string> | no | `[]` | Extra source or data globs included in the compile input digest |
| `extra_docs` | list<string> | no | `[]` | Extra files included in the documentation action input digest |
| `data` | list<string> | no | `[]` | Runtime data globs included in run inputs |
| `target` | string | no | host target | Zig target triple passed with `-target` |
| `cpu` | string | no | empty | Processor setting passed with `-mcpu` |
| `optimize` | string | no | empty | Optimization mode passed with `-O` |
| `mode` | string | no | empty | `auto`, `debug`, `release_safe`, `release_small`, or `release_fast`; maps to `-O` |
| `host_mode` | string | no | empty | Alias for `mode` when porting configured host targets |
| `threaded` | string | no | empty | `multi` passes `-fno-single-threaded`; `single` passes `-fsingle-threaded` |
| `host_threaded` | string | no | empty | Alias for `threaded` when porting configured host targets |
| `strip` | bool | no | `false` | Alias for `strip_debug_symbols` |
| `strip_debug_symbols` | bool | no | `false` | Pass `-fstrip` |
| `compiler_runtime` | string | no | `default` | `default`, `include`, or `exclude` for compiler runtime flags |
| `zigopt` | list<string> | no | `[]` | Global Zig flags prepended before module-specific `zigopts` |
| `host_zigopt` | list<string> | no | `[]` | Alias for `zigopt` when porting configured host targets |
| `zigopts` | list<string> | no | `[]` | Extra flags attached to this module specification |
| `linkopts` | list<string> | no | `[]` | Extra linker flags appended after Once-managed flags |
| `use_cc_common_link` | int | no | `-1` | Compatibility setting for C provider linking; Once consumes C providers through its provider model |
| `host_use_cc_common_link` | int | no | `-1` | Host compatibility setting for C provider linking |
| `use_standalone_translate_c` | int | no | `-1` | Set to `1` to use a standalone `translate-c` executable |
| `translate_c` | string | no | empty | Standalone `translate-c` executable path |
| `translate_c_identity` | string | no | empty | Stable identity for the standalone `translate-c` executable, folded into translate action cache keys |
| `csrcs` | list<string> | no | `[]` | C source files passed to Zig through `-cflags ... --` |
| `copts` | list<string> | no | `[]` | C compiler flags passed after `-cflags` |
| `linker_script` | string | no | empty | Package-relative linker script passed as `-T` |
| `emit_asm` | bool | no | `false` | Emit assembly output |
| `emit_llvm_ir` | bool | no | `false` | Emit compiler intermediate representation output |
| `emit_llvm_bc` | bool | no | `false` | Emit compiler bitcode output |
| `output_name` | string | no | target name | Output file name without platform extension |
| `env` | map<string, string> | no | `{}` | Environment variables for `once run` |
| `args` | list<string> | no | `[]` | Arguments for `once run` |

## Dependency Edges

| Edge | Accepts | Description |
| --- | --- | --- |
| `deps` | `zig_module`, `c_provider` | Zig modules and C provider dependencies consumed by the executable |

## Providers

The target emits `zig_binary`.

## Capabilities

| Capability | Output groups | Requires |
| --- | --- | --- |
| `build` | `binary`, `asm`, `llvm_ir`, `llvm_bc`, `zig_docs` |  |
| `run` | `default` | `binary` |

## Example

```toml
[[target]]
name = "hello"
kind = "zig_binary"
srcs = ["src/**/*.zig"]
deps = ["./math"]

[target.attrs]
main = "src/main.zig"
```