28. Documentation

Configuration Reference

braid.toml Project Configuration

Every Braid project uses a braid.toml file in the project root to declare project metadata, entry points, and dependencies.

Basic Project

[project]
name = "myapp"
version = "1.0"

Full Configuration

[project]
name = "llm-trainer"
version = "0.2.0"
entrypoint = "src/main.br"

[dependencies]
libs = ["m", "pthread"]
modules = ["std.io", "std.math"]

[build]
target = "turbo-vm"
optimization = "O3"
ccodegen = true

[gpu]
backend = "cpu"      # "cpu", "cuda", or "vulkan"
memory_pool_size = "1GB"

Junction App Configuration

[project]
name = "mywebapp"
version = "1.0"

[server]
port = 8080
host = "0.0.0.0"

[storage]
engine = "memory"     # "memory", "file", "sqlite"

Frontend Project Configuration

[project]
name = "myfrontend"
version = "1.0"

[frontend]
framework = "bond"
styling = "blend"
routing = "link"
state = "merge"

CMake Build Flags

These flags control the Braid compiler and runtime build configuration when building from source.

Flag	Values	Default	Description
`BRAID_ENABLE_CPU_ONLY`	ON/OFF	ON	Disables GPU backends, enables CPU-specific optimizations (ternary matmul, hierarchical attention, local learning, CPU streaming, memory pools). When ON, defines `BRAID_ENABLE_CPU_ONLY=1` on the runtime library and builds CPU test targets.
`BRAID_ENABLE_CUDA`	ON/OFF	OFF	Enables `gpu_cuda.cu` compilation. Defines `BRAID_CUDA`. Requires CUDA toolkit.
`BRAID_ENABLE_VULKAN`	ON/OFF	OFF	Enables `gpu_vulkan.c` and `gpu_common.c`. Defines `BRAID_VULKAN`. Requires Vulkan SDK.
`CMAKE_BUILD_TYPE`	Release/Debug	Release	Standard CMake build type. Release adds `-O3 -mavx2 -mfma -march=native`.

Environment Variables

The following environment variables affect Braid toolchain behavior at runtime.

Variable	Description
`BRAID_PATH`	Root directory for Braid standard library and runtime includes
`BRAID_LIB_PATH`	Extra library search path for extern FFI linking
`BRAID_MODULE_PATH`	Colon/semicolon-separated list of directories to search for `.br`/`.bx` modules
`BRAID_LOG_LEVEL`	Runtime logging verbosity: `debug`, `info`, `warn`, `error`

PATH Setup

After building, add the build output directory to your PATH so braidc is available globally:

# Linux / macOS
export PATH=$PATH:/path/to/braid/build/tools/braidc
export BRAID_PATH=/path/to/braid/braid-lang
export BRAID_MODULE_PATH=$BRAID_PATH/lib/std

# Windows PowerShell
$env:PATH += ";C:\path\to\braid\build\tools\braidc\Debug"
$env:BRAID_PATH = "C:\path\to\braid\braid-lang"
$env:BRAID_MODULE_PATH = "$env:BRAID_PATH\lib\std"

BLAS Configuration

BLAS libraries are auto-detected by the build system. When found, BRAID_BLAS is defined and the BLAS libraries are linked into all executables. The detection order is: openblas via pkg-config, then blas via pkg-config, then CMake's find_package(BLAS).

LLVM Configuration

LLVM is auto-detected via find_package(LLVM). When found (LLVM_FOUND), the JIT module is compiled and BRAID_LLVM_JIT is defined. The build links against LLVM_LIBRARIES (core, orcjit, native).

# Force LLVM directory
cmake -B build -DLLVM_DIR=/usr/lib/llvm-18/lib/cmake/llvm