Skip to main content

Update the list of Julia functions R can call

Source: R/scaffold.R

Description

Finds the @rcall declarations in the package’s Julia binding package and generates the code that lets R call them. Run this whenever you add or remove an @rcall, or change its arguments. It writes two files:

Usage

update_entrypoints(path = ".")

Arguments

path Path to the package sources.

Details

  • src/entrypoints.h, from which src/jlbind.c registers a routine C_<name> for each declaration.

  • R/jlbind-wrappers.R, with an R function for each declaration that calls its routine. @rcall shift(x::Vector{Float64}, by::Float64 = 0.0)::Float64 becomes shift <- function(x, by = 0.0) .Call(C_shift, x, by).

Defaults must be literal numbers, strings, true, false or nothing (NULL). A function returning Nothing returns invisibly. To export or document a function, use a roxygen block on NULL with @name in another file. To add R code around a call, declare the Julia function with a jl_ prefix and write the R function yourself.

Value

Invisibly, a data frame of the entrypoints with the columns name, nargs, and the formals, args and invisible (whether it returns invisibly) of their R wrappers.

Examples

# A package set up with use_jlbind() in a temporary directory
pkg <- file.path(tempdir(), "addpkg")
dir.create(pkg)
writeLines(
  c(
    "Package: addpkg",
    "Title: Demo",
    "Version: 0.1.0",
    "Description: Demo.",
    "License: MIT"
  ),
  file.path(pkg, "DESCRIPTION")
)
use_jlbind(pkg)
#> Created the binding package addpkgBindings in /tmp/RtmpM1Cbim/addpkg/inst/julia.
#> Wrote /tmp/RtmpM1Cbim/addpkg/src/entrypoints.h (1 entrypoints).
#> Wrote /tmp/RtmpM1Cbim/addpkg/R/jlbind-wrappers.R.

# Add an entrypoint to the binding package, before its closing `end`
file <- file.path(pkg, "inst/julia/src/addpkgBindings.jl")
code <- readLines(file)
last <- max(which(code == "end"))
code <- append(
  code,
  c(
    "add(x::Float64, y::Float64) = x + y",
    "@rcall add(x::Float64, y::Float64)::Float64",
    ""
  ),
  after = last - 1L
)
writeLines(code, file)

update_entrypoints(pkg)
#> Wrote /tmp/RtmpM1Cbim/addpkg/src/entrypoints.h (2 entrypoints).
#> Wrote /tmp/RtmpM1Cbim/addpkg/R/jlbind-wrappers.R.
writeLines(readLines(file.path(pkg, "R", "jlbind-wrappers.R")))
#> # Generated by jlbind::update_entrypoints(): do not edit by hand
#> 
#> hello <- function(name) .Call(C_hello, name)
#> add <- function(x, y) .Call(C_add, x, y)