CLI
ry check [PATHS] # report problemsry fmt [PATHS] # format files in placery migrate data-table [PATHS] # rewrite data.table code as DataFrame codery run [FILE] # run an R script on ry's runtime; without one, open ry's consolery R [FILE] # the same on GNU Rry load [PATH] # load an R package from source, run code against it, and exitry test [PATH] # run a package's testthat tests against the loaded packagery document [PATH] # write a package's Rd files and NAMESPACE with roxygen2ry build [PATH] # build a package's source tarball; --aot installs it compiled, --aot --exe makes a script an executablery install [PATH] # build and install a packagery debug-adapter # a debugger for editors, over stdiory server # the language server, over stdio; your editor starts itry debug COMMAND # developer aids for working on ry itselfformat 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.
ry check # the current directoryry check R/model.R # report on one filery check --output json # one JSON object per finding, on stdoutry check --min-severity error # ignore warnings, also for the exit codery check --fix # apply the safe fixes, then report what remainsry check --fix --unsafe-fixes # also apply fixes that guess, such as a spelling suggestionry check --annotate # write inferred types as annotations, then report what remainsNaming 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 file2 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.
The check cache
Section titled “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.
ry fmt # rewrite files in placery fmt --check # name the files that would change, and exit 1 if any wouldry fmt --diff # show the changes without writing them, and exit 1 if anyry fmt --range 3-8 R/report.R # format only lines 3 to 8 of one filery 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.
migrate
Section titled “migrate”ry migrate data-table # print the rewrites for the project as a diffry migrate data-table R/ --write # rewrite the files under R/ in placery 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.
run and R
Section titled “run and R”ry run script.R a b # run on ry's runtime; the script reads a and b with commandArgs(TRUE)ry run # ry's consolery run -i setup.R # run setup.R, then open the consolery R script.R # run on GNU Rry R # a GNU R console with ry's highlighting and completionOptions 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 viswitches 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 aBrowse[1]>prompt:nruns the next statement,ssteps in,ffinishes the function,ccontinues,Qquits, andwhereshows the call stack. In a script,browser()does nothing, as in a non-interactive R session.?meanandhelp()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
Section titled “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.
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 * xcat("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:
$ RY_TYPED_LOG=1 ry run totals.Rstartedtyped: compiled for [I64] -> I64 in 733 us385i64$ RY_TYPED_LOG=1 ry run --aot totals.Rtyped: compiled for [I64] -> I64 in 1044 ustyped: compiled for [I64] -> I64 in 319 ustyped: compiled 2 functions ahead of time in 1419 usstarted385i64A 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 bysource(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 printsry: 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 as1.5L; - a top-level function with a record, tuple,
Dict,Setor 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 aList.from_rwhose item type the checker does not know, such asList.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.
Profile summary
Section titled “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:
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 asprivate-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] <- vthat 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,xtsand the like) as “an object”; - the refused compile attempts by reason, with the reasons
RY_JIT_LOG=1prints 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
Section titled “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
Section titled “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
Section titled “load and server”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 REGEXruns only the test files whose names match, asdevtools::test(filter =)does. The pattern matches the name without a leadingtest-ortest_and without the extension, so--filter '^parse$'selectstest-parse.Randtest_parse.R.--reporter NAMEpicks a testthat reporter, such assummary,progressorcheck.--jobs N(or-j N) runs the test files inNworker processes, one file at a time in each, and--jobs 1runs them in thery testprocess. See Parallel tests.--watchkeeps running: after every edit underR/,src/,data/,inst/,tests/,DESCRIPTIONorNAMESPACEit reloads only what changed (rebuilding compiled code after asrc/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
Section titled “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
Section titled “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
Section titled “build and install”ry build # write ../<package>_<version>.tar.gzry build -o dist # write it into dist/ insteadry install # install into the first library on .libPaths()ry install -l ~/rlib # install into ~/rlibry install --train tests # train the package's code image on its testsry build --aot -l ~/rlib # install, as ry install doesry build --aot --exe main.R # write the executable ./mainry build --aot --exe main.R -o bin/app # write it to bin/app insteadry 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 builtThe 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=2A 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.
Executables
Section titled “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:
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 * xn <- as.integer(commandArgs(trailingOnly = TRUE)[[1]])print(total(n))$ ry build --aot --exe totals.Rtyped code: closures=2 written=2totals$ RY_TYPED_LOG=1 ./totals 10typed: attached `total` for [I64] -> I64 from the executable's code file385i64The 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 andoutput. The editor launches an R script, which runs on ry's runtime, and the command exits with thescript'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 itwhile 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]` analyzesa workspace and reports where time and memory go, and `ry debug erase FILE...` rewrites files inplace as the plain R that `ry R` runs, with every inline annotation removed. All three are developeraids 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.4address 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 withkillorabortsays so instead. - R call stack. The function of each call in progress, innermost first, as
traceback()numbers them, with.Calland 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
ryis stripped, so its frames showmodule(+offset)and no symbol; keep the matching binary to look an offset up withaddr2line -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
Section titled “Exit codes”- 0: nothing found, or nothing to reformat.
- 1:
checkcounted a finding (warnings count, unless--min-severity error),fmt --checkor--difffound a file to change,run,Rorloadhit an error in the script or the package,testsaw a test fail,documenthit an error in roxygen2, strict mode refused a script, or the server stopped after an analysis panic. A script that callsq(status = n)exits withn. - 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 invalidexcludepattern, forload,testanddocumenta path inside no package, or, for the commands that need R, no usable R or no ry runtime library. A2overrides a1, so a broken setup never looks like ordinary findings.
A misspelled key in ry.toml is only a warning, not
a 2.
How ry finds R
Section titled “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()andR.home()then describe that copy. The 0.4.1-beta release does not have it and needsR_HOMEor a GNU R onPATH. 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. AnR_HOMEthat holds no base R is an error, not a fallback.RY_BASE_Rnames a base R tree built byjust base-r. Without it, abase-r/directory besidery, one or two directories up, or in../lib/ry/base-rtakes 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.
JSON output
Section titled “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:
{"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.