Frequently Asked Questions
General
Is Braid production-ready?
Braid is currently at version 0.1 (prototype). The core compiler pipeline (lex, parse, AST, C codegen, bytecode VM) is functional, but MLIR and LLVM backends are stubs. The standard library is minimal. We recommend using Braid for experimentation, prototyping, and contributing to the language itself, but not yet for production systems.
What platforms does Braid support?
Braid supports Linux, macOS, and Windows. The C codegen path requires GCC. The bytecode VM runs on any platform with a C compiler. GPU support (CUDA) is experimental and requires an NVIDIA GPU.
How do I install Braid?
Build from source: cd compiler/cpp && cmake -B build && cmake --build build. The braidc binary will be at build/tools/braidc/braidc.
What file extensions does Braid use?
.br for source files, .bd for scripts, .bx for bytecode artifacts.
How does Braid compare to Mojo?
Both target the ML/AI space with Python-like syntax and advanced compilation. Mojo is built on MLIR and targets Python ecosystem compatibility with a focus on GPU acceleration. Braid is a broader-scope language that adds dialectical programming (Diameter), a full web framework (Junction), and systems programming capabilities. Braid uses ARC while Mojo uses ownership. Braid's tensor support is native syntax ([[ ]]) while Mojo uses Python library types.
Can I use Braid for web development?
Yes. Braid includes the Bond UI framework (component-based, like React), Blend styling system, Link router, Merge state management, and Junction full-stack framework. These are currently evolving alongside the language core.
Does Braid have a package manager?
Not yet. Packages are imported via relative path imports (import std.io). A package manager is planned for a future release.
How do I report bugs?
Report bugs at the Braid GitHub repository (braid-os organization). Include the Braid source file, the command you ran, and the expected vs actual output.
Is there a Braid community?
The Braid community is growing on GitHub (braid-os/braid-os). We have discussions, issue tracking, and contribution guidelines in the repository.
Language
Braids uses ARC — can I opt into GC?
Braid's runtime includes a generational GC that can be enabled for certain object types. ARC is the default, but GC can be activated per-object via runtime configuration. The cycle detector runs periodically to handle reference cycles.
Does Braid have generics?
Generic type syntax (Type<SubType>) is supported in the parser, but Hindley-Milner inference provides parametric polymorphism without explicit generics in many cases. Full generic support is being developed.
Can I call C libraries from Braid?
Yes, via extern fn declarations. These declare C functions that are linked at compile time. Example: extern fn sqrt(x: float) -> float.
Can I call Braid from C?
The C codegen output produces valid C that can be included in C projects. Additionally, the .bx bytecode format is designed for embedding in any application.
Does Braid support async/await?
Async/await syntax is planned via the std.async module. The parser supports spawn semantics for green threads. Async runtime is in development.
What is a Diameter?
A Diameter is a dialectical programming construct that models tension between two opposing poles (thesis/antithesis). It supports evolve() to advance the state and observe() to read tension, state, or pole values. See the Language Tour for examples.
How does @autograd work?
The @autograd decorator marks a function for automatic differentiation. When called, it builds a computation graph, computes the forward pass, and can .backward() to compute gradients with respect to trainable parameters. This is integrated with the tensor runtime.
Can I use Braid for embedded systems?
Braid's C codegen output is portable C code that can be cross-compiled for embedded targets. The runtime footprint depends on which features are used. The bytecode VM is also embeddable.
How does Braid handle strings?
Strings are first-class UTF-8 values with + for concatenation. They are heap-allocated ObjString objects managed by ARC with automatic deallocation.
What is the difference between native and extern?
extern fn declares external C functions linked at compile time. native fn declares functions implemented in the BraidVM runtime for FFI calls at runtime via OP_INVOKE_FFI.
Compiler and Tooling
What is the Braid compiler pipeline?
Source (.br) → Lexer → Parser → AST → Type Checker → C Codegen (or LLVM/MLIR backends) → GCC → Native executable. The pipeline can be run step-by-step with braidc parse/ast/ir/ccodegen/run.
Does Braid have an LSP or IDE support?
LSP support is planned. Currently, the compiler provides parse errors and type checking diagnostics via the CLI.
How do I debug Braid programs?
Use braidc parse for syntax validation, braidc ast to inspect the AST, and braidc ir to see the intermediate representation. Runtime debugging is via print() statements currently.
Can Braid output LLVM IR?
The braidc llvm command is a stub that outputs mock LLVM IR. The LLVM backend is under development.
What is the .bx bytecode format?
A binary format with magic bytes BRDC, version field, target kind (e.g., LLVM IR), payload size, and payload data. Can be executed with braidc run file.bx.