Skip to content

Volume 20: Toolchain and Build System

1. Introduction

This volume defines the official Rethon toolchain, compiler workflow, build model, project structure, executable generation, library generation, and RETPAK integration. It describes the toolchain overview, rethonc compiler, compiler responsibilities, source files, project structure, build model, build targets, executable generation, library generation, entry points, module compilation, dependency resolution, RETPAK integration, testing integration, FFI build considerations, platform targets, diagnostics and build output, future extensions, and summary.

This document is part of the official Rethon Language Specification. It is normative rather than descriptive. Implementations, tooling, documentation systems, and other source-processing tools shall treat the rules in this volume as authoritative.

This volume does not define backend code generation internals, linker implementation details, optimizer internals, or platform-specific toolchain mechanics beyond the source-level contract described here. It defines the source-level build and compilation direction for Rethon.

Rethon is Python-inspired in language philosophy and Python-first in surface syntax where practical. It uses rethonc as the official compiler, RETPAK as the official package manager, retpak.toml as the project manifest, .re as the source file extension, .rpk as the package archive extension, static typing, and AOT compilation.

2. Toolchain Overview

The Rethon toolchain shall consist of at least the compiler, package manager, standard library, and related source-level build utilities.

The compiler is one component of the official toolchain. Runtime refers to execution-time mechanisms and behavior defined only where relevant in other specification volumes.

rethonc shall be responsible for compilation.

RETPAK shall be responsible for package and dependency workflows.

The standard library shall provide the general-purpose APIs used by ordinary code.

The toolchain shall remain source-readable and conservative.

Example commands:

rethonc src/main.re
retpak build
retpak test
retpak publish

The toolchain shall support ordinary application development without requiring ordinary source code to know backend implementation details.

3. rethonc Compiler

rethonc shall be the official Rethon compiler.

rethonc shall compile .re source files according to the language specification.

rethonc shall support AOT compilation as part of the language's initial direction.

rethonc shall be the source-level entry point for turning Rethon source into executables, libraries, or other compiled outputs supported by the toolchain.

Example:

rethonc src/main.re

rethonc shall remain compatible with the language's static typing, module model, and package model.

4. Compiler Responsibilities

rethonc shall be responsible for at least the following source-level tasks:

  • parsing Rethon source
  • validating syntax
  • validating types
  • resolving modules and imports
  • checking visibility rules
  • checking generic and protocol constraints
  • applying ordinary language diagnostics
  • supporting executable and library builds
  • cooperating with RETPAK for dependency resolution
  • honoring FFI declarations and build boundary rules

rethonc shall not expose backend internals as part of its source-level contract.

rethonc shall remain conservative in its diagnostics and build behavior.

5. Source Files

Rethon source files shall use the .re extension.

A .re file shall contain Rethon source code.

Example:

src/main.re
src/math/geometry.re

Source files shall be compiled according to module and package rules.

The source extension shall be used consistently by tooling and project conventions.

6. Project Structure

A Rethon project shall be represented by a project manifest named retpak.toml.

A project shall ordinarily contain source files, package metadata, and any other assets needed by the project's build and dependency workflow.

A typical project structure may resemble:

retpak.toml
src/
    main.re
    app.re
tests/
    test_app.re

The specification does not require a single filesystem layout beyond the use of the manifest and the source extension.

The build and package model shall remain source-level and shall not depend on hidden layout conventions beyond what tooling needs to locate manifest and source files.

7. Build Model

The build model shall be source-oriented and AOT-oriented.

A build shall compile Rethon source into an executable, library, package artifact, or other supported output target.

A build shall use the manifest and dependency information needed to resolve the project.

A build shall remain compatible with the module system, visibility rules, and package model.

Example:

rethonc src/main.re

The specification does not require a single build pipeline implementation.

The build model shall remain readable and conservative.

8. Build Targets

The toolchain shall support build targets for at least executables and libraries.

A build target shall describe the intended compiled output of a project or module set.

Build targets shall be selected explicitly or inferred from project configuration in a source-readable way.

The specification does not require any particular backend artifact format in this volume.

Example conceptual targets:

  • executable
  • library
  • test binary
  • FFI library wrapper

Build targets shall remain compatible with RETPAK workflows and the package model.

9. Executable Generation

Executable generation shall be supported.

A project with an entry point shall be compilable into an executable.

Example:

rethonc src/main.re --target executable

Executable generation shall be AOT-oriented and shall remain compatible with the language's static type system and module model.

The specification does not define linker internals or platform-specific binary layout.

10. Library Generation

Library generation shall be supported.

