9. Execution / tools overview

This block specifies the rok compiler rokc, the front-end rok, and the execution environments (REPL / Jupyter kernel). It covers how the two engines (JIT / AOT) and the three user surfaces (REPL / Jupyter / direct execution of AOT output) defined in Execution engines and user surfaces are implemented.

Tool surface

The tool surface is organized as follows.

rok  (front-end, cargo-like)
  │   new / init, add / remove / update / deps (rok.rokon, rok.lock), env, toolchain
  │   build / check / run / test / bench / emit / fmt / lint / doc / clean / repl / lsp / demangle
  │        └── resolve deps, then call rokc ... --extern <dep roots>
  ▼
rokc  (compiler)
  │
  ├── build / run
  │   ├── rokc build      : AOT compile - .rok source to .a / executable
  │   ├── rokc run        : AOT compile then run immediately
  │   ├── rokc test       : collect + build the #[test] harness (rok test runs it)
  │   ├── rokc bench      : collect + build the #[bench] harness (rok bench runs it)
  │   ├── rokc check      : type / diagnostics only (no native build)
  │   └── rokc clean      : remove build artifacts
  │
  ├── tools
  │   ├── rokc fmt        : formatter
  │   ├── rokc lint       : linter
  │   ├── rokc doc        : API documentation
  │   └── rokc lsp        : LSP server (IDE integration)
  │
  ├── interactive
  │   ├── rokc repl       : terminal REPL (each cell runs once)
  │   └── rokc jupyter    : Jupyter kernel (REPL cell session + ZMQ)
  │
  ├── debug / diagnostic
  │   ├── rokc demangle   : symbol demangle
  │   ├── rokc rokhir-text  : ROKHIR interface text dump
  │   └── rokc inspect    : package inspect
  │
  └── rokc version / help

rokls  (= rok lsp, for editors)
librokr.a  (runtime, rokr)

The toolchain consists of the compiler rokc (the counterpart of rustc), the cargo-style front-end rok, the editor LSP executable rokls, and the runtime librokr.a. rok owns the manifest rok.rokon / rok.lock, dependencies, environments and the toolchain pin; build and tool commands are delegated to rokc with the resolved dependency packages attached via --extern (9.10). There are no separate tools (rok-fmt etc.).

Implementation of the two engines

The two engines defined in Execution engines and user surfaces are divided as follows.

JIT engine  ──  used by rokc repl / jupyter
AOT engine  ──  used by rokc build / run / test

Both engines go through the same compile pipeline (rok-hir → rok-mir → standard MLIR) and diverge only after the last intermediate representation. See Execution engines and user surfaces and Compile pipeline for details.

Implementation of the three user surfaces

The three user surfaces and the commands that implement them are:

surface              command
────────             ──────
REPL                 rokc repl
Jupyter              rokc jupyter        (invoked by Jupyter, not directly)
AOT direct exec      rokc build → run artifact

The implementation of each surface is covered in the following documents.

Package build output

A library package of a source unit compiles to libfoo.a and the interface foo.rokhir.

foo/
├── src/
│   ├── lib.rok              <- input
│   └── ...
       v rokc build
foo/target/debug/
├── libfoo.a                 <- artifact (static archive)
├── foo.rokhir                 <- interface (ROKHIR)
├── build/                   <- intermediates (foo.o, ...)
└── ...

The per-profile layout is defined in 9.2.15, and the archive format in Package archive.

ROKHIR: portable IR for generic functions

Generic functions must be monomorphized at the call site, so binary code alone is not enough. An interface file, ROKHIR, therefore sits next to the library. ROKHIR holds the package source with concrete function bodies stripped (because monomorphization takes the AST as input).

The detailed format is defined in ROKHIR format.

Single dependency: `librokr.a`

Build output consists of the user package's libfoo.a, the runtime librokr.a, and the standard libraries librok_*.a. There are no further dependencies beyond external OS libraries.

The detailed build flow is defined in AOT build pipeline.

Edit this page on GitHub

#9. Execution / tools overview

#Contents

#Tool surface

#Implementation of the two engines

#Implementation of the three user surfaces

#Package build output

#ROKHIR: portable IR for generic functions

#Single dependency: librokr.a