rxc - the \crexx{} Compiler

Command Line Options

\fontspec{IBM Plex Mono} \begin{shaded} \small \obeylines \splice{rxc -h | sed “s/&/\and/g”} \end{shaded} \fontspec{TeX Gyre Pagella}

Import Search Roots

rxc now separates automatic import discovery into two root classes:

• source roots, searched for .rexx project sources
• binary roots, searched for .rxbin, optional .rxas, and .rxplugin

The primary source root is the directory of the source file being compiled. If the source file name does not include a directory, the compiler uses the working location from -l. Additional source roots can be supplied with -s, using a semicolon-delimited list.

Binary roots are controlled separately with -i. The compiler always includes the executable directory in the binary-root set so deployed libraries remain visible without adding them explicitly. -i can be repeated, and repeated -s options are accumulated in the same way.

Search order is:

1. primary source root
2. extra -s source roots
3. binary roots for .rxbin
4. binary roots for .rxas when --import-rxas is enabled
5. binary roots for .rxplugin

This keeps same-project source imports preferred over deployed binary artifacts, while stopping the compiler from treating every binary directory as a source tree.

Import Discovery Notes

Automatic .rxas import scanning is now disabled by default. It can be re-enabled with --import-rxas for workflows that intentionally use assembler modules as import sources.

For source imports, rxc performs a cheap header scan before doing a full parse. That scan reads the leading options, namespace, and import clauses so the compiler can reject namespace-mismatched source files early and avoid unnecessary full validation work.

Within a single binary root, when multiple artifacts share the same module stem, the compiler keeps only the freshest candidate. If timestamps tie, .rxbin wins over .rxas.

\section{Inline Assembler} On page \pageref{inlineAssembly} the inline assembler function of the \crexx{} compiler is discussed. This enables the incorporation of \code{rxas} assembler instructions into a \textsc{Rexx} source file.

Optimizer

The compiler can do a number of optimizations that can make the execution of a program much faster; the next example shows how an operation can be done at compile time, to avoid instruction scheduling and execution at runtime:

\lstinputlisting[language=rexx,label=fpow_example]{examples/fpowtest.rexx} \fontspec{IBM Plex Mono} \splice{rxc examples/fpowtest} \splice{rxas examples/fpowtest} \begin{shaded} \small \obeylines \splice{rxvm examples/fpowtest} \end{shaded} \lstinputlisting[language=rxas,label=fpow_example_rxas,caption=optimization]{examples/fpowtest.rxas} \fontspec{TeX Gyre Pagella}

This works because, for a large number of operations, the \code{rxc} compiler can assume the result is never going to be different, and will determine that result during compile time. In the same vein, results from operations that are not displayed or handled further in the program, will lead to the operation being skipped entirely.

Debugging and Validation

For compiler developers and advanced users, rxc provides debug modes that enable internal validation of the AST and Symbol table and stress‑test the fixpoint loop.

• -d2 — Structural Validator
  • Runs the built‑in AST/Symbol validator between passes.
  • Catches parent/child inconsistencies, broken bi‑directional symbol links, and illegal scope parentage.
• -d3 — Validator + Idempotency Stress Test
  • Everything in -d2, plus: the fixpoint loop is forced to run extra iterations and selected walkers are invoked multiple times per iteration.
  • Proves walker idempotency and overall convergence.

Example:

# Validate (structure only)
rxc -d2 -o out input.rexx

# Stress idempotency and convergence
rxc -d3 -o out input.rexx

Notes:

• These modes are for diagnostics and do not change user‑visible semantics.

• All walkers inside the fixpoint loop are designed to be idempotent.

• See also: compiler/docs/fixpoint_idempotency_and_scope.md for design details.

• See also: compiler/docs/testing.md for information on regression testing and how to update golden files.