Section 13: Conditional Compilation

Goal: Enable platform-specific code and feature flags

Criticality: High — Required for cross-platform support and feature management

Proposal: proposals/approved/conditional-compilation-proposal.md

Design Decisions

Question	Decision	Rationale
Syntax	`#target(...)` and `#cfg(...)`	Separate platform from features, clear intent
File-level	`#!target(...)`	Directive at top of file
OR conditions	`any_os`, `any_arch`, `any_feature`	Essential for real cross-platform code
Negation	`not_*` prefix	`not_os`, `not_debug`, `not_feature` — consistent
Families	`family: "unix"/"windows"/"wasm"`	Group related platforms
DCE	Full elimination	False branches not type-checked
Feature names	Valid identifiers only	Consistent with Ori naming

Reference Implementation

Rust

~/projects/reference_repos/lang_repos/rust/compiler/rustc_attr_parsing/src/cfg.rs  # cfg parsing
~/projects/reference_repos/lang_repos/rust/compiler/rustc_expand/src/cfg.rs        # cfg evaluation

Go

~/projects/reference_repos/lang_repos/golang/src/go/build/constraint/             # Build constraints
~/projects/reference_repos/lang_repos/golang/src/cmd/go/internal/work/build.go    # Build tags handling

Swift

# Swift uses #if os(...), #if arch(...), #if canImport(...)
~/projects/reference_repos/lang_repos/swift/lib/Parse/ParseIfConfig.cpp           # #if config parsing
~/projects/reference_repos/lang_repos/swift/lib/AST/PlatformKind.cpp              # Platform enumeration

13.1 Target Attribute

Spec section: spec/25-conditional-compilation.md § Target Attribute

Syntax

// Operating system
#target(os: "linux")
@linux_specific () -> void = ...

#target(os: "windows")
@windows_specific () -> void = ...

// Architecture
#target(arch: "x86_64")
@x64_specific () -> void = ...

// Target families
#target(family: "unix")
@unix_like () -> void = ...

// Combined (AND)
#target(os: "linux", arch: "x86_64")
@linux_x64 () -> void = ...

Implementation

13.2 OR Conditions

Spec section: spec/25-conditional-compilation.md § OR Conditions

Syntax

// Match any OS in list
#target(any_os: ["linux", "macos", "freebsd"])
@unix_variants () -> void = ...

// Match any architecture
#target(any_arch: ["x86_64", "aarch64"])
@desktop_arch () -> void = ...

Implementation

13.3 Negation

Spec section: spec/25-conditional-compilation.md § Negation

Syntax

// Negated conditions
#target(not_os: "windows")
@non_windows () -> void = ...

#target(not_family: "wasm")
@native_only () -> void = ...

#cfg(not_debug)
@release_only () -> void = ...

#cfg(not_feature: "ssl")
@insecure_fallback () -> void = ...

Implementation

13.4 Cfg Attribute

Spec section: spec/25-conditional-compilation.md § Cfg Attribute

Syntax

// Build mode flags
#cfg(debug)
@debug_only () -> void = ...

#cfg(release)
@release_only () -> void = ...

// Feature flags
#cfg(feature: "ssl")
@secure_connect () -> void = ...

#cfg(any_feature: ["ssl", "tls"])
@encrypted_connect () -> void = ...

Implementation

13.5 Feature Flags

Spec section: spec/25-conditional-compilation.md § Features

Syntax

# In ori.toml
[features]
default = ["logging"]
logging = []
metrics = ["logging"]  # depends on logging
experimental = []
ssl = []

// In code
#cfg(feature: "logging")
@log_message (msg: str) -> void uses Logger = ...

#cfg(not_feature: "logging")
@log_message (msg: str) -> void = ()  // No-op

// Feature-gated imports
#cfg(feature: "metrics")
use std.metrics { Counter, Gauge }

Feature Name Validation

Feature names must be valid Ori identifiers:

Start with a letter or underscore
Contain only letters, digits, and underscores

#cfg(feature: "ssl")           // valid
#cfg(feature: "async_io")      // valid
#cfg(feature: "my-feature")    // error: invalid feature name

Implementation

13.6 File-Level Conditions

Spec section: spec/25-conditional-compilation.md § File-Level Conditions

Syntax

// file: linux_impl.ori
#!target(os: "linux")

// Everything in this file is Linux-only
@epoll_create () -> int = ...
@epoll_wait (fd: int) -> [Event] = ...

The #! prefix indicates a file-level condition. It must appear before any declarations (after comments).

Implementation

13.7 Compile-Time Constants

Spec section: spec/25-conditional-compilation.md § Compile-Time Constants

