Skip to main content

Set up a package to use jlbind

Source: R/scaffold.R

Description

Adds what a package needs to call Julia code through jlbind.

Usage

use_jlbind(path = ".", module = NULL, dir = "julia")

Arguments

path Path to the package sources.
module Name of the Julia binding package. Defaults to the package name followed by Bindings. It must be unique across all packages that use jlbind, since they’re all compiled into one library.
dir Directory under inst/ for the binding package.

Details

  • A Julia binding package in inst/<dir>, with one example function, hello(). An existing binding package is left alone.

  • The C code that registers the package’s routines: src/jlbind.c and src/entrypoints.h (written by update_entrypoints()), and a rule in src/Makevars (created if needed) that recompiles jlbind.c when entrypoints.h changes.

  • R/jlbind.R, with an .onLoad() that calls bind_client(), and the roxygen tag for useDynLib(). If the package already has an .onLoad(), add jlbind::bind_client(pkgname) to it yourself.

  • The Config/jlbind and Imports: jlbind fields in DESCRIPTION.

  • .jlbind/, where build_library() writes a library for development, in .Rbuildignore and .gitignore.

  • R/jlbind-wrappers.R (written by update_entrypoints()), with an R function for each Julia function declared with @rcall.

Value

path, invisibly.

Examples

# A new package in a temporary directory
pkg <- file.path(tempdir(), "mypkg")
dir.create(pkg)
writeLines(
  c(
    "Package: mypkg",
    "Title: Demo",
    "Version: 0.1.0",
    "Description: Demo.",
    "License: MIT"
  ),
  file.path(pkg, "DESCRIPTION")
)

use_jlbind(pkg)
#> Created the binding package mypkgBindings in /tmp/RtmpOAs2nZ/mypkg/inst/julia.
#> Wrote /tmp/RtmpOAs2nZ/mypkg/src/entrypoints.h (1 entrypoints).
#> Wrote /tmp/RtmpOAs2nZ/mypkg/R/jlbind-wrappers.R.
list.files(pkg, recursive = TRUE)
#> [1] "DESCRIPTION"                     "inst/julia/Project.toml"        
#> [3] "inst/julia/src/mypkgBindings.jl" "NAMESPACE"                      
#> [5] "R/jlbind-wrappers.R"             "R/jlbind.R"                     
#> [7] "src/entrypoints.h"               "src/jlbind.c"                   
#> [9] "src/Makevars"

# The Julia binding package, with its example entrypoint
writeLines(readLines(file.path(pkg, "inst/julia/src/mypkgBindings.jl")))
#> """
#>     mypkgBindings
#> 
#> The R entrypoints of the R package mypkg. Each `@rcall` declaration
#> exports a Julia function to R; after changing them, run
#> `jlbind::update_entrypoints()` to regenerate the R functions that call them, in
#> `R/jlbind-wrappers.R`.
#> """
#> module mypkgBindings
#> 
#> using JLBind
#> 
#> hello(name::String) = "Hello, " * name * ", from Julia!"
#> 
#> @rcall hello(name::String)::String
#> 
#> end