Skip to content
ry

CLI

Terminal window
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 says where that runtime and base R come from.

Terminal window
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 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 shows how to read a finding.

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

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 says, prints how many it added, and then reports what is left. Strict mode shows it at work. A binding whose type inference cannot write down, such as one involving Unknown, is skipped.

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.

Terminal window
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.

Terminal window
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 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.

Terminal window
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 warnings, and in 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, 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 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.

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.

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:

Terminal window
$ 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 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 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.

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:

Terminal window
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.

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.

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.

ry load loads the package 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).

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.
  • --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.

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.

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).

Terminal window
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 is the design.

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:

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))
Terminal window
$ 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 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). 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.

  • 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 in ry.toml is only a warning, not a 2.

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:

[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.

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:

{"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.