Sync Points: Compile-Time Constants (multi-crate sync required)

Adding $target_os, $target_arch, $target_family, $debug, $release requires:

ori_ir — Represent compile-time constants in AST (distinguish from user $ constants)
ori_types — Register type signatures ($target_os: str, $debug: bool, etc.) in infer_ident()
ori_eval — Provide runtime values from build configuration
ori_llvm — Fold to constants during codegen, enable dead branch elimination

Built-in Constants

$target_os: str       // "linux", "macos", "windows", etc.
$target_arch: str     // "x86_64", "aarch64", etc.
$target_family: str   // "unix", "windows", "wasm"
$debug: bool          // true in debug builds
$release: bool        // true in release builds

Usage

@get_path_separator () -> str =
    if $target_os == "windows" then "\\" else "/"

Dead Code Elimination

Branches conditioned on compile-time constants are eliminated and not type-checked:

@get_window_handle () -> WindowHandle =
    if $target_os == "windows" then
        WinApi.get_hwnd()  // Only type-checked on Windows
    else
        panic(msg: "Not supported on this platform")

Implementation

13.8 Build Configuration

Spec section: spec/25-conditional-compilation.md § Build Configuration

CLI Flags

# Target specification
ori build --target linux-x86_64
ori build --target macos-aarch64
ori build --target windows-x86_64

# Features
ori build --feature ssl --feature async
ori build --no-default-features --feature minimal

# Build mode
ori build --debug    # sets cfg(debug)
ori build --release  # sets cfg(release)

# Custom cfg flags
ori build --cfg experimental

Project Configuration

# ori.toml
[package]
name = "myapp"
version = "1.0.0"

[features]
default = ["ssl"]
ssl = []
async = ["dep:async-runtime"]
experimental = []

[target.linux]
dependencies = ["libc"]

[target.windows]
dependencies = ["winapi"]

Implementation

13.9 Diagnostics

Spec section: spec/25-conditional-compilation.md § Diagnostics

Error Messages

// Clear errors for cfg mismatch
#target(os: "linux")
@linux_only () -> void = ...

// On Windows:
// error: function `linux_only` is not available on this platform
//   --> src/main.ori:5:1
//   |
// 5 | linux_only()
//   | ^^^^^^^^^^ requires #target(os: "linux")
//   |
//   = note: current target: windows-x86_64
//   = help: this function is only available on Linux

Invalid Feature Names

#cfg(feature: "my-feature")
// error: invalid feature name "my-feature"
//   --> src/main.ori:1:15
//   |
// 1 | #cfg(feature: "my-feature")
//   |               ^^^^^^^^^^^^ feature names must be valid identifiers
//   |
//   = help: use "my_feature" instead

Implementation

13.10 compile_error Built-in

CROSS-REFERENCE: Section 11.8 also covers compile_error in the FFI context. Implementation should be done once and shared; avoid duplicate work.

Proposal: proposals/approved/additional-builtins-proposal.md

Syntax

@compile_error (msg: str) -> Never

Causes a compile-time error with the given message. Valid only in compile-time evaluable contexts.

Constraints

// ERROR: compile_error in unconditional code
@bad () -> void = compile_error(msg: "always fails")

// OK: compile_error in dead branch
@platform_check () -> void =
    if $target_os == "windows" then
        compile_error(msg: "Windows not supported")
    else
        real_impl()

// OK: compile_error in #target block
#target(os: "windows")
@platform_specific () -> void = compile_error(msg: "Not supported")

Implementation

Section Completion Checklist

Exit Criteria: Can build a cross-platform CLI tool with platform-specific implementations

Example: Cross-Platform Path Handling

// Platform-specific path separator using compile-time constant
@get_path_separator () -> str =
    if $target_os == "windows" then "\\" else "/"

// Platform-specific home directory using target attribute
#target(family: "unix")
@home_dir () -> Option<str> = Env.get(key: "HOME")

#target(os: "windows")
@home_dir () -> Option<str> = Env.get(key: "USERPROFILE")

// Platform-specific file operations
#target(family: "unix")
@set_permissions (path: str, mode: int) -> Result<void, Error> uses FileSystem = {
    // Unix chmod
    Unix.chmod(path: path, mode: mode)
}

#target(os: "windows")
@set_permissions (path: str, mode: int) -> Result<void, Error> uses FileSystem =
    // Windows handles permissions differently
    Ok(())

// Debug-only logging
#cfg(debug)
@debug_log (msg: str) -> void = print(msg: `[DEBUG] {msg}`)

#cfg(not_debug)
@debug_log (msg: str) -> void = ()