Replace this with your own README when you start working on your compiler.
Welcome to the Rx Compiler course! This repository provides a template from which you can build your own compiler for the Rx programming language. It includes official testcases, a test scaffold, and the G4 representation of Rx to get you started.
We strongly recommend that you fork this repository instead of downloading zips, in case we need to update the official testcases. After forking your copy, clone it to your local machine.
Initialize the testcases and REIMU submodules:
git submodule update --init --recursive
Python 3, xmake and any C++23 compiler is needed to build REIMU. Build REIMU separately from the project root before running tests:
xmake f -y -P vendor/REIMU -m release -o target/reimu
xmake -y -P vendor/REIMU
Rerun these commands after updating the REIMU submodule.
If you want to run default rustc test, install rustup, and run
rustup target add riscv32im-unknown-none-elf
In this course you can use any language to implement your compiler. Contact the TA if your language is not mainstream so that we can provide support for it on the Online Judge. For this reason, the template we provide here is language-agnostic. You will find:
- Testcases under
tests/. Official testcases reside undertests/officialand is a git submodule. You may add your own testcases undertests/custom. - A test runner. The
Makefileruns testcases using the compiler configured inconfig.mk. By default it uses your system rustc with theriscv32im-unknown-none-elftarget and executes generated assembly in REIMU. Replace the compiler commands inconfig.mkwith your own compiler commands to set up testing for your compiler. See Running tests for details.- Some auxiliary files (such as the reference compiler helper code in
crates/rx) help the default rustc produce assembly suitable for REIMU. Itssrc/entry.rsis compiled separately for each testcase and supplies the bare-metal entry point andBox/Vecimports. The library implements integer I/O through REIMU's libc, plus allocation and panic handling for bare-metal RV32 targets insrc/runtime.rs. The reference codegen command requests both assembly and a static library so rustc performs whole-program LTO and includes the runtime in the assembly. The extra{output}.ais a build artifact;RUNconsumes{output}afterscripts/strip_asm_debug.pyremoves debug metadata that REIMU cannot assemble. These helpers can be removed when you replace the Rust compiler commands.
- Some auxiliary files (such as the reference compiler helper code in
- REIMU under
vendor/REIMU, pinned as a git submodule. TheRUNcommand inconfig.mkinvokes it; the test runner does not depend on a particular simulator. - G4 grammar for Rx under
grammar/. You may use it to generate the lexer and parser for your compiler.
The Makefile is our unified entrypoint in accessing your compiler. You are expected to edit config.mk and hook in your compiler commands. In practice, specify in these fields:
The C++ frontend also provides these local checks:
make build # Compile src and link the ANTLR 4 C++ runtime
make lint # Syntax-check src with the same ANTLR runtime flags
make generate # Regenerate the C++ sources under src/generated
The ANTLR runtime is searched for in Homebrew and common system locations. Set ANTLR4_ROOT when it is installed elsewhere, for example make build ANTLR4_ROOT=/opt/antlr4-cpp-runtime. Set ANTLR4_JAR when regenerating with an ANTLR tool jar outside the script's default paths.
| Command Name | Purpose |
|---|---|
BUILD |
The command to build your compiler, can be empty. Must exit 0. |
SEMANTIC |
Check a complete program through semantic analysis. Exit 0 to accept or 1 to reject. |
CODEGEN |
Compile codegen and optimization testcases and write RV32IM assembly to {output} for the default RUN. |
RUN |
Run {output}. Optional {stdout} and {profile} placeholders select per-execution output and profiling files. |
For example, if your compiler supports --stage and -o and emits RV32IM assembly:
BUILD = cargo build --release
SEMANTIC = ./target/release/compiler --stage semantic {source}
CODEGEN = ./target/release/compiler --stage codegen {source} -o {output}
RUN = xmake run -P vendor/REIMU reimu -f {output} -o {stdout} -p {profile} 1>&2
REIMU starts at the assembly's global main symbol and provides its supported libc functions. -o {stdout} saves the program's output for comparison, -p {profile} saves its cycle profile, and 1>&2 sends simulator status messages to the stderr log. Do not add --silent when collecting cycles: REIMU suppresses profiles in silent mode. If your compiler needs additional runtime assembly, pass it with the program using -f {output},path/to/runtime.s.
Tests reside in tests/, and are organized into subdirectories. We recommend you follow the "namespace:test-suite:testcase" pattern. For instance, official:semantic:arrays is the arrays testcase in the semantic test suite of the official namespace.
Each testcase can have one or more source files, optional input and output files and a compulsory manifest.json file which defines the format of the testcase. See the official schema for details. The manifest's stage argument determines how the testcase runs: semantic uses SEMANTIC, while codegen and optimization use CODEGEN followed by RUN.
You are encouraged to add your own testcases under tests/custom. The runner will find them automatically.
Requirements for each kind of testcase:
| Testcase Type | Requirements |
|---|---|
| Semantic | The compiler must exit 0 or 1 to match compilation_success. Other exit codes, signals, and timeouts fail the case. |
| Codegen | Compilation must exit 0 and create {output}. Each io pair runs the artifact and the output must match the expected file. |
| Optimization | Same as Codegen, with cycle reporting when RUN provides {profile}. |
Testcases with type lex and parse will be skipped since we already provide the G4 grammar. Extend the Makefile if you want to DIY these stages.
Run from the project root:
make test
make test FILTER=official:semantic
make test FILTER=official:codegen:arrays,official:optimization
make test FILTER=custom
make test FILTER=official:optimization COMPILE_TIMEOUT=60 RUN_TIMEOUT=30
make test VERBOSE=true
Supported environment variables include:
FILTER, which selects directories undertests, using:between folder names and,between selections. OmitFILTERor leave it empty to run all supported tests.VERBOSE=true, which shows every test name and its duration instead of grouped progress. Defaults tofalse.COMPILE_TIMEOUTandRUN_TIMEOUT, which override the default timeouts for compilation and execution.
This repo comes with a GitHub Actions workflow that runs tests on every push and pull request. We advise turning it off while you develop the compiler and turning it back on when the compiler is ready for test-based development.
To disable the test, rename .github/workflows/test.yml to .github/workflows/test.yml.disabled. GitHub Actions will only discover *.yml and *.yaml files.