Compiler Usage

Part of: Reef Language Reference Last reviewed on version: 0.8.0

Overview

The Reef compiler (reefc) compiles Reef source files (.reef) to native executables. It uses a multi-stage compilation pipeline: parsing, type checking, monomorphization, C code generation, and finally invokes GCC to produce the final binary.

Quick Start

# Compile a single file
reefc hello.reef

# Compile and run immediately
reefc run hello.reef

# Create a new project
reefc new myproject
cd myproject
reefc build

Commands

Default: Compile File

reefc <file.reef>

Compiles a single Reef source file to an executable. The output name matches the input filename without the .reef extension.

Examples:

reefc hello.reef              # Produces: hello
reefc hello.reef -o greet     # Produces: greet

build

reefc build [options]

Builds the project in the current directory. Looks for entry point in order:

1. main.reef
2. src/main.reef

Creates build/ directory and outputs executable named after the project directory.

Examples:

cd myproject
reefc build                   # Produces: build/myproject
reefc build --keep-c          # Keep generated C file for debugging
reefc build --emit-c          # Generate C code only (no binary)

run

reefc run [file.reef] [options]

Compiles and immediately executes. If no file is specified, looks for main.reef or src/main.reef.

Examples:

reefc run                     # Run project (main.reef or src/main.reef)
reefc run hello.reef          # Compile and run specific file
reefc run hello.reef -v       # Verbose compilation then run

The exit code from the executed program is returned.

new

reefc new <project_name>

Creates a new Reef project with standard directory structure:

project_name/
├── reef.toml           # Project manifest
├── README.md           # Project readme
├── .gitignore          # Git ignore file
├── src/
│   └── main.reef       # Entry point
├── tests/              # Test files
└── docs/               # Documentation output

Project naming rules:

• Must start with a lowercase letter
• Can contain: a-z, 0-9, _, -

Examples:

reefc new myapp
reefc new web-server
reefc new game_engine_2

init

reefc init

Initializes a reef.toml in the current directory without creating a full project structure. Useful for adding Reef to an existing project.

Example:

cd existing-project
reefc init

clean

reefc clean

Removes build artifacts:

• build/ directory and contents
• Stray .c files in current directory

doc

reefc doc [options]

Generates API documentation from source files. Extracts comments before declarations and produces Markdown files.

Options:

Examples:

reefc doc                     # Generate to docs/
reefc doc --output api        # Generate to api/
reefc doc --private           # Include private items

info

reefc info

Shows resolved paths and configuration:

• Compiler version
• Runtime path
• Standard library path
• Environment variables

Useful for debugging installation issues.

doctor

reefc doctor

Diagnoses installation health. Checks:

• Runtime library availability
• Standard library availability
• GCC availability
• Required system libraries

Returns exit code 0 if healthy, 1 if issues found.

help

reefc help
reefc --help
reefc -h

Displays usage information.

version

reefc version
reefc --version
reefc -V

Displays version information.

Compilation Options

Output Control

Examples:

reefc hello.reef -o greet           # Custom output name
reefc --check hello.reef            # Type check only
reefc hello.reef --emit-c           # Generate hello.c
reefc hello.reef --keep-c           # Compile but keep hello.c
reefc hello.reef -v                 # Verbose output

External Libraries

Examples:

reefc reefzip.reef -lz                    # Link zlib
reefc app.reef -lssl -lcrypto             # Link OpenSSL
reefc app.reef --obj utils.o              # Link object file
reefc app.reef --cflags "-Wl,-rpath,/lib" # Custom linker flags

Auto-detected libraries: The compiler automatically detects and links required libraries based on imports:

• import net.tls → Links libreef_tls.a plus the system -lssl -lcrypto (OpenSSL >= 3.0, dynamically linked at runtime)
• import ui.backend.x11 → Links X11

Runtime Options

Hosted targets (with libc):

• amd64, x86_64, x64 - x86-64 Linux/macOS
• arm64, aarch64 - ARM64 Linux/macOS
• riscv64 - RISC-V 64-bit

Baremetal targets (freestanding):

• amd64-baremetal, x86_64-baremetal
• arm64-baremetal, aarch64-baremetal
• riscv64-baremetal

Examples:

reefc --runtime /opt/reef/runtime hello.reef
reefc --target arm64 hello.reef
reefc --target amd64-baremetal kernel.reef

Baremetal Options

Examples:

# Minimal kernel
reefc kernel.reef --target amd64-baremetal --entry _start

# With custom linker script
reefc kernel.reef --target amd64-baremetal --linker-script kernel.ld

# Generate C code for manual compilation
reefc kernel.reef --no-stdlib --emit-c

GC and Runtime Options

Examples:

# Simple program without GC overhead
reefc simple.reef --no-gc

Environment Variables

Priority order:

1. Command-line flags (--runtime)
2. Environment variables
3. Default paths (relative to compiler location)

Example setup:

export REEF_HOME=/opt/reef
# Or set individually:
export REEF_STDLIB=/opt/reef/reef-stdlib
export REEF_RUNTIME=/opt/reef/reef-runtime

Exit Codes

When using reefc run, the exit code from the executed program is returned.

Compilation Pipeline

The compiler processes source files through these stages:

1. Lexing & Parsing - Converts source text to AST
2. Module Loading - Resolves and loads imported modules
3. Type Checking - Validates types and semantics
4. Monomorphization - Expands generic types
5. C Code Generation - Produces C source code
6. C Compilation - Invokes GCC to produce binary

Use --verbose to see each stage:

reefc hello.reef -v

Project Configuration (reef.toml)

Projects can be configured with a reef.toml file:

[package]
name = "myproject"
version = "0.1.0"
author = "Your Name <email@example.com>"
description = "A Reef project"
license = "MIT"
url = "https://github.com/user/myproject"

[build]
entry = "src/main.reef"
output = "myproject"
output_dir = "build"
source_dirs = ["src"]

[docs]
output = "docs"
include_private = false

See 010_PROJECT_STRUCTURE.md for details.

Common Workflows

Development Cycle

# Edit code, then:
reefc run                     # Quick test
reefc build                   # Production build

Debugging Compilation

reefc hello.reef --emit-c     # Inspect generated C code
reefc hello.reef --emit-ast   # Inspect parsed AST
reefc hello.reef --keep-c -v  # Verbose + keep C file

Type Checking Only

reefc --check src/*.reef      # Check multiple files

Linking External Libraries

# Compression (zlib)
reefc reefzip.reef -lz

# Cryptography (OpenSSL)
reefc crypto_app.reef -lssl -lcrypto

# Custom C code
gcc -c myhelper.c -o myhelper.o
reefc app.reef --obj myhelper.o

OS/Kernel Development

# Generate C for baremetal
reefc kernel.reef --target amd64-baremetal --emit-c

# Full baremetal build
reefc kernel.reef --target amd64-baremetal \
    --linker-script kernel.ld \
    --entry _start \
    -o kernel.elf

Troubleshooting

"Reef runtime not found"

Set the environment variable or use --runtime:

export REEF_HOME=/path/to/reef
# or
reefc --runtime /path/to/reef-runtime hello.reef

Run reefc doctor to diagnose.

"Module not found"

Check that:

1. The file exists at the expected path
2. REEF_STDLIB is set correctly
3. Module name matches filename

Compilation Errors

Use verbose mode to see which stage failed:

reefc hello.reef -v

For C compilation errors, keep the C file:

reefc hello.reef --keep-c
# Then inspect the .c file

Previous: 000_INDEX.md Next: 010_PROJECT_STRUCTURE.md