CREXX

CREXX is a modern implementation of the REXX language built as a compiler-to-bytecode toolchain. Source programs are compiled to cREXX assembler, assembled into rxbin bytecode, optionally linked into a deployable image, and run by the CREXX virtual machine.

Current documentation baseline: crexx-1.0.0-beta.2.

What Is Included

The core toolchain is:

• rxc: compiles cREXX source to .rxas assembler
• rxas: assembles .rxas to .rxbin bytecode
• rxlink: combines one or more .rxbin modules into a linked image
• rxvm / rxvme: executes rxbin bytecode
• crexx: driver for common compile, assemble, link, and run workflows
• rxcpack: packages bytecode images as C source for native executable builds

The Release 1 beta line focuses on the implemented Level B language surface, the bytecode toolchain, core standard libraries, host integration, and packaging on the supported desktop platforms. rxdb exists as an experimental debugger prototype and is not yet part of the stable release surface.

Build

cmake -S . -B cmake-build-debug
cmake --build cmake-build-debug
ctest --test-dir cmake-build-debug --output-on-failure

The build creates the toolchain under cmake-build-debug/bin.

Parser-mode and syntax-highlighting support use DSL Syntax Highlighter (DSLSH). If a sibling checkout exists at ../DSL-Syntax-Highlighter, CMake uses it. Otherwise CMake fetches the configured DSLSH repository and tag.

Useful DSLSH options:

cmake -S . -B cmake-build-debug -DDSLSH_GIT_TAG=<tag-or-commit-sha>
cmake -S . -B cmake-build-debug -DDSLSH_PREFER_LOCAL=OFF

Run A Program

For the usual workflow, use the crexx driver:

cmake-build-debug/bin/crexx path/to/program.crexx

The individual stages are also available:

cmake-build-debug/bin/rxc path/to/program.crexx
cmake-build-debug/bin/rxas path/to/program.rxas
cmake-build-debug/bin/rxvm path/to/program.rxbin

Current source convention: .crexx is the canonical cREXX source extension. When rxc is given an extensionless initial source name, it falls back to .crexx. .crx is also accepted, .rexx remains supported for explicit Classic/compatibility sources, and an arbitrary extension on the initial source is searched for same-extension imports.

Documentation

• Release notes summarize the beta 2 scope, signing status, and known limitations.
• Release 1 plan tracks the fixed-date path to Release 1, including scope tiers, gates, and provisional issue owners.
• Release documentation is the main entry point for current as-built user and technical documentation.
• Roadmap collects future direction and non-release commitments separately from current technical documentation.
• Documentation map explains which documentation area to use and how much authority each area has.
• Level B tutorial teaches practical Level B for Rexx programmers with tested examples.
• Language reference covers the implemented language surface.
• Programming guide covers tools, running programs, host integration, plugins, and practical workflows.
• Agent and maintainer notes capture implementation facts used by contributors and coding agents.
• Compiler internals contain technical notes for compiler maintainers.
• Project wiki is for vision, direction, and history. It is not the current technical reference.

Contributing

For repository-specific working rules, start with AGENTS.md. It lists the current implementation references to trust before changing compiler logic, syntax, runtime behaviour, or Level B source.