Expand description
A low-level libR binding library which is kept deliberately minimal.
In particular, it has no external dependencies other that libR installed on the target.
Synopsis
The libR-sys
crate is a low level bindgen wrapper for the R
programming language. The intention is to allow one or more extension
mechanisms to be implemented for rust.
Effort to make the extension libraries platform-independent can be concentrated here.
Examples
use libR_sys::{Rf_initialize_R, R_CStackLimit, setup_Rmainloop};
use std::os::raw;
unsafe {
std::env::set_var("R_HOME", "/usr/lib/R");
let arg0 = "R\0".as_ptr() as *mut raw::c_char;
Rf_initialize_R(1, [arg0].as_mut_ptr());
R_CStackLimit = usize::max_value();
setup_Rmainloop();
}
Conditional compilation depending on R installation
The libR-sys crate provides these environmental variables that you can use in build.rs
:
DEP_R_R_VERSION_MAJOR
: The major part of the R version (e.g.4
in version4.1.0
)DEP_R_R_VERSION_MINOR
: The minor part of the R version (e.g.1
in version4.1.0
)DEP_R_R_VERSION_PATCH
: The patch part of the R version (e.g.0
in version4.1.0
)DEP_R_R_VERSION_DEVEL
:true
if the R is a development version, otherwisefalse
DEP_R_R_VERSION_STRING
: The full version string (e.g.R version 4.1.0 (2021-05-18)
)DEP_R_R_HOME
: The R home directory
Example build.rs
ⓘ
use std::env;
fn main() {
// Set R_HOME envvar, and refer to it on compile time by env!("R_HOME")
let r_home = env::var("DEP_R_R_HOME").unwrap();
println!("cargo:rustc-env=R_HOME={}", r_home);
// Enable cfg setting to conditionally compile a code using a feature
// available only on newer versions of R
let major = env::var("DEP_R_R_VERSION_MAJOR").unwrap();
let minor = env::var("DEP_R_R_VERSION_MINOR").unwrap();
if &*major >= "4" && &*minor >= "1" {
println!("cargo:rustc-cfg=use_a_feature");
}
}
Structs
- These are very similar to those in Rdynpriv.h, but we maintain them separately to give us more freedom to do some computations on the internal versions that are derived from these definitions.
- A structure containing graphical parameters
- try to allow some type checking
- R 4.3 redefined
Rcomplex
to a union for compatibility with Fortran. But the old definition is compatible both the union version and the struct version. See: https://github.com/extendr/extendr/issues/524
Constants
- native device coordinates (rasters)
- normalised device coordinates x=(0,1), y=(0,1)
- When replaying the display list, the graphics engine checks, after each replayed action, that the action produced valid output. This is the graphics system’s chance to say that the output is crap (in which case the graphics engine will abort the display list replay).
- Copy system state information to the current device. This is used when copying graphics from one device to another so all the graphics system needs to do is to copy across the bits required for the display list to draw faithfully on the new device.
- This event gives the registered system a chance to undo anything done in the initialisation.
- In response to this event, the registered graphics system should allocate and initialise the systemSpecific structure
- Restore the system state that is saved by GE_SaveSnapshotState
- This is sent by the graphics engine prior to replaying the display list. It gives the graphics system the chance to restore any information it saved on the GE_SaveState event
- Create a snapshot of the system state that is sufficient for the current “image” to be reproduced
- This is sent by the graphics engine prior to initialising the display list. It give the graphics system the chance to squirrel away information it will need for redrawing the the display list
- The device wants to scale the current pointsize (for scaling an image) This is not a nice general solution, but a quick fix for the Windows device.
- , MAYBE
- , MAYBE
- was === SA_RESTORE
- = 0
Statics
- “as.character”
- “@”
- The base environment; formerly R_NilValue
- The (fake) namespace for base
- “base”
- “” as a STRSXP
- “” as a CHARSXP
- “{”
- “[[”
- “[”
- C stack limit
- “class”
- Use current expression (marker)
- “.Device”
- “dimnames”
- “dim”
- “$”
- “…”
- “::”
- “drop”
- An empty environment at the root of the environment tree
- “eval”
- “function”
- The “global” environment
- To be found in BC interp. state (marker)
- “.Last.value”
- “levels”
- Missing argument marker
- “mode”
- NA_INTEGER:= INT_MIN currently
- IEEE NaN
- NA_REAL: IEEE
- “na.rm”
- NA_STRING as a CHARSXP
- “name”
- “names”
- “.NAMESPACE.”
- Registry for registered namespaces
- IEEE -Inf
- The nil object
- “package”
- IEEE Inf
- “previous”
- “quote”
- Marker for restarted function calls
- “row.names”
- “.Random.seed”
- “sort.list”
- “source”
- “spec”
- Current srcref, for debuggers
- “:::”
- “tsp”
- Unbound marker
- <– backcompatible version of:
- “.Generic”
- “.Method”
- “.defined”
- “.packageName”
- “.target”
Functions
- ALTREP support
- General Cons Cell Attributes
- BODY⚠
- CAAR⚠
- CADR⚠
- CAR⚠
- CDAR⚠
- CDDR⚠
- CDR⚠
- External pointer access macros
- Closure Access Functions
- Environment Access Functions
- From plotmath.c
- From plot3d.c : used in package clines
- metadata access
- S4 object testing
- Vector Access Functions
- MARK⚠
- Promise Access Functions
- Symbol Access Functions
- RAW⚠
- RAW0⚠
- REAL⚠
- Check for an available device slot
- ../../main/util.c and others :
- From vfonts.c
- Patterns - from ../../main/patterns.c
- Raster operations
- Convert either a name or a #RRGGBB[AA] string to internal. Because people were using it, it also converts “1”, “2” … to a colour in the palette, and “0” to transparent white.
- srcref related functions
- NA_STRING is a SEXP, so defined in Rinternals.h
- External pointer interface
- Added in R 3.4.0
- Weak reference interface
- Environment and Binding Features
- preserve objects across GCs
- Interface for exporting and importing functions from one package for use from C code in a package. The registration part probably ought to be integrated with the other registrations. The naming of these routines may be less than ideal.
- S3-S4 class (inheritance), attrib.c
- Protected evaluation
- public C interface
- These two are guaranteed to use ‘.’ as the decimal point, and to accept “NA”.
- supporting a C-level version of is(., .) :
- S Like Memory Management
- class definition, new objects (objects.c)
- slot management (in attrib.c)
- Shutdown actions
- Calling a function with arguments evaluated
- R_gc⚠
- To be used by applications embedding R to register their symbols that are not related to any dynamic module
- ../../main/sort.c :
- ../../appl/maxcol.c: also in Applic.h
- C version of R’s indx <- order(…, na.last, decreasing) : e.g. arglist = Rf_lang2(x,y) or Rf_lang3(x,y,z)
- C version of R’s indx <- order(x, na.last, decreasing) :
- R’s versions with !R_FINITE checks
- appl/pretty.c: for use in engine.c and util.c
- ../../main/qsort.c : / / dummy renamed to II to avoid problems with g++ on Solaris
- used by BIOC::matter; mightbe reasonable to include in API
- vectorizing function f(x[1:n], …) -> x[] {overwriting x[]}.
- Other Internally Used Functions, excluding those which are inline-able
- These are the public inlinable functions that are provided in Rinlinedfuns.h It is essential that these do not appear in any other header file, with or without the Rf_ prefix.
- Type Coercions of all kinds
- the next really should not be here and is also in Defn.h
- ../main/errors.c : / / needed for R_load/savehistory handling in front ends
- Various tests with macro versions in the internal headers
- Translates Unicode point to UTF-8
- stuff that probably shouldn’t be in the API but is getting used
- TAG⚠
- SEXP (STRING_ELT)(SEXP x, R_xlen_t i);
- ../../appl/interv.c: also in Applic.h
- Random Number Generators
- Also used in packages nlme, pcaPP
Type Definitions
- Called with a variable argument set after casting to a compatible function pointer.
- ——— New (in 1.4.0) device driver structure ——— NOTES:
- The graphics engine will only accept locations and dimensions in native device coordinates, but it provides the following functions for converting between a couple of simple alternative coordinate systems and device coordinates: DEVICE = native units of the device NDC = Normalised device coordinates INCHES = inches (!) CM = centimetres (!!)
- Different kinds of “N(0,1)” generators :
- We sometimes need to coerce a protected value and place the new coerced value under protection. For these cases PROTECT_WITH_INDEX saves an index of the protection location that can be used to replace the protected value using REPROTECT.
- PARSE_NULL will not be returned by R_ParseVector
- Finalization interface
- These are very similar to those in Rdynpriv.h, but we maintain them separately to give us more freedom to do some computations on the internal versions that are derived from these definitions.
- Some line end/join constants
- These give the indices of some known keys
- These are the three possible mouse events
- type for length of (standard, not long) vectors etc
- R_xlen_t is defined as int on 32-bit platforms, and that confuses Rust. Keeping it always as ptrdiff_t works fine even on 32-bit.
- Startup Actions
- NOT YET using enum:
- Different ways to generate discrete uniform samples
- cetype_t is an identifier reseved by POSIX, but it is well established as public. Could remap by a #define though
- type of pointer to the hessian functions
- type of pointer to the target and gradient functions
- ../../appl/integrate.c
- ../main/character.c :
- main/optim.c