Arx Compiler CLI

The arxlang distribution installs the arx command. It can inspect frontend and lowering stages, compile native artifacts, run executables, and execute compiled tests.

Command forms

arx [input_file] [options]
arx run [input_file] [options]
arx test [paths ...] [options]

run is an alternate spelling of --run. test is a separate subcommand.

Inspection modes

arx --show-tokens program.x
arx --show-ast program.x
arx --show-llvm-ir program.x

These modes stop after printing the requested representation.

Build and run

arx program.x --output-file program
arx --run program.x
arx run program.x

The compiler emits an executable when the module defines main. Without a native entry point, or with --lib, it emits an object artifact instead.

Use arx --help for the complete option list and defaults rather than a copied flag catalog. Diagnostics and linker choices below have operational consequences.

Compiling multiple input files in one invocation is not currently supported. Use project-aware imports to compile a module graph from one entry file.

Output path

--output-file accepts the requested artifact path. If it is omitted, the compiler derives a name from the entry source file and otherwise falls back to a.out.

Link modes

The default auto mode uses the platform toolchain's default executable mode. pie and no-pie request explicit position-independent or non-PIE linking.

If a linker defaults to PIE but rejects an object relocation, use:

arx program.x --link-mode no-pie

IRx emits PIC-compatible objects by default. Explicit link modes are primarily toolchain compatibility controls.

Diagnostics

Expected lexer, parser, semantic, lowering, native compilation, and linking failures exit with status 1. Human-readable diagnostics go to standard error by default. Unexpected internal failures produce ARX-INTERNAL-001 without exposing exception details and exit with status 70. Compiler developers can opt in to the original Python exception and traceback with --traceback.

Use --diagnostic-format json for one versioned JSON document on standard error:

{
  "diagnostics": [
    {
      "code": "ARX-PARSE-001",
      "column": 7,
      "end_column": null,
      "end_line": null,
      "hint": null,
      "line": 4,
      "message": "expected expression",
      "module": null,
      "notes": [],
      "phase": "frontend",
      "severity": "error"
    }
  ],
  "schema_version": 1
}

JSON mode covers expected compiler-phase failures and sanitized internal failures. Argument usage errors remain argparse text with exit status 2. Consumers must reject unsupported schema_version values instead of guessing field semantics.

Tests

The arx test subcommand has its own discovery and execution options. See Compiled Tests.

API boundary

CLI argument handling lives in Arx. Semantic diagnostics, LLVM lowering, artifact building, and runtime feature activation are provided by IRx.