A project shall be compilable into a reusable library artifact when the project is intended to expose reusable modules and public APIs.

Example:

rethonc src/text.re --target library

Library generation shall preserve public API boundaries and visibility rules.

Libraries shall remain compatible with package distribution through RETPAK.

11. Entry Points

A project entry point shall identify the module or function intended to start program execution.

The entry point shall be source-level and explicit in project configuration or compiler invocation.

Example:

rethonc src/main.re

The entry point model shall remain compatible with modules as source-level namespaces.

The specification does not require a single fixed main syntax beyond the language's ordinary function model and project conventions.

12. Module Compilation

Modules shall be compiled as source-level units within the project build.

Module compilation shall respect module namespaces, imports, visibility, and dependency order.

Example:

module app:
    public def run() -> None:
        ...

A module shall not require special compilation semantics beyond those needed to preserve source-level correctness.

Modules shall remain the units of namespace and compilation organization.

13. Dependency Resolution

Dependency resolution shall cooperate with RETPAK.

The compiler shall use manifest and package metadata to resolve project dependencies in a source-level manner.

The specification does not prescribe resolver internals, backtracking algorithms, or network transport details.

Dependency resolution shall remain consistent with module imports and package boundaries.

Example:

[dependencies]
text-utils = "1.4.0"

The compiler shall not need to infer package dependencies from arbitrary source analysis alone.

14. RETPAK Integration

RETPAK shall participate in builds as the package and dependency workflow layer.

RETPAK shall support tasks such as initialization, dependency management, building, testing, and publishing.

Example commands:

retpak init
retpak add package_name
retpak remove package_name
retpak update
retpak build
retpak test
retpak publish

rethonc shall handle compilation, while RETPAK shall handle package workflows and dependency preparation.

RETPAK integration shall keep the build model source-readable and conservative.

15. Testing Integration

Testing shall be supported as a first-class build and workflow concern.

The toolchain shall support running tests through the package and build workflow.

Example:

retpak test

Tests shall compile and run in a way that respects the language's type system, module model, and package dependencies.

Testing integration shall not require special runtime semantics beyond ordinary compilation and execution support.

16. FFI Build Considerations

FFI build considerations shall remain explicit.

Projects that use native bindings or external libraries may require additional build configuration, but those details shall remain outside the core compilation model.

The toolchain shall support FFI-aware builds without exposing ABI internals in the source-level specification.

Example:

rethonc src/native_wrapper.re

FFI build integration shall cooperate with the FFI volume and package model.

17. Platform Targets

Platform targets shall be represented in a source-level and tooling-friendly way.

The specification does not prescribe a single target triple or platform descriptor format in this volume.

Platform-specific build behavior shall remain abstracted where practical.

Tooling and manifests may describe target platforms or environment constraints, but the source-level build model shall remain readable and not over-specified.

18. Diagnostics and Build Output

Build diagnostics shall be readable, source-oriented, and actionable.

Diagnostics shall point to source files, lines, and declarations where practical.

Diagnostics shall support ordinary compiler workflows without exposing backend internals unnecessarily.

Example of diagnostic intent:

error: type mismatch in src/main.re:12

Build output shall be conservative and suitable for ordinary developer workflows.

The specification does not prescribe exact formatting, but it does require clarity and source orientation.

19. Future Extensions

This volume defines the current direction for the Rethon toolchain and build system, but future specification work may refine the model in carefully controlled ways.

Possible future extensions include:

  • richer build target metadata
  • additional project layout conventions
  • improved incremental build behavior
  • more detailed target-platform descriptors
  • expanded test-runner integration
  • additional FFI build metadata
  • workspace-level build orchestration

Any future extension shall preserve the current direction:

  • rethonc remains the official compiler
  • RETPAK remains the official package manager
  • retpak.toml remains the project manifest
  • .re remains the source file extension
  • .rpk remains the package archive extension
  • builds remain source-oriented and AOT-oriented
  • dependency resolution cooperates with RETPAK
  • diagnostics remain readable and source-oriented
  • backend internals remain unspecified at the source level

20. Summary

rethonc shall be the official Rethon compiler.

RETPAK shall handle package workflows, and retpak.toml shall represent the project.

.re shall be the source file extension, and Rethon shall support AOT compilation into executables and libraries.

The compiler shall validate syntax, types, modules, visibility, generics, and dependency-related source correctness.

RETPAK shall participate in dependency preparation and package workflows, while rethonc shall handle compilation.

Diagnostics shall remain readable and source-oriented.

The toolchain shall therefore provide a conservative, Python-first, statically typed, package-aware build model without over-specifying backend internals.