# CLI

```sh
ry check [PATHS]               # report problems
ry fmt [PATHS]                 # format files in place
ry migrate data-table [PATHS]  # rewrite data.table code as DataFrame code
ry run [FILE]                  # run an R script on ry's runtime; without one, open ry's console
ry R [FILE]                    # the same on GNU R
ry load [PATH]                 # load an R package from source, run code against it, and exit
ry test [PATH]                 # run a package's testthat tests against the loaded package
ry document [PATH]             # write a package's Rd files and NAMESPACE with roxygen2
ry build [PATH]                # build a package's source tarball; --aot installs it compiled, --aot --exe makes a script an executable
ry install [PATH]              # build and install a package
ry debug-adapter               # a debugger for editors, over stdio
ry server                      # the language server, over stdio; your editor starts it
ry debug COMMAND               # developer aids for working on ry itself
```

`format` and `lsp` are aliases for `fmt` and `server`. Only `run`, `R`, `load`, `test`, `document`,
`build`, `install` and `debug-adapter` run R, and all of them except `R` run it on ry's runtime.
[How ry finds R](#how-ry-finds-r) says where that runtime and base R come from.

## check

```sh
ry check                       # the current directory
ry check R/model.R             # report on one file
ry check --output json         # one JSON object per finding, on stdout
ry check --min-severity error  # ignore warnings, also for the exit code
ry check --fix                 # apply the safe fixes, then report what remains
ry check --fix --unsafe-fixes  # also apply fixes that guess, such as a spelling suggestion
ry check --annotate            # write inferred types as annotations, then report what remains
```

Naming a file limits what is reported, not what the check sees: ry reads the whole
[project](/reference/configuration.md#which-file-applies) the file belongs to, so a name defined in
another file resolves however you spell the paths. When every path you name is in the package's
`R/`, as in `ry check R`, the tests and scripts are left out, because they add nothing to the
package and cannot change its findings. A file matched by `exclude` is analyzed only when you name
it.

`ry check` reads `.R` files and the R chunks of `.Rmd`, `.qmd`, and `.Rnw` documents. Findings go to
stderr and the one-line summary to stdout. A terminal gets color and Unicode box drawing, `NO_COLOR`
turns off only the color, and a pipe gets plain ASCII. [Diagnostic
codes](/reference/diagnostic-codes.md) shows how to read a finding.

A finding with a mechanical fix says so under its snippet, and the summary counts them:

```text
  help: Change to `TRUE` (`ry check --fix` applies it)
...
3 problems in 1 file
2 fixable with `ry check --fix` (1 more with `--unsafe-fixes`)
```

`--fix` rewrites the files in place and then reports what is left. It applies only safe fixes, which
keep what the code means: `T` to `TRUE`, `=` to `<-`, and removing a trailing comma. A fix that
guesses what you meant, such as changing a misspelled `totl` to `total`, is unsafe and needs
`--unsafe-fixes` as well. One fix can expose another, so ry repeats the pass until nothing changes. A file with a syntax
error is left unchanged, because its fixes were worked out on a guess at what the broken code means.
The editor offers the same fixes as quick fixes.

`--annotate` writes the inferred type of each unannotated top-level function and binding in the
named files, inline or as a `#:` comment as [`inline-annotations`](/reference/configuration.md#inline-annotations)
says, prints how many it added, and then reports what is left.
[Strict mode](/guide.md#strict-mode) shows it at work. A binding
whose type inference cannot write down, such as one involving `Unknown`, is skipped.

### The check cache

`ry check` records its findings in `.ry_cache/check.json` at the project root, and the next run
reuses them for every file whose findings cannot have changed. On a 300,000-line package, a repeat
check of an unchanged project takes about 0.1 s instead of 1.2 s. After an edit inside a function
body, only the edited file and the files whose check read it are checked again, which takes about
0.45 s. Any other change checks every file again: an edit outside a function body (a new top-level
name, a changed signature, a class definition), an added or removed file, a different `ry.toml`,
`NAMESPACE`, `DESCRIPTION` or stub, or a different ry binary. An edit inside a body that changes
what the rest of the project sees also checks every file, for example one that adds `UseMethod`,
`<<-`, `assign`, `library`, `setClass` or a `#: @type` declaration. A directory with no `ry.toml`
or `DESCRIPTION`, such as one holding a single downloaded script, gets no cache.

A run checks only the files it was asked about, so `ry check R` records no findings for the files
in `tests/`, and a later `ry check` checks those files. The strict check of `ry load` asks about
`R/` alone in the same way and shares the record.

The output is the same with or without the cache. `--no-cache` checks every file without reading or
writing the record, and deleting `.ry_cache/` is always safe. ry writes a `.gitignore` into the
directory, so the record stays out of version control.

The language server reads the same record when it starts. If the record still holds for a file
under `R/`, opening that file shows its recorded findings at once, before the server has analysed
the project, and the server's own analysis replaces them when it settles. A file that changed since
the check, or whose findings depend on one that did, starts without them. Any edit drops the
recorded findings of every file, and a record written by a different ry binary is never read.

## fmt

```sh
ry fmt           # rewrite files in place
ry fmt --check   # name the files that would change, and exit 1 if any would
ry fmt --diff    # show the changes without writing them, and exit 1 if any
ry fmt --range 3-8 R/report.R   # format only lines 3 to 8 of one file
ry fmt --verbose # also print how many bytes were formatted, and how fast
```

`--range` takes `LINE`, `START-END`, or `LINE:COLUMN-LINE:COLUMN`, counting from 1. It formats the
lines the range touches exactly as formatting the whole file would, at the indentation the file
already uses, and leaves every other line alone. A statement is laid out as one unit, so a line
just outside the range changes when it belongs to a statement the range reaches into. A range that
starts past the file's last line is an error, and an end past it stops at the last line.

In `.Rmd`, `.qmd`, and `.Rnw` files, `ry fmt` formats each R chunk on its own and leaves the prose,
the fences, inline `` `r expr` `` code, and indented chunks (such as one inside a list item) exactly
as written. `exclude` does not apply to it. All of its output goes to stderr. The rules it applies
are in [Formatting rules](/reference/formatting-rules.md).

## migrate

```sh
ry migrate data-table             # print the rewrites for the project as a diff
ry migrate data-table R/ --write  # rewrite the files under R/ in place
```

`ry migrate data-table` rewrites data.table code as [DataFrame](/reference/dataframes.md) code, applying
the same rewrites the editor offers as code actions. It takes files and directories, or the whole
project when given none. Without `--write`, it prints a diff of each file to stderr and leaves the
files alone. Either way it prints a one-line summary to stdout and exits 0. Each form it rewrites,
and each it leaves alone, is listed in
[Moving from data.table](/reference/from-data-table.md#rewriting-automatically).

## run and R

```sh
ry run script.R a b   # run on ry's runtime; the script reads a and b with commandArgs(TRUE)
ry run                # ry's console
ry run -i setup.R     # run setup.R, then open the console
ry R script.R         # run on GNU R
ry R                  # a GNU R console with ry's highlighting and completion
```

Options go before the file, because everything after the file is the script's: `ry run script.R --help` hands `--help` to the script. A top-level error
stops a script with exit status 1, as with `Rscript`, and so does `q(status = 1)`. The output is
only what the script prints, with no startup banner.

Before anything runs, both commands check the script, and the console checks each command, against
the project's `ry.toml`. They print the [inline annotation](/guide.md#inline-annotations)
warnings, and in [strict mode](/guide.md#strict-mode) they print every error and refuse code
that has one.

The runtimes differ in what they do with the annotations. ry's runtime turns them into [checks at
function boundaries](/reference/type-system.md#annotations-at-run-time), and GNU R runs the
script with them erased. ry's runtime is under construction: a script that calls something it
lacks stops with an error naming it, such as a missing `.Internal` or a native routine of a default
package. Base graphics, grid and device packages such as ragg draw as they do on GNU R. The
built-in `pdf`, `svg`, `postscript`, `png`, `jpeg`, `bmp` and `tiff` devices write their files when
the device closes or the script ends. They draw gradients, patterns, clipping paths, masks, groups
and even-odd fills except on `postscript`, which refuses them and drops semi-transparent colours
with a warning, as GNU R's does. Like GNU R's, `pdf` cannot repeat or reflect a gradient, and warns
and stops it at its ends instead. knitr and rmarkdown documents with plot chunks render. A script sees `interactive()` as `FALSE` on both runtimes, as under `Rscript`, and a console
sees `TRUE`.

Started inside an R package, either console [loads it](/reference/package-loading.md) and reloads what
changed before each command; `--no-load` turns that off. In the console:

- Tab completes names from the type checker's view of the code you typed, with each field's type.
  `--keybindings vi` switches to vi keys.
- Lines typed while a command runs are queued and run in order. Ctrl-C interrupts the command and
  discards the queue.
- `browser()` stops at a `Browse[1]>` prompt: `n` runs the next statement, `s` steps in, `f`
  finishes the function, `c` continues, `Q` quits, and `where` shows the call stack. In a script,
  `browser()` does nothing, as in a non-interactive R session.
- `?mean` and `help()` print R's help pages; `help_type = "html"` opens them in a browser.

`--keybindings` and `--no-load` apply only to a console, so passing either with a script is a usage
error. With `-i FILE`, the file is checked under its own name before the console opens, and a
strict-mode refusal exits 1.

With standard input piped (`echo '1 + 1' | ry run`), the console skips the editor, the prompt and
the banner, evaluates each line, prints the result, and exits 0 at the end of input. It behaves
like `R --no-echo`, except that it keeps going after an error.

### Compiling ahead of time

`ry run --aot script.R` compiles the script's typed functions before the script starts, so no
function compiles in the middle of the run. Without the flag, each typed function compiles at its
first call. The script prints the same either way, and its warnings and errors arrive at the same
points.

```r
total <- function(n: I64) -> I64 {
  sum <- 0
  for (i in List.range(1, n)) sum <- sum + square(i)
  sum
}
square <- function(x: I64) -> I64 x * x
cat("started\n", file = stderr())
print(total(10))
```

`RY_TYPED_LOG=1` prints each compilation on standard error. With `--aot`, both functions are
compiled before the script writes `started`:

```console
$ RY_TYPED_LOG=1 ry run totals.R
started
typed: compiled for [I64] -> I64 in 733 us
385i64
$ RY_TYPED_LOG=1 ry run --aot totals.R
typed: compiled for [I64] -> I64 in 1044 us
typed: compiled for [I64] -> I64 in 319 us
typed: compiled 2 functions ahead of time in 1419 us
started
385i64
```

A function compiles ahead when it is defined at the top level of the script as
`name <- function(...)` and each parameter's annotation says which values arrive from R: a number,
`Bool`, `Str`, a `List` of those, a tag union or a table such as `DataFrame` or
`DataFrame{price: double[]}`. The typed functions it calls compile with it, whatever their
parameters. A file the script sources into the global environment, as `source("helpers.R")` does,
compiles the same way when `source()` has read it, before any of it runs. These compile at their
first call instead:

- a function defined inside a block or another function, or in a file sourced any other way,
  such as by `sys.source()` or by `source(local = TRUE)` inside a function;
- a function of a package, unless the package's [typed code file](#build-and-install) holds it,
  in which case it runs code compiled at install. Under `--aot`, a package whose typed code file
  another build of ry wrote compiles its typed functions as it loads instead, and prints
  `ry: another build of ry installed rates, so its typed functions compiled as it loaded; reinstall it to compile them at install`;
- a function defined after the script set `options(keep.source = TRUE)`, or in a statement that
  holds a literal R warns about, such as `1.5L`;
- a top-level function with a record, tuple, `Dict`, `Set` or function parameter that no typed
  function compiled ahead calls;
- a function that calls a name the script binds to something else later. It was compiled for the
  first definition of the name, and compiles again at its next call after the rebinding;
- a function that converts an R value with `Num.from_r`, or with a `List.from_r` whose item type
  the checker does not know, such as `List.from_r(get("prices"))`. Its first call runs in the
  interpreter to see the type;
- a function that calls into a namespace R has not loaded yet, such as `tools::file_ext`. Loading
  a namespace runs its code, so the first call runs in the interpreter, which loads it.

[Typed code at run time](/reference/type-system.md#annotations-at-run-time) describes both waits.

Untyped R code is not compiled ahead of time. It runs in the interpreter and its hot functions
compile while the script runs, with or without the flag.

`--aot` needs a script and ry's runtime: `ry run --aot` without a file, `--aot` beside `-i`,
`--keybindings` or `--no-load`, and `--aot --runtime gnu-r` are usage errors.

### Profile summary

`ry run --profile-summary FILE script.R` runs the script and, when it ends, writes a Markdown
summary of where the time went to FILE. `ry load --profile-summary FILE -e CODE` profiles a package
load and the code after it, and `ry test --profile-summary FILE` a test run, the same way. Setting
`RY_PROFILE_SUMMARY=FILE` does the same for any session of ry's runtime. Only the process that
reads that variable is profiled: time spent in child processes (`callr`, `parallel`'s workers)
does not count.

To profile child processes too, set `RY_PROFILE_SUMMARY_DIR=DIR`. Every session of ry's runtime
that starts with the variable set writes its own summary to `DIR/ry-profile-<start>-<pid>.md` when
it ends, and child processes inherit the variable, so a CI job that runs several test processes,
each with its own workers, leaves one summary per process:

```sh
RY_PROFILE_SUMMARY_DIR=profiles ry load -e 'testthat::test_dir("tests/testthat")'
```

A process forked from a session (`parallel::mclapply`) writes no summary. The directory is created
if it does not exist, and a relative path is taken from the directory the session started in. When
both variables are set, the process that reads `RY_PROFILE_SUMMARY` writes to that file, and its
child processes write to the directory.

Only ry's runtime profiles: under `--runtime gnu-r` the flag and both variables have no effect.

The summary is meant to be shared from a private code base: it holds no source code, no names from
your code and no data. It lists:

- the time split after start-up: tier-0 bytecode, the AST evaluator, closure call setup, variable
  lookups past the inline caches, builtins, S3 and S4 method lookup, native code, condition
  handling, frame introspection (`sys.call`, `parent.frame`, `match.call`), garbage collection,
  JIT compilation and JIT-compiled code. The summary's own work, counting each collection's freed
  objects by type, is listed apart as "profile summary bookkeeping" rather than in garbage
  collection;
- base R's builtins by time and by number of calls;
- native code (`.Call`, `.External`, `.C`) by package. A package outside R's own, its
  recommended packages and the common CRAN dependencies ry benchmarks against is printed as
  `private-` and a hash of its name;
- event counts: closure calls, promises created and forced, S3 and S4 dispatches, conditions
  signalled, entries into compiled code and deoptimizations, collections and the peak memory in
  use. "JIT compilations" counts the compiles tier 1 finished, and "JIT compile attempts refused"
  the attempts it gave up on, leaving the body to tier 0;
- calls to closures of package namespaces other than base, and how many of them skipped the
  generic call protocol: the call ran natively or in a slot frame that never made its
  environment, and no argument was a promise;
- slot frames turned into environments, by what asked for the environment;
- complex assignments such as `names(x)[2] <- v` that built a call for their target, by the
  replacement functions and what the variable held. A replacement function that base R does not
  define is printed as "(a function)", and a class outside a short list of widely used ones
  (`data.frame`, `factor`, `Date`, `xts` and the like) as "an object";
- the refused compile attempts by reason, with the reasons `RY_JIT_LOG=1` prints beside each
  body it refuses (such as "the body runs too rarely to repay compiling it").

A run that compiled nothing reads, for a script whose only hot function is `function(x) x + 1`:

```
| JIT compilations | 0 |
| JIT compile attempts refused | 1 |
```

and its table of refusals names the reason, "the body does too little natively to repay entering
compiled code".

A private package's hash is keyed with a secret, so someone who guesses the name cannot confirm
the guess by hashing it. The key belongs to the project the session started in (the nearest
directory with `ry.toml`, `roughly.toml` or `DESCRIPTION`), so two summaries of one project on
one machine give a package the same label. ry draws the key at random the first time it profiles
the project and keeps it in your cache directory, under `ry/profile-keys/`, never inside the
project. A session outside any project uses one key for all such sessions. Set
`RY_PROFILE_KEY` to 32 hexadecimal digits to use that key instead, for example from a CI secret so
that runs on different machines agree. The summary's header names the key it used; when no key
file can be kept (no cache directory, or one ry cannot write to), the run uses a key of its own
and the header says why.

The time split comes from sampling what the runtime is doing once a millisecond, so a share below
about 1% of a short run is noise. Collecting it slows a run by up to about 7% (1% on the fastest
of three runs of the `timeseries` application workload, 7% on the median). Without the
option, the hooks cost one predictable branch each.

Setting `RY_PROFILE_STACKS=FILE` as well writes every sampled call stack to FILE, one line per
distinct stack and activity: the sample count, the activity (such as `builtin:c` or
`native:data.table`) and the closures from outermost to innermost as `owner::function`, joined
by `;`, where the owner is a namespace, `R_GlobalEnv` or `other`. Unlike the summary, these lines name your functions. `tools/bench/compare_profiles.py`
reads them beside a GNU R `Rprof()` file of the same run (the benchmark driver writes one when
`RY_BENCH_RPROF=FILE` is set) and compares the two engines closure by closure;
`development/design/codebase-gap.md` shows what it reports.

`ry repl` still works. It is the earlier name of `ry R`'s console (`ry run`'s with `--runtime ry`),
and it keeps its `-f FILE`, which is `ry R -i FILE`.

### Memory

ry's runtime collects garbage on GNU R's schedule, vectors of a megabyte or more go back to the
kernel when they die, and a dead large vector or list is freed at the next allocation once its
reference count reaches zero, without waiting for a collection. A script's peak memory is therefore
at or below GNU R's. These scripts from a CI machine that ran out of memory peak at (in MiB):

| Script | GNU R 4.3.3 | ry |
| --- | --- | --- |
| `id <- rep(1:1000, 50000)` | 239 | 239 |
| 20 rounds of `keep <- v > 0.5; s <- list(id[keep], v[keep])` over `runif(5e7)` | 1386 | 1097 |
| 20 rounds of `dt[v > 0.5]` on a 5e6-row data.table | 340 | 277 |

To trade time for a lower peak, for example to fit more test processes into a CI machine, set GNU
R's own variables, which ry's runtime reads at startup:

| Variable | Effect |
| --- | --- |
| `R_GC_MEM_GROW` | `0` to `3`, default `1`: how much headroom the heap keeps above the live data after a full collection. `0` keeps the least and `3` the most. |
| `R_GC_GROWFRAC` | `0.35` to `0.75`, default `0.70`: the share of the heap the live data must fill before the heap grows. |
| `R_GC_VGROWINCRFRAC`, `R_GC_GROWINCRFRAC` | `0.05` to `0.80`, default `0.2`: the share by which the heap grows. |

`R_GC_MEM_GROW=0` lowers the data.table script's peak from 277 to 239 MiB (GNU R: 282 MiB). It costs
time where many objects outlive a collection: on a generated package's 1,907 testthat tests it
runs 48 full collections instead of 5, and collecting takes 3.8 s of the 23 s instead of 0.7 s.
A value outside a variable's range is ignored, as on GNU R.

### Start-up image

ry's base R tree ships an image of the session as it stands once base R and the default packages
have loaded (`library/base/R/ry-start.<build>.image`, where `<build>` identifies the ry build),
and a start loads it instead of running base R's start-up code. On Linux an empty `ry run` script
takes about 30 ms from the image and about 90 ms without it (`RY_IMAGE=0`). The image is written
when ry is built, or when a ry build first starts over a base R tree that has none of its own, and
never by a running session. Several ry builds can share one base R tree: each keeps its own images
in it, and the tree keeps those of the four builds that wrote theirs most recently, plus any build
a running session uses.

Each start still runs the steps that read the environment: the C-level options, base R's profile,
and the `.onLoad` hooks of utils, grDevices and stats. So `EDITOR`, `R_LIBS`, `_R_RNG_VERSION_`
and the other variables they read take effect on every run, as they do on GNU R. A start runs the
slow way, with the same result, when it is interactive, sources a site or user profile (which
`ry run` never does and ry's `Rscript` does when one exists), or sets a variable that changes which
packages load or how: `R_DEFAULT_PACKAGES`, `R_TESTS`, `R_KEEP_PKG_SOURCE=yes`,
`_R_TRACE_LOADNAMESPACE_`, `_R_NO_REPORT_MISSING_NAMESPACES_`, `_R_METHODS_DONT_CHECKSUBCLASSES`
or `RY_METHODS_NATIVE`.

| Variable | Effect |
| --- | --- |
| `RY_IMAGE` | `0` turns the image off: every start runs the slow way. |
| `RY_IMAGE_LOG` | `1` prints `ry: image unused: <reason>` for each image a start or load could not use, and `ry: image written: ...` when a start writes its build's images. |

## load and server

`ry load` [loads the package](/reference/package-loading.md) at `PATH` (default: the one containing the
current directory) on ry's runtime, then runs each `-e EXPR` and the `-f FILE` script, and exits
like `ry run`. `ry load --r-entry` prints the R code that gives a plain R session the same
`load_all()`, for `source(pipe("ry load --r-entry"))`. `load_all()` is also available in the scripts
and consoles of `ry run` and `ry R`.

`ry server --debug` (or `RY_DEBUG=1`) adds internal analysis facts to hover, for working on ry itself.
No feature is experimental, so `--experimental-features` ignores every name with a warning
(`range_formatting` is always on).

## test

`ry test` loads the package at `PATH` the way `ry load` does and runs its `tests/testthat` files
with testthat, as `devtools::test()` does. testthat must be installed. A test file is one whose name
starts with `test` and ends in `.R` or `.r`, so `test-parse.R` and `test_parse.R` both count. The
output is testthat's own reporter's, and the command exits with `1` when a test fails or errors.

- `--filter REGEX` runs only the test files whose names match, as `devtools::test(filter =)` does.
  The pattern matches the name without a leading `test-` or `test_` and without the extension, so
  `--filter '^parse$'` selects `test-parse.R` and `test_parse.R`.
- `--reporter NAME` picks a testthat reporter, such as `summary`, `progress` or `check`.
- `--jobs N` (or `-j N`) runs the test files in `N` worker processes, one file at a time in each,
  and `--jobs 1` runs them in the `ry test` process. See [Parallel tests](#parallel-tests).
- `--watch` keeps running: after every edit under `R/`, `src/`, `data/`, `inst/`, `tests/`,
  `DESCRIPTION` or `NAMESPACE` it reloads only what changed (rebuilding compiled code after a
  `src/` edit), runs first the test files the edit can affect, and then the rest. It learns of
  edits from the operating system's file notifications, so it costs nothing while you type. A file is affected
  when you edited it, or when it mentions a function whose definition reaches a changed one. An
  edit to a helper or setup file, or a reload that has to run top-level code, reruns everything.

### Parallel tests

Workers are testthat's own parallel runner, so a package set up for it needs no change:
`Config/testthat/start-first` in `DESCRIPTION` orders the files, `testthat::is_parallel()` is
`TRUE` in a worker, and each worker runs `tests/testthat/setup*.R` and the helpers once. Each
worker is a separate R process, so test files must not depend on state another file leaves behind.

| You write | Files run in |
| --- | --- |
| `ry test --jobs 4` | 4 workers |
| `ry test --jobs 1` | the `ry test` process |
| `ry test`, and `DESCRIPTION` has `Config/testthat/parallel: true` and `Config/testthat/edition: 3` | one worker per core |
| `ry test` otherwise | the `ry test` process |

A run never starts more workers than it has test files, and one test file runs without workers.
Without `--jobs`, testthat's own switches apply as they do under `devtools::test()`: the
`TESTTHAT_PARALLEL` environment variable overrides `DESCRIPTION`, and `TESTTHAT_CPUS` or
`options(Ncpus =)` sets the worker count in place of the core count.

A worker loads the package the way `ry test` itself does, lazily and under the project's
`ry.toml`, so it needs neither pkgload nor every package in `Imports` installed. With
`--runtime gnu-r`, workers load the package with `pkgload::load_all()`, as under testthat alone.

`--profile-summary` measures one process, so it runs the files without workers, and combining it
with more than one job is an error.

## document

`ry document` loads the package at `PATH` the way `ry load` does and runs roxygen2 against the
loaded namespace, as `devtools::document()` does, writing the same `man/*.Rd` files and `NAMESPACE`
byte for byte. roxygen2 must be installed. `--roclet NAME` (repeatable) runs only the named
roclets, such as `rd` or `namespace`. Without it, the package's own roxygen options decide, and a
package that sets none gets `collate`, `namespace` and `rd`.

Three things make it faster than roxygen2 alone, without changing what it writes. The parsed
documentation blocks of each file are cached in ry's cache directory, so a run parses again only
the files whose content changed. The finished Rd text of every topic is cached too, so after an
edit only the topics that can have changed are rebuilt: those with a block in an edited file, those
that inherit from them (`@inheritParams` and the other `@inherit` tags) or share a `@family` with
them, and, every time, the package topic and any topic built from a block ry cannot track. A block
is tracked only when it documents a function defined right below it under a name without a dot (a
dotted name may become an S3 method when another file adds a generic) and uses none of the tags
that read other files or the namespace: `@eval`, `@evalRd`, `@evalNamespace`, `@template`,
`@templateVar`, `@example`, `@includeRmd`, `@describeIn`, `@method`, `@exportS3Method` and
`@R6method`. Every other topic is written from the cache. Finally, the steps of roxygen2 that
take time quadratic in the number of topics (collecting them, ordering them for `@inherit`, and
finding them by name) run in linear time.

The caches keep two things roxygen2 would recompute: the markdown links a block resolved against
installed packages, and documentation inherited from another package. After you install or remove
a package a link or an `@inherit` points at, edit the file or delete the cache, which lives in
`~/.cache/ry/roxygen/` (or under `$XDG_CACHE_HOME`).

## build and install

```sh
ry build                  # write ../<package>_<version>.tar.gz
ry build -o dist          # write it into dist/ instead
ry install                # install into the first library on .libPaths()
ry install -l ~/rlib      # install into ~/rlib
ry install --train tests  # train the package's code image on its tests
ry build --aot -l ~/rlib  # install, as ry install does
ry build --aot --exe main.R           # write the executable ./main
ry build --aot --exe main.R -o bin/app  # write it to bin/app instead
```

`ry build` writes the source tarball of the package at `PATH` (default: the one containing the
current directory), as `devtools::build()` does: it runs `R CMD build --no-resave-data
--no-manual`, rebuilds the vignettes unless you pass `--no-vignettes`, and prints the tarball's path
on stdout. The tarball goes beside the package directory unless `-o DIR` names another.

`ry install` installs the package as `devtools::install()` does: it builds a tarball without
rebuilding the vignettes in a temporary directory, installs it with `R CMD INSTALL`, and deletes the
tarball. `-l DIR` names the library, which is created if it does not exist. The package's dependencies must
already be installed.

Both run R's own `build` and `INSTALL` scripts on ry's runtime, from ry's R home, so compiled code is
built against ry's libR, as `ry run` loads it. `--runtime gnu-r` (or `RY_RUNTIME=gnu-r`) uses GNU R
instead.

On ry's runtime, both check a typed package (one with `strict = true` under `[check]` in its
`ry.toml`, or with a file that holds ry syntax or a `# typing: strict` line) before they build it.
A strict-mode error stops the build, and the command prints the errors and exits with status 1:

```
  x strict mode found 1 error, so this code does not run
  x /home/you/bad was not built
```

The tarball then holds the package's sources as `ry run` would run them: a number literal carries
the type the checker gave it, an empty `List` or `Dict` carries its item type, and each parameter
and return annotation that fits on one line is written as the type it stands for, with aliases
expanded and the package's own `type` definitions unfolded (`p: Point` becomes
`p: Record{x: F64, y: F64}`). A type with no such spelling, such as the open record
`Record{a: I64, ..}`, stays as written. Only the tarball changes, never the package directory, and a
package that declares `Encoding: latin1` gets its rewritten files in latin1.

ry's `R CMD INSTALL` and `R CMD SHLIB` run `make` with one job per processor unless `MAKEFLAGS`
is set to a value. A package
whose `Makevars` builds correctly only with one job fails in parallel, so a failed parallel build
runs again with one job, reusing the objects already built.

Compiled code built by ry's `R CMD INSTALL` reads ry's object layout through the headers' inline
accessors, so it runs only under a ry whose headers have the same binary interface. The install
records that interface's version as `RyAbi:` in the package's `DESCRIPTION`, beside `RyBuilt:`
(ry's version). Loading a package that has `RyBuilt:` and whose `RyAbi:` is missing or differs
fails at its shared library:

```
Error: package or namespace load failed for ‘tally’:
 unable to load shared object '/home/me/library/tally/libs/tally.so':
  package 'tally' was compiled by ry 0.4.5 against older C headers, and its compiled code is unsafe to run under this ry. Reinstall it with this ry: install.packages("tally"), or R CMD INSTALL on its source (ry install for a package you develop).
```

A package GNU R installed has neither field and loads under ry as it is.

A build in place, by `ry load` or by an install from a directory, leaves its objects in `src/` with
a stamp file, `src/.ry-abi`, that names the same version. When the stamp is missing or differs, the
next build first deletes the objects and shared libraries under `src/` (static libraries stay), so
make cannot reuse objects that other headers compiled.

An install on ry's runtime compiles the package's typed functions and writes their machine code to
its typed code file, `R/<package>.<build>.ryt`. A later session maps that file and runs the first
call of each typed function on the code compiled at install, instead of compiling it, and processes
that use the same package share that code. The install log counts what the file holds:

```
** typed code: closures=2 written=2
```

A function the file leaves out, such as one with a `match` over any tag, is counted by reason after
`left out:` and compiles at its first call. With `--train`, the file also holds the versions the training run
compiled that an install cannot compile on its own, such as one for the type a `Num.from_r` gave in
that run. A session in which that conversion gives another type runs the call in the interpreter
instead; `RY_TYPED_LOG=1` names each function that attaches and
each one that compiles. `ry build --aot` on a package does what `ry install` does (`-l DIR` names
the library), and on a script it is a usage error that points at `--exe`.
`R CMD INSTALL --ry-no-typed-code` writes no typed code file. A typed code file another build of ry
wrote is ignored. [The typed code file](/development/typed-code-file.md) is the design.

### Executables

`ry build --aot --exe main.R` checks the script as `ry run` does, compiles its typed top-level
functions, and writes an executable that runs the script with that code. The executable is named
after the script, in the current directory, unless `-o FILE` names another path; an output that
is the script itself or a directory is a usage error. The build prints what the code file holds
and then the executable's path:

```r
total <- function(n: I64) -> I64 {
  sum <- 0
  for (i in List.range(1, n)) sum <- sum + square(i)
  sum
}
square <- function(x: I64) -> I64 x * x
n <- as.integer(commandArgs(trailingOnly = TRUE)[[1]])
print(total(n))
```

```console
$ ry build --aot --exe totals.R
typed code: closures=2 written=2
totals
$ RY_TYPED_LOG=1 ./totals 10
typed: attached `total` for [I64] -> I64 from the executable's code file
385i64
```

The executable prints what `ry run --aot` prints for the same arguments, and every argument goes
to the script, so `--help` is the script's to read. Its typed functions attach their code from the
executable instead of compiling, and it does not check the script again, so it starts sooner than
`ry run` does. A function [Compiling ahead of time](#compiling-ahead-of-time) lists as compiling
at its first call still does, and so does a file the script sources: only the script itself is in
the executable.

The executable is a copy of `ry` with the script and its code appended, so it runs on the ry
runtime and base R that `ry` itself uses (see [How ry finds R](#how-ry-finds-r)). One built by a
development build of ry remembers where that build's runtime and base R are, and `RY_LIBR` and
`RY_BASE_R` override them. Packages load from the library as they do for `ry run`, and are not in
the executable. On macOS the executable is signed again ad hoc, because appending to `ry`
invalidates its signature.

An install on ry's runtime also writes the package's code image, `R/<package>.<build>.ryc`
beside its lazy-load database: the compiled code of every closure, which a later session takes instead of
compiling the closure itself, and the package's lazy-load records uncompressed, which a later
session reads in place instead of inflating them. `--train tests`, `--train examples` or `--train SCRIPT` (`R CMD
INSTALL --ry-train=...`) first runs the package's tests, its help-page examples or a script, and
the image then keeps the profile of that run, so a function that ran hot there is handed to the
optimizing tier as soon as a new session compiles it. `R CMD INSTALL --ry-no-code-image` writes no
image, and `RY_CODE_IMAGE=0` makes a session ignore images. An image for other package sources
is ignored, and a damaged one warns once and is ignored; reinstall the package to write a fresh
one. A package installed by another ry build, such as the version you upgraded from, runs without
its image, and the first such package a session loads from a library prints one note naming every
package in that library to reinstall:

```
ry: another build of ry installed these packages in library, so their functions compile as they run, which is slower, until you reinstall them: one, two
``` The base packages (base, stats, utils, methods and the rest)
carry images that ry's own build writes, holding their uncompressed records but no code.

## debug-adapter

`ry debug-adapter` serves one debug session over the
[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) on standard input and
output. The editor launches an R script, which runs on ry's runtime, and the command exits with the
script's status. The launch arguments are `program` (the script), `args`, `stopOnEntry`, `prelude`
(R code run first, such as `load_all("."); library(testthat)`) and `testName` (run only the
`test_that()` block with that description).

On Unix, the `ry run` console serves the same protocol on a socket, so an editor can attach to it
while you work: connect to the socket named in `$TMPDIR/ry-<uid>/console-<pid>.json` and send
`initialize` and then `attach`.

## debug

`ry debug ast FILE` prints the syntax tree of a file, `ry debug analysis-stats [PATH]` analyzes
a workspace and reports where time and memory go, and `ry debug erase FILE...` rewrites files in
place as the plain R that `ry R` runs, with every inline annotation removed. All three are developer
aids for working on ry itself.

## Crash reports

A process that dies from SIGSEGV, SIGBUS or SIGABRT prints a report on standard error first, then dies by the same signal, so exit statuses (139 for SIGSEGV in a shell) and core dumps are unchanged. This script calls a package's compiled code, which writes through a null pointer:

```text
*** ry caught SIGSEGV (segmentation fault) ***
ry 0.4.4
address 0x0, cause 'memory not mapped' (si_code 1)

R call stack, innermost call first:
 1: .Call(...)
 2: write_through_null(...)
 3: caller(...)

Native stack, innermost first, starting in the crash handler (module(symbol+offset) [address]):
/usr/local/bin/ry(+0x1d68262)[0x558889e1a262]
/usr/local/bin/ry(+0x1d6882f)[0x558889e1a82f]
/lib/x86_64-linux-gnu/libc.so.6(+0x45330)[0x7f864da45330]
/home/user/library/crashpkg/libs/crashpkg.so(write_c+0x4)[0x7f864dc3c124]
/usr/local/bin/libR.so(+0x4cbc8ae)[0x7f2e2a3b08ae]
...
```

- **Header.** The version, the signal, and for a fault the address and its cause: `memory not mapped`, `invalid permissions`, or a bus error's cause. A signal sent with `kill` or `abort` says so instead.
- **R call stack.** The function of each call in progress, innermost first, as `traceback()` numbers them, with `.Call` and its relatives between the closures that made them. It lists at most 50 calls and then counts the rest (`... 73 more`). A frame whose memory cannot be read prints as `<unreadable frame>` instead of causing a second crash.
- **Native stack.** The addresses with their module and offset. A release `ry` is stripped, so its frames show `module(+offset)` and no symbol; keep the matching binary to look an offset up with `addr2line -e BINARY OFFSET`. The first frames belong to the handler.

The report is written without allocating, on a signal stack of its own, so a stack overflow is reported too. A handler that was installed before it still runs afterwards, which is how Rust's `thread has overflowed its stack` line still appears. It covers every command that starts ry's runtime (`run`, `R`, `repl`, `test` and its workers, `load`, `document`, `build`, `install`) and `check`, `fmt` and `server`; with `--runtime gnu-r`, GNU R prints its own report. Windows prints no report.

## Exit codes

- **0**: nothing found, or nothing to reformat.
- **1**: `check` counted a finding (warnings count, unless `--min-severity error`), `fmt --check` or
  `--diff` found a file to change, `run`, `R` or `load` hit an error in the script or the package,
  `test` saw a test fail, `document` hit an error in roxygen2, strict mode refused a script, or the
  server stopped after an analysis panic. A script that calls `q(status = n)` exits with `n`.
- **2**: ry could not do its job. That is a usage error, invalid TOML in `ry.toml`, a path that does
  not exist, a file, script or stub it cannot read, an invalid `exclude` pattern, for `load`, `test`
  and `document` a path inside no package, or, for the commands that need R, no usable R or no ry
  runtime library. A `2` overrides a `1`, so a broken setup never looks like ordinary findings.

A [misspelled key](/reference/configuration.md#mistakes-in-rytoml) in `ry.toml` is only a warning, not
a `2`.

## How ry finds R

`ry check`, `ry fmt` and `ry server` run no R. The other commands except `ry R` run on ry's runtime,
which needs base R (the R code of the base and default packages):

- **Built in.** Linux releases from 0.4.3-beta, macOS releases from 0.4.4 and a build from source
  carry base R 4.6.2 inside `ry`, which extracts it into `~/.cache/ry/base/` on first use, once per
  release. `R.version`, `getRversion()` and `R.home()` then describe that copy. The 0.4.1-beta
  release does not have it and needs `R_HOME` or a GNU R on `PATH`.
- **`R_HOME`.** When set to a GNU R installation (4.3 or newer, built as a shared library), ry's
  runtime loads base R from it and behaves like that release where R changed between releases.
  An `R_HOME` that holds no base R is an error, not a fallback.
- **`RY_BASE_R`** names a base R tree built by `just base-r`. Without it, a `base-r/` directory
  beside `ry`, one or two directories up, or in `../lib/ry/base-r` takes precedence over the built-in
  copy, which is how a development build and a distribution package find theirs.

ry's runtime itself (`libR.so`, `libR.dylib` or `R.dll`) is built into `ry` and extracted into
`~/.cache/ry/runtime/` (`$XDG_CACHE_HOME`, or `%LOCALAPPDATA%` on Windows) on first use. If that
directory cannot hold a library (read-only, or mounted `noexec`), set `XDG_CACHE_HOME` to another
directory, or `RY_LIBR` to a runtime you placed yourself. A runtime beside `ry`, in `deps/`, or in
`../lib/ry/` takes precedence over the built-in one.

`ry R` and `--runtime gnu-r` run GNU R itself: the R in `R_HOME` if it is set, and otherwise the one
`R RHOME` reports on your `PATH`. It must be built as a shared library, as the CRAN builds are, and
on Windows it must be R 4.2 or newer.

Linear algebra (`solve`, `qr`, `chol`, `svd` and the rest) loads the system's BLAS and LAPACK on
first use: `libblas.so.3` and `liblapack.so.3` on Linux, Accelerate on macOS. With `R_HOME` set, ry
also looks in the directories GNU R's `etc/Makeconf` records (which is how it finds GNU R's on
NixOS). Last, it loads `lib/libRblas.so` and `lib/libRlapack.so` from the R home: GNU R's own, or on
Linux the reference BLAS and LAPACK that ry carries beside its runtime, built from GNU R's sources,
so linear algebra works on a system that has neither library. If none loads, the error lists every
place it searched. On Windows, linear algebra needs `R_HOME`, for GNU R's `Rblas.dll` and
`Rlapack.dll`. Compiled package code links the same libraries: on Linux, where the toolchain would link
`-lblas -llapack`, ry's `Makeconf` names the versioned files instead (`-l:libblas.so.3` and
`-l:liblapack.so.3`), so a package that uses them (Matrix, quadprog) builds without the
distribution's BLAS and LAPACK development packages.

The matrix products (`%*%`, `crossprod`, `tcrossprod`) do not use that BLAS by default. ry computes
them in its own kernels, which add each entry's terms in the order of the reference BLAS that GNU R
bundles, so the bits are the same on every machine. A GNU R linked to an optimized BLAS such as
OpenBLAS differs from that in the last bit. To get that GNU R's results, set `options(ry.blas =
"host")` or start ry with `RY_BLAS=host`: the products then call the BLAS found above (`dgemm`,
`dgemv`, `dsyrk`, `zgemm`) with the arguments GNU R passes, and `options(matprod =)` keeps its
meaning, including the NaN and infinity screen of `"default"` and `"default.simd"`. The option wins
over the variable, and `"reference"` (the default) selects ry's kernels. `options(matprod =
"internal")` is GNU R's long double loop and ignores the setting. `solve`, `qr`, `chol`, `svd` and
the other LAPACK-backed functions always call the host libraries.

Packages you installed with GNU R are on ry's `.libPaths()` without any setup. When `R_LIBS_USER`
is unset, it holds GNU R's user library for ry's R version (`~/R/<platform>-library/4.6` on
Linux, `~/Library/R/<arch>/4.6/library` on macOS, with `arm64` for Apple silicon) and then the existing ones of older 4.x versions,
newest first. When `R_LIBS_SITE` is unset, it holds ry's own site library, then the `site-library`
of the GNU R on `PATH` (read from its `R` script's `R_HOME_DIR`) and `/usr/local/lib/R/site-library`,
`/usr/lib/R/site-library` and `/usr/local/lib/R/library`, skipping any that holds `base`. Only
directories that exist are kept, in this order and ahead of ry's own library:

```text
[1] "/home/me/R/x86_64-pc-linux-gnu-library/4.6"
[2] "/home/me/R/x86_64-pc-linux-gnu-library/4.5"
[3] "/opt/R/4.5.1/lib/R/site-library"
[4] "/home/me/.cache/ry/home/18e0bd65b5dace8c/library"
```

A variable you set replaces its default, as in GNU R; `R_LIBS_SITE=NULL` drops the site libraries.

On macOS, `ry run` loads packages installed by CRAN's or Homebrew's GNU R unchanged: it loads a copy
of each package library, cached under `~/Library/Caches/ry/rebound/`, that names ry's runtime
instead of GNU R's `libR`.

## JSON output

`ry check --output json` writes one object per finding to stdout and nothing else, not even a
summary, so the stream can be read line by line:

```json
{"code":"type-mismatch","column":21,"endColumn":27,"endLine":4,"fix":null,"line":4,"message":"expected `integer`, found `character`","path":"/home/you/demo/main.R","related":[],"severity":"error"}
```

`path` is absolute. Lines and columns start at 1 and count characters, as your editor does, and
`endColumn` is one past the end. `severity` is `"warning"` or `"error"`, and `code` is what a
`# ry: allow(...)` comment names. `related` lists companion locations with the same position fields
and a `message`, such as the other definition of a `duplicate`. `fix` is `null` or an object with
the `title`, an `applicability` of `"safe"` or `"unsafe"`, the position fields of the range it
replaces, and the `replacement` text. These field names are a contract,
so tools built on them keep working across releases.
