\ | /
-     -
 / | \

RADIANCE

Radiance is a small statically-typed systems language designed for the Radiant[0]
computer system (https://radiant.computer). It currently targets RISC-V (RV64).

The compiler is self-hosted: written in Radiance, it compiles to RISC-V and
runs inside a RISC-V emulator on x86-64 platforms.

Currently, the Radiance compiler supports most of the R' language. See
https://radiant.computer/system/radiance/prime/ for more information on R'.

[0]: https://radiant.computer

REQUIREMENTS

  * Linux on x86-64
  * Make
  * Radiant's RISC-V Emulator
    (https://code.radiant.computer/emulator/)

BUILDING

  The compiler is self-hosted, so building from source requires bootstrapping
  from a seed binary. A known-good compiler is checked into the repository.

  The Radiant emulator is required to run the compiler and build process
  on x86-64. The build process will look for it in $PATH, unless $RAD_EMULATOR
  is set to its location:

      export RAD_EMULATOR=~/bin/emulator

  Then, build the compiler:

      make

  This uses the emulator to run the seed binary (`seed/radiance.rv64`) which
  compiles the self-hosted compiler source to produce `bin/radiance.rv64.dev`.

  To update the seed to a new fixed point:

      make seed

  This iterates self-compilation stages until two consecutive stages produce
  identical output, proving the compiler faithfully reproduces itself. See
  `seed/README` for full details on the seed workflow, verification, and
  how to handle breaking changes.

USAGE

  Compile a Radiance program:

      emulator -run bin/radiance.rv64.dev \
          -pkg example -mod example.rad -o example.rv64

  Run a compiled binary:

      emulator -run example.rv64

GENERICS

  Records, unions, and free functions declare ordered type or integer
  parameters between `⟨` and `⟩`:

      union Maybe⟨T⟩ { None, Some(T) }
      record Buffer⟨const N: u32⟩ { data: [u8; N] }
      fn first⟨T⟩(left: T, right: T) -> T { return left; }

  Concrete data and function applications use the same syntax.
  Every concrete application reachable at run time must be covered by an
  explicit package-level monomorphization root and its dependency closure:

      instantiate Maybe⟨u32⟩, first⟨u32⟩;

  Rooted generic functions add generic callees and nested data applications to
  the specialization closure. For declarations with only type parameters,
  calls may omit the generic argument list when local parameter and result
  evidence selects one already-rooted specialization; inference never creates
  a root. Integer arguments are compile-time expressions. The compiler checks
  each argument against its parameter's declared type. A declaration with
  an integer parameter requires a complete argument list.

  Type parameters may have trait bounds. Calls through those bounds use
  static instance dispatch:

      trait Less { fn (&Less) less(other: &Self) -> bool; }
      fn minimum⟨T: Less⟩(a: T, b: T) -> T {
          if a.less(&b) { return a; }
          return b;
      }

  `Self` is the concrete instance type in trait signatures. Opaque trait
  objects remain dynamic. The compiler rejects traits whose `Self` usage is
  not object-safe. `instance` declares a trait implementation. `instantiate`
  requests generic monomorphization.

  Generic symbols follow ordinary module visibility. A root may reference an
  exported template in another module by its qualified name:

      use containers;
      instantiate containers::Maybe⟨u32⟩;

  Duplicate roots share one package-wide specialization.

  Unsupported by design: generic traits, instances, or methods; associated
  types; overlapping instances; user-defined specialization; arbitrary
  compile-time execution; inferred roots; and higher-kinded types. The compiler
  diagnoses wrong arity or argument kind, unsatisfied or ambiguous bounds,
  missing roots, incomplete or conflicting inference, recursive layout,
  expanding dependency chains, and implementation-limit overflow.

TESTING

  Run all tests:

      make test

  Individual test suites:

      make std-test    # Standard library tests
      make lower-test  # IL lowering tests
      make asm-test    # RV64 code generation tests

PROJECT STRUCTURE

  seed/            Seed compiler binary and update tooling
  compiler/        Self-hosted compiler entry point
  lib/std/         Standard library
  lib/std/lang/    Compiler modules
  lib/std/arch/    Architecture backends
  test/            Test harnesses
  scripts/         Utility scripts
  vim/             Vim syntax files

EDITOR SUPPORT

  Vim syntax files for Radiance (.rad) and RIL (.ril) are in the vim/ folder.
  Copy them to ~/.vim/syntax/ for syntax highlighting.

LICENSE

  Licensed under the MIT License,
  Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer)