Packages

Package Manifest (braid.toml)

Every Braid package is defined by a braid.toml manifest file at the root of the project. This file declares the package name, version, entrypoint, and dependencies.

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

[dependencies]
braid_std = "1.0"

Manifest Fields

The [project] section supports the following fields:

• name — The package name used in imports
• version — Semantic version string
• entrypoint — Path to the main source file (defaults to src/main.br)

[project]
name = "webapp"
version = "2.3.1"
entrypoint = "src/app.br"

[dependencies]
braid_web = "0.5"
braid_db = "1.2"

Dependencies

Dependencies are listed in the [dependencies] section with name and version. The Braid package manager resolves and downloads them from configured registries.

[project]
name = "api-server"
version = "0.1.0"

[dependencies]
braid_http = "1.0"
braid_json = "0.8"
braid_router = "1.2"

Building Packages

Use braidc build to compile your package into a .bx bytecode artifact. This packages the compiled code along with metadata.

braidc build src/main.br -o out.bx

The .bx format includes a header with magic bytes (BRDC), version, target kind, payload size, and the compiled payload data.

// .bx bytecode header layout
Offset  Size  Field
0       4     Magic: 'BRDC'
4       4     Version
8       4     Target kind
12      4     Payload size
16      n     Payload data

Running Packages

Execute a package directly from source or from a compiled bytecode artifact.

# Run from source
braidc run src/main.br

# Run compiled bytecode
braidc run out.bx

# Build and run in one step
braidc run main.br

Example: Full Package Layout

// braid.toml
[project]
name = "calculator"
version = "0.1.0"
entrypoint = "src/lib.br"

[dependencies]
braid_math = "1.0"

// src/lib.br
fn add(a: int, b: int) -> int {
    return a + b;
}

fn multiply(a: int, b: int) -> int {
    return a * b;
}

// tests/test_lib.br
fn test_add() -> bool {
    let result = add(2, 3);
    return result == 5;
}

Package Resolution

When importing from a package, Braid looks up the package by its manifest name and resolves the file path relative to the package root. The import pathcalculator.lib maps to the lib module inside thecalculator package.

// Importing from another package
import calculator.lib;

fn main() {
    let sum = calculator.lib.add(10, 20);
    print(sum);
}