Raz Manual/Toolchain & Build

Toolchain & Build

Toolchain and Build Options

The active compiler, command-line output controls, module search roots, and GNU C++ configuration.

Raz Gen2 Manual·Toolchain & Build
Item Current interface Behavior
Active compiler compiler/razc/bin/razc Self-hosted Gen2 compiler emitting C++17.
Compiler source compiler/razc/compiler.raz and compiler/razc/src/ Modular Raz source compiled by the active compiler.
C++ output --emit-cpp <path> or -o <path> Writes generated C++ to the requested destination.
Module search -L, --module-path, --std-path Adds module lookup roots.
Build definitions --define NAME=VALUE Exposes supported literal build definitions to Raz source; accepted literal grammar is restricted.
Target labels --target-os, --target-arch, --target-compiler Supplies target metadata; does not by itself create cross-compilation support.
Native compiler Root options Configures CXX=g++ and default C++ flags.

Authoritative build configuration

The root options file currently contains:

CXX=g++
CXXFLAGS="-O2 -pipe -static -s -DNDEBUG -ffunction-sections -fdata-sections -Wl,--gc-sections"

These flags request optimization, static linking, symbol stripping, release behavior, function/data sectioning, and linker garbage collection. Actual support may vary by platform and GNU toolchain.

Project rule: ordinary native builds should load options and pass its CXXFLAGS to the configured GNU C++ compiler. A different compiler or flags require an explicit, documented special case.

Build and inspect a compiler candidate

Build a candidate separately from the active compiler. Inspect its version and run the required tests before manually replacing the active binary. 

mkdir -p compiler/razc/build
./compiler/razc/bin/razc compiler/razc/compiler.raz \
  --emit-cpp compiler/razc/build/compiler.cpp

. ./options
set -f
"$CXX" -std=c++17 $CXXFLAGS -I library/raz \
  compiler/razc/build/compiler.cpp -o compiler/razc/build/razc-candidate
set +f

./compiler/razc/build/razc-candidate --version
Release safety: do not replace compiler/razc/bin/razc automatically as part of a successful build. Candidate review, test results, and version/checksum updates should be deliberate.

Compiler driver and build orchestration

The longer-term driver should provide a clear interface between the user and the core compiler: resolve modules and libraries, collect native dependencies, apply target and optimization settings, and expose generated C++ for inspection. The core compiler and the build orchestration layer must remain separate responsibilities.

The current project build uses GNU C++ on Unix-like development systems. Platform-specific paths and shell behavior should belong in build tooling (for example, a Makefile or launcher), rather than being hard-coded as assumptions in the language frontend. The present target labels are metadata, not a promise of complete cross-compilation support.

Questions to settle

  • Define development and production profiles without making options non-authoritative.
  • Specify output naming and cleanup for compiler candidates and generated C++.
  • Update version metadata atomically during releases.
  • Define the exact GNU C++ version baseline and supported host platforms.