Backlog/docs/build-options.md

# Backlog Engine Build Options

This document provides comprehensive documentation for all `core.BuildOption` flags available in the Backlog game engine.

## Overview

Build options in Backlog are boolean flags that control various compilation behaviors and engine features. They are accessed at compile-time using `core.BuildOption("option_name")` and can be set via Zig's build system command line arguments.

## Usage

Build options are set when building the project:

```bash
zig build -Doption_name
# or
zig build -Doption_name=true
```

To disable an option explicitly:
```bash
zig build -Doption_name=false
```

## Core Engine Build Options

### Performance & Development Options

#### `mutex_job_queue`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Temporary test option that reverts to old mutex-based queue behavior in `jobs.zig:JobManager`
- **Usage**: `zig build -Dmutex_job_queue`
- **Impact**: Changes job system threading behavior for debugging/testing purposes
- **Files**: `engine/core/src/jobs.zig:8`

#### `force_mailbox`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Forces mailbox mode for present mode, unlocking framerate to very high levels
- **Usage**: `zig build -Dforce_mailbox`
- **Impact**: Disables VSync and allows unlimited framerate rendering
- **Warning**: Can cause excessive GPU usage and heat generation

### Logging Options

#### `zero_logging`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Disables all logging completely, intended primarily for job dispatch performance testing
- **Usage**: `zig build -Dzero_logging`
- **Impact**: Removes all log output, improving performance but eliminating debug information
- **Files**: `engine/core/src/logging.zig:7`

#### `slow_logging`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Disables buffered logging, taking a performance hit but providing accurate timing information
- **Usage**: `zig build -Dslow_logging`
- **Impact**: Each log call is immediately flushed, providing precise timing but reducing performance
- **Files**: `engine/core/src/logging.zig:6`

### Build & Deployment Options

#### `static_build`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Builds the entire game as a single executable with static linking
- **Usage**: `zig build -Dstatic_build`
- **Impact**:
  - Required for Linux builds
  - Disables dynamic module loading
  - Creates self-contained executable
- **Files**:
  - `build.zig:190`
  - `engine/core/src/extern/externModule.zig:139`
  - `build/generateApi.zig:118`
  - `engine/rend/src/sgpu/renderer.zig:1126`

#### `RootDeploymentOnly`
- **Type**: `bool`
- **Default**: Not explicitly set (appears to default to `false`)
- **Description**: Controls whether only root deployment operations are performed
- **Usage**: `zig build -DRootDeploymentOnly`
- **Impact**: Appears to limit engine initialization to root-level deployment only
- **Files**: `engine/main.zig:28`

### Development & Shader Options

#### `cookShaders`
- **Type**: `bool`
- **Default**: `false`
- **Description**: Generates shaders and updates `.json` files before running the build
- **Usage**: `zig build -DcookShaders`
- **Impact**:
  - Automatically runs `tools/scripts/cookShaders.py`
  - Compiles HLSL shaders to SPIR-V, MSL, and DXIL formats
  - Must be run whenever shader files are modified
- **Files**: `build.zig:80`

### Third-Party Integration Options

#### `tracy` (Tracy Profiler)
- **Type**: `bool`
- **Default**: `false`
- **Description**: Enables Tracy profiler integration for performance analysis
- **Usage**: `zig build -Dtracy`
- **Impact**:
  - Adds Tracy profiling instrumentation
  - Enables real-time performance monitoring
  - Increases binary size and may affect performance
- **Files**: `lib/tracy/build_tracy.zig:37`

## Build Option Categories

### By Purpose

**Performance Testing**:
- `mutex_job_queue` - Job system behavior testing
- `zero_logging` - Maximum performance logging
- `force_mailbox` - Unlimited framerate testing

**Development & Debugging**:
- `slow_logging` - Precise timing information
- `tracy` - Performance profiling
- `cookShaders` - Shader development workflow

**Deployment & Distribution**:
- `static_build` - Self-contained executable creation
- `RootDeploymentOnly` - Deployment scope control

### By Impact Level

**High Impact** (affects core engine behavior):
- `static_build`
- `zero_logging`
- `mutex_job_queue`

**Medium Impact** (affects specific subsystems):
- `slow_logging`
- `force_mailbox`
- `cookShaders`

**Low Impact** (development/profiling tools):
- `tracy`
- `RootDeploymentOnly`

## Common Build Configurations

### Development Build
```bash
zig build -Dslow_logging -Dtracy -DcookShaders
```

### Performance Testing Build
```bash
zig build -Dzero_logging -Dforce_mailbox -Dmutex_job_queue
```

### Production/Release Build
```bash
zig build -Dstatic_build
```

### Linux Build (Required)
```bash
zig build -Dstatic_build
```

## Implementation Details

Build options are implemented through Zig's compile-time options system:

1. **Definition**: Options are defined in `build.zig` in the `BuildOptions` struct
2. **Access**: Runtime code accesses options via `core.BuildOption("option_name")`
3. **Compilation**: The `core.BuildOption()` function checks for the option at compile-time
4. **Fallback**: If an option is not defined, it defaults to `false`

The `core.BuildOption()` function implementation:
```zig
pub fn BuildOption(comptime option: []const u8) bool {
    if (@hasDecl(@import("root"), "options")) {
        const r = @import("root").options;
        if (@hasDecl(r, option)) {
            return @field(r, option);
        } else {
            return false;
        }
    }
    return false;
}
```

## Notes

- All build options are boolean flags
- Options not explicitly set default to `false`
- Some combinations may be incompatible (e.g., `zero_logging` + `slow_logging`)
- Linux builds require `static_build=true`
- Shader compilation via `cookShaders` should be run after modifying any `.hlsl` files