RIF - Retargetable ISA Foundry

RIF is a low-level framework designed to abstract the creation of toolchains (assemblers, linkers, compilers) without the rigid coupling to a specific CPU architecture. The premise is to transform ISA definitions into an automated production system through configuration tables and extensible plugins.

Architecture and Capabilities

The system decouples core logic (parser, linker, emitter) from hardware specifications, allowing architectures to be modeled via declarative .pack tables.

Retargeting via .pack: Full definition of registers, memory, sections, and emission rules. Instruction semantics and encoding are configured without modifying the core.
Integrated Pipeline: Complete orchestration of the lexer -> parser -> compiler -> linker workflow via a CLI that resolves inter-section dependencies, relocations, and final binary generation.
Extensibility via Python Plugins: The framework allows injecting custom logic for asset handling (fillables), pre-processing, or extended CLI commands, enabling each architecture to manage its own quirks (ROM padding, checksums, headers).
Developer Tooling: Automated generation of VS Code extensions (VSIX) with support for diagnostics, autocompletion, and syntax highlighting, optimizing the workflow without sacrificing the project's bare-metal nature.

Core Components

RIF abstracts complexity through a modular structure:

basics: Primitive layer for expressions, bitwise operations (bitcat, trunc, zext), symbol management, and alignment rules.
Architecture Support: Native implementations and plugins for GBA (ARM/Thumb), Atari 2600, and experimental support for AMD64.
Asset Management: Dedicated plugins for converting images, PCM audio, and bitmap fonts, featuring a caching system to optimize build times.

Integration and CLI

The tool is designed for professional/enthusiast development environments, enabling a complete lifecycle from the terminal:


    # Editable installation

    python -m pip install -e .


    # Build projects and invoke emulators via plugin

    python -m rif build examples/gba --plugin gba --name example

    python -m rif -pcli gba run examples/gba/gba.gba -nd

VSIX Automation

RIF includes an integrated extension generator that bundles metadata, TextMate syntax, and local documentation. This allows any defined architecture to immediately have a functional editing environment:


    python -m rif compile --vscode --ext .gbasm -icon icon.png --p gba sound fonts basics

For detailed technical references and internal API documentation, consult the local portal generated by the rif help command.