Overview of the Toolchain

cRexx is built as a small set of separate tools with visible boundaries. That is deliberate: users can inspect the generated assembly, assemble it directly, link modules, disassemble bytecode, or package a program for native deployment.

\begin{wrapfigure}{l}{0.4\textwidth} \includegraphics[scale=0.3]{charts/buildflow.pdf} \end{wrapfigure} \fussy

The common flow is:

1. rxc compiles CREXX source to .rxas assembly.
2. rxas assembles .rxas assembly to .rxbin bytecode.
3. rxvm, rxvme, rxbvm, or rxbvme executes one or more .rxbin files.
4. rxlink optionally combines modules into a linked image with a shared constant pool.
5. rxcpack can package a linked image as C data for native executable builds.

The crexx driver wraps the usual compile, assemble, run, link, and package steps for day-to-day use.

Source, Assembly, and Bytecode

Source files are UTF-8 text. New cRexx source normally uses .crexx, with .crx as a short alias. .rexx remains the compatibility/classic extension. The compiler also accepts an arbitrary non-reserved initial source extension for that compile. Toolchain artifacts are less flexible: RXAS assembly uses the fixed .rxas suffix and RXBIN bytecode uses the fixed .rxbin suffix. The compiler output is RXAS assembly:

```bash rxc hello.crexx

The assembler output is RXBIN bytecode:

```bash <!--rxas1.sh-->
rxas hello.rxas

RXBIN is the module format consumed by the VM, linker, disassembler, and packager.

For rxc, rxas, and rxlink, -o names an output stem/path unless it already ends in the tool’s fixed artifact suffix. For example, rxas -o app writes app.rxbin, rxas -o app.rxbin writes app.rxbin, and rxas -o app.debug writes app.debug.rxbin.

Module Discovery

The compiler separates source discovery from binary discovery:

• source roots contain .crexx, .crx, .rexx, and any arbitrary extension used by the initial source file for this compile
• binary roots contain .rxbin, optional .rxas, and .rxplugin files

Use rxc -s path to add a source import root and rxc -i path to add a binary import root. The crexx driver exposes the same distinction for compilation. The directory of the source being compiled is searched for source imports, but it is not searched for .rxbin imports unless it is also passed with -i. That avoids stale generated bytecode shadowing the source you are editing.

When a source file has no options level... clause, .crexx, .crx, and arbitrary initial extensions default to Level G; .rexx defaults to Level C.

The runtime library path is separate. Use crexx -l... or the VM’s own library loading rules when a compiled program must load bytecode or plugins at runtime.

Linking

rxlink combines one or more .rxbin modules into a linked image with one shared constant pool. This reduces duplicate constants and resolves module and interface-provider relationships up front while preserving the module records needed by the VM loader.

Use rxlink for release-style deployable images and for native packaging.

Native Packaging

Native packaging uses rxlink before rxcpack. The linked image is serialized to C data and linked with the VM runtime library by the platform C toolchain. The generated executable contains the program image and the runtime pieces selected by the build.

Static and dynamic plugin choices depend on how the project was built. Do not assume every distribution contains every optional native plugin.