bux-lang/docs/BuildAndTest.md

Build and Test Guide

This guide covers building the Bux bootstrap compiler, creating projects, and running tests.

---

Prerequisites

• Nim (1.6+) — for building the bootstrap compiler
• C compiler (gcc, clang, or cc) — for the C backend
• Make

On Debian/Ubuntu:

sudo apt-get install nim gcc make libssl-dev

On macOS:

brew install nim gcc make openssl

Note: The Std::Crypto module requires OpenSSL (-lcrypto). The build system links it automatically.

---

Building the Compiler

# Release build
make build

# Development build (no optimizations, faster compile)
make dev

The output is a single binary: buxc (bootstrap compiler in Nim).

The self-hosted compiler buxc2 is built from compiler/selfhost/*.bux sources via:

make selfhost

This compiles buxc2 using the bootstrap compiler. The self-hosted compiler generates C code and invokes cc to produce native binaries.

---

Creating a Project

# Create a new package in a new directory
./buxc new myproject
cd myproject

This generates:

myproject/
├── bux.toml
└── src/
    └── Main.bux

bux.toml

[Package]
Name    = "myproject"
Version = "0.1.0"
Type    = "bin"

[Build]
Output = "Bin"

---

Building and Running

# Type-check without building
./buxc check
./buxc check ./myproject

# Build
./buxc build
./buxc build ./myproject

# Build and run
./buxc run
./buxc run ./myproject

# Run tests
./buxc test

# Clean build artifacts
./buxc clean

Build output goes to build/ by default.

---

Running Tests

Compiler Tests

make test

This runs:

• Lexer unit tests
• Parser unit tests
• Semantic analysis unit tests
• HIR lowering unit tests
• Integration tests (buxc new, buxc --version)

Example Programs

make test-examples

Compiles and runs all programs in examples/.

Individual Example

mkdir -p examples_pkg/hello/src
cp examples/hello.bux examples_pkg/hello/src/Main.bux
# Create bux.toml manually or use `buxc new`
cd examples_pkg/hello && ../../buxc run

---

Project Layout

bux/
├── src/              # Bootstrap compiler source (Nim)
│   ├── main.nim      # Entry point
│   ├── cli.nim       # CLI commands
│   ├── lexer.nim     # Tokenizer
│   ├── parser.nim    # Parser
│   ├── sema.nim      # Semantic analysis
│   ├── hir.nim       # High-level IR
│   ├── hir_lower.nim # AST → HIR lowering
│   ├── c_backend.nim # HIR → C code generation
│   └── ...
├── library/           # Standard library
│   ├── Std/
│   │   ├── Io.bux
│   │   ├── Array.bux
│   │   ├── String.bux
│   │   ├── Map.bux
│   │   ├── Fs.bux
│   │   ├── Mem.bux
│   │   ├── Set.bux
│   │   ├── Path.bux
│   │   ├── Math.bux
│   │   ├── Task.bux
│   │   └── Channel.bux
│   ├── runtime.c     # C runtime shim
│   └── io.c          # C I/O functions
├── examples/         # Example programs
├── tests/            # Unit tests (Nim)
├── docs/             # Documentation
└── Makefile

---

Debugging

Verbose Output

./buxc build -v

Inspecting Generated C (bootstrap)

./buxc build
cat build/main.c

Inspecting Generated C (self-hosted)

cd _selfhost && ../buxc build
cat build/main.c

Common Errors

Error	Cause	Fix
stdlib directory not found	buxc can't find library/	Run from project root or set correct path
duplicate symbol 'bux_alloc'	Multiple stdlib modules declare same extern	Only declare in one module
C compilation failed	Generated C has errors	Check build/main.c for issues

---

Adding a New Example

1. Create examples/myexample.bux
2. Add myexample to EXAMPLES in Makefile
3. Run make test-examples

---

Development Workflow

# After making changes to the compiler:
make build
make test

# If tests pass, run examples:
make test-examples