Quartz Build Guide

Quick Reference

# From /Users/mathisto/projects/quartz

# 1. Rebuild the self-hosted compiler (using bootstrap C compiler)
/Users/mathisto/projects/quartz-bootstrap/bin/quartz build self-hosted/quartz.qz --stdlib-path std > /tmp/quartz_rebuild.ll

# 2. Link the compiler binary
clang -O2 -x ir /tmp/quartz_rebuild.ll -o self-hosted/bin/quartz-new2

# 3. Compile a Quartz program
self-hosted/bin/quartz-new2 build <source>.qz --stdlib-path std > /tmp/output.ll

# 4. Link the compiled program
clang -O2 -x ir /tmp/output.ll -o /tmp/output

# 5. Run
/tmp/output

[!TIP] Use -O0 instead of -O2 when debugging segfaults to preserve stack frames. The -O2 warnings about “loop not vectorized” are harmless.

Architecture

graph LR
    A[Bootstrap C Compiler] -->|compiles| B[Self-Hosted Compiler]
    B -->|compiles| C[User Programs]
    C -->|linked by| D[clang/LLVM]
    style A fill:#2d4a2d,stroke:#4a7a4a
    style B fill:#2d3a5a,stroke:#4a6a9a
    style C fill:#4a2d4a,stroke:#7a4a7a

Component	Path	Built By
Bootstrap C compiler	/Users/mathisto/projects/quartz-bootstrap/bin/quartz	make in quartz-bootstrap
Self-hosted compiler	self-hosted/bin/quartz-new2	Bootstrap C compiler
User programs	/tmp/*.ll → /tmp/<binary>	Self-hosted compiler + clang

Entry Points

What	Entry File
Self-hosted compiler	self-hosted/quartz.qz
QSpec demo	spec/qspec_demo.qz
Standard library	std/ (auto-discovered via --stdlib-path)

Project Structure

quartz/
├── self-hosted/           # Self-hosted compiler source
│   ├── quartz.qz          # Main entry point
│   ├── resolver.qz        # Module resolver
│   ├── frontend/          # Lexer, parser, tokens
│   ├── middle/            # Type inference, typechecker
│   └── backend/           # MIR lowering, LLVM codegen
│       ├── mir.qz         # MIR (Mid-level IR) lowering
│       ├── codegen.qz     # LLVM IR emission
│       └── codegen_main.qz
├── std/                   # Standard library
│   ├── colors.qz          # ANSI colors
│   ├── qspec/             # QSpec test framework
│   │   ├── matchers.qz    # expect/assert matchers
│   │   ├── runner.qz      # Test runner (describe/it)
│   │   ├── formatter.qz   # Output formatting
│   │   └── property.qz    # Property-based testing
│   └── qspec.qz           # QSpec entry (re-exports)
├── spec/                  # Test specifications
│   └── qspec_demo.qz      # QSpec dogfood tests
└── self-hosted/bin/       # Compiled binaries
    └── quartz-new2        # Current self-hosted compiler

Common Tasks

Rebuild Self-Hosted Compiler After Code Changes

# Step 1: Compile with bootstrap
/Users/mathisto/projects/quartz-bootstrap/bin/quartz build \
  self-hosted/quartz.qz --stdlib-path std > /tmp/quartz_rebuild.ll

# Step 2: Link (overwrites existing binary)
clang -O2 -x ir /tmp/quartz_rebuild.ll -o self-hosted/bin/quartz-new2

Run QSpec Tests

# Compile
self-hosted/bin/quartz-new2 build spec/qspec_demo.qz --stdlib-path std > /tmp/qspec.ll

# Link
clang -O2 -x ir /tmp/qspec.ll -o /tmp/qspec_demo

# Run
/tmp/qspec_demo

Debug a Segfault

# Compile to IR
self-hosted/bin/quartz-new2 build <source>.qz --stdlib-path std > /tmp/debug.ll

# Link with debug mode (no optimization)
clang -g -O0 -x ir /tmp/debug.ll -o /tmp/debug_binary

# Run under lldb
lldb -b -o 'run' -o 'bt' /tmp/debug_binary

# Check for unknown intrinsics (warns about missing codegen handlers)
grep "WARNING: Unknown intrinsic" /tmp/debug.ll

# Check module init
grep "@__qz_module_init" /tmp/debug.ll