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:

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

To disable an option explicitly:

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

zig build -Dslow_logging -Dtracy -DcookShaders

Performance Testing Build

zig build -Dzero_logging -Dforce_mailbox -Dmutex_job_queue

Production/Release Build

zig build -Dstatic_build

Linux Build (Required)

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:

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