Package {zigimports}

zigimports: Call 'Zig' Code from R

Description

Load shared libraries compiled from 'Zig' (.so on Linux, .dll on Windows) with zig_load, bind exported functions with zig_bind, and compile and run 'Zig' code from R with zig_call.

Author(s)

Maintainer: Firstname Lastname author@example.com

Authors:

• Coauthor Name

Bind an exported Zig function to an R function

Description

Looks up a function exported from a library loaded with zig_load and returns an ordinary R function that calls it. Arguments are passed by value with the native C calling convention, so functions with mixed argument types, such as export fn add(a: i32, b: f64) f64, work as expected.

Usage

zig_bind(lib, name, args = NULL, returns = "void")

Arguments

Details

Supported types (a Zig-style or R-style name may be used):

"void" is also valid as a return type. Functions must be declared with export fn, take at most six arguments, and cannot return pointers other than strings. Vector arguments are copied before the call, so the caller's data is never modified; the modified copies are returned (see Value). NA integers are passed as the C value INT_MIN. The Zig code runs inside the R process: a crash in Zig crashes R.

Value

A function taking the Zig function's arguments. Calling it returns the Zig return value. If the function has vector arguments, their (possibly modified) copies are returned as a named list: in the "args" attribute of the return value, or as the result itself for a void function.

See Also

zig_load, zig_call

Examples

if (nzchar(Sys.which("zig"))) {
  q <- function(p) shQuote(p, type = if (.Platform$OS.type == "windows") "cmd" else "sh")
  src <- system.file("examples", "mathlib.zig", package = "zigimports")
  tmp <- tempfile("zigimports_ex_")
  dir.create(tmp)
  out <- file.path(tmp, paste0("mathlib", .Platform$dynlib.ext))
  status <- system2("zig", c("build-lib", q(src), "-dynamic", "-O", "ReleaseFast",
                             paste0("-femit-bin=", q(out)),
                             "--cache-dir", q(file.path(tmp, "c")),
                             "--global-cache-dir", q(file.path(tmp, "g"))),
                    stdout = FALSE, stderr = FALSE)
  if (status == 0L && file.exists(out)) {
    lib <- zig_load(out)
    add <- zig_bind(lib, "add", args = c("i32", "f64"), returns = "f64")
    add(2L, 0.5)
    total <- zig_bind(lib, "total", args = c("ptr_f64", "i32"), returns = "f64")
    total(c(1, 2, 3), 3L)
    dyn.unload(lib$path)
  }
  unlink(tmp, recursive = TRUE)
}

Compile and run Zig code from R

Description

Compiles 'Zig' source into a temporary shared library with the zig compiler, loads it, calls it, and cleans up. Requires Zig (0.11 or later) to be installed and on the PATH, or located through options(zigimports.zig = ...) or the ZIGIMPORTS_ZIG environment variable. All build files are written to a temporary directory.

Usage

zig_call(
  code,
  ...,
  fn = NULL,
  args = NULL,
  returns = "void",
  optimize = c("ReleaseFast", "ReleaseSafe", "ReleaseSmall", "Debug"),
  flags = character(),
  zig = NULL,
  keep = FALSE,
  verbose = FALSE
)

Arguments

Details

There are two modes:

• Function mode (fn given): code is a complete Zig source (or the path to a .zig file) that defines export fn <fn>. The function is called with .... Argument types are given by args; if NULL they are inferred (length-1 double, integer, logical and string values are passed by value, longer vectors as pointers). Use args when a length-1 vector must be passed as a pointer.

• Snippet mode (fn = NULL): code is just a function body. Each named argument in ... becomes a Zig parameter with that name: a pointer for numeric, integer and logical vectors ([*]f64 or [*]i32) and [*:0]const u8 for a single string. The vector lengths are available as zig_lens[i] in argument order, and std is already imported. The body can return a value if returns is set.

See zig_bind for the supported types and conventions.

Value

As for functions created by zig_bind: the Zig return value (with the modified vector arguments in the "args" attribute), or, for returns = "void", a named list of the modified vector arguments (invisible NULL if there are none).

See Also

zig_load, zig_bind

Examples

if (nzchar(Sys.which("zig"))) {
  # Function mode: mixed argument types and a return value
  src <- "export fn add(a: i32, b: f64) f64 {
    return @as(f64, @floatFromInt(a)) + b;
  }"
  zig_call(src, fn = "add", args = c("i32", "f64"), returns = "f64",
           2L, 0.5)

}


if (nzchar(Sys.which("zig"))) {
  # Snippet mode: double every element of a vector
  zig_call("
    var i: usize = 0;
    while (i < @as(usize, @intCast(zig_lens[0]))) : (i += 1) x[i] *= 2;
  ", x = c(1, 2, 3))
}

Load a Zig shared library

Description

Loads a shared library produced by the 'Zig' compiler (a .so file on Linux or a .dll file on Windows) so that its exported functions can be bound with zig_bind.

Usage

zig_load(path)

Arguments

Value

An object of class "zig_lib": a list with the normalised path, the library name, and the dll handle returned by dyn.load.

See Also

zig_bind, zig_call

Examples

if (nzchar(Sys.which("zig"))) {
  q <- function(p) shQuote(p, type = if (.Platform$OS.type == "windows") "cmd" else "sh")
  src <- system.file("examples", "mathlib.zig", package = "zigimports")
  tmp <- tempfile("zigimports_ex_")
  dir.create(tmp)
  out <- file.path(tmp, paste0("mathlib", .Platform$dynlib.ext))
  status <- system2("zig", c("build-lib", q(src), "-dynamic", "-O", "ReleaseFast",
                             paste0("-femit-bin=", q(out)),
                             "--cache-dir", q(file.path(tmp, "c")),
                             "--global-cache-dir", q(file.path(tmp, "g"))),
                    stdout = FALSE, stderr = FALSE)
  if (status == 0L && file.exists(out)) {
    lib <- zig_load(out)
    print(lib)
    dyn.unload(lib$path)
  }
  unlink(tmp, recursive = TRUE)
}