tar_target_cpp_raw: Target that runs a C++ script (raw / factory form)

View source: R/tar-target-cpp.R

tar_target_cpp_rawR Documentation

Target that runs a C++ script (raw / factory form)

Description

Character-based constructor mirroring targets::tar_target_raw() for C++, for use inside targets factories. Returns a single targets target whose command compiles the ⁠// [[Rcpp::export]]⁠ functions in script with Rcpp::sourceCpp() and then evaluates an R post-script that calls those functions (with the upstream inputs in scope) and returns the value. See run_cpp_step() for the contract. For direct use in ⁠_targets.R⁠, see tar_target_cpp().

Usage

tar_target_cpp_raw(
  name,
  script,
  post_script = NULL,
  inputs = NULL,
  output = "object",
  depends = NULL,
  pattern = NULL,
  packages = targets::tar_option_get("packages"),
  library = targets::tar_option_get("library"),
  deps = NULL,
  string = NULL,
  format = NULL,
  repository = targets::tar_option_get("repository"),
  iteration = targets::tar_option_get("iteration"),
  error = targets::tar_option_get("error"),
  memory = targets::tar_option_get("memory"),
  garbage_collection = isTRUE(targets::tar_option_get("garbage_collection")),
  deployment = targets::tar_option_get("deployment"),
  priority = targets::tar_option_get("priority"),
  resources = targets::tar_option_get("resources"),
  storage = targets::tar_option_get("storage"),
  retrieval = targets::tar_option_get("retrieval"),
  cue = targets::tar_option_get("cue"),
  description = targets::tar_option_get("description")
)

Arguments

name

Character string, the target name.

script

Path to the C++ script with ⁠// [[Rcpp::export]]⁠ functions (required). Accepts a literal path, a tar_target_path() reference, or inline code from tar_code(); see the "Script options" section below.

post_script

Path to an R script run after compilation, where the compiled functions and inputs are in scope. Its last expression is the value (object mode); it returns file paths (file mode). Required for object mode. Accepts a literal path, a tar_target_path() reference, or inline code from tar_code(); see the "Script options" section below.

inputs

Named character vector (or list) mapping the name seen inside the step (in the R environment and, after the hand-off, in the foreign session) to the name of an upstream target, e.g. c(x = "prepared_x"). Each upstream target becomes a dependency of this target and is bound by that name in the step environment; under dynamic branching the per-branch slice is bound instead.

output

Output mode: "object" (default) returns a converted R object, "file" returns a character vector of file paths (and defaults format to "file").

depends

Optional character vector of extension packages (e.g. c("RcppArmadillo", "RcppEigen")); see run_cpp_step().

pattern

Optional branching pattern as described in the targets package documentation, as a language object (e.g. quote(map(x))), forwarded to targets::tar_target_raw(). The patterns included in the targets package (map(), head(), ...) are accepted, but it is recommended to use the tarpolyglot pattern functions instead, as they compile the library once and reuse it across the branches (see tarpolyglot_map(), tarpolyglot_head(), tarpolyglot_tail(), tarpolyglot_cross(), tarpolyglot_slice(), tarpolyglot_sample()).

packages, library

Character vectors of R packages (and library paths) to load for the target, forwarded to targets::tar_target_raw().

deps, string

Advanced targets::tar_target_raw() arguments: extra dependency names and a string used for change detection.

format, repository, iteration

Storage/iteration settings forwarded to targets::tar_target_raw(). format defaults to "file" when output = "file", otherwise to the targets option default.

error, memory, garbage_collection, deployment, priority, resources, storage, retrieval, cue, description

Standard targets::tar_target_raw() execution/behaviour arguments, forwarded unchanged.

Details

Unlike Python/Julia there is no pre-script for C++: inputs are used directly in the post-script alongside the compiled functions, mirroring tar_target_rs(). A working C++ compiler is required; sourceCpp() compiles via R's own configured toolchain (⁠R CMD SHLIB⁠), so, unlike Rust, there is no separate compiler/ABI to match – on Windows Rtools must be installed and discoverable the same way it already needs to be for any R package with compiled code.

Under dynamic branching, pattern = map(...) recompiles the library in every branch (C++ has no live interpreter to reuse, the same limitation Rust has). Passing a tarpolyglot pattern helper instead (tarpolyglot_map(), tarpolyglot_cross(), tarpolyglot_slice(), tarpolyglot_head(), tarpolyglot_tail(), tarpolyglot_sample()) compiles the library once in a companion target named ⁠<name>_cpp_lib⁠ and reuses it across all branches; the constructor then returns both targets as a list. See tarpolyglot_map().

Value

A targets target object. When pattern uses tarpolyglot_map() it is instead a list of two targets: the ⁠<name>_cpp_lib⁠ compile target and the branched ⁠<name>⁠ target.

Script options

Every script argument (script, and pre_script / post_script where the constructor has them) accepts the same three forms. The choice is not cosmetic: it decides whether editing the code re-runs the target.

A literal path string

e.g. script = "py/step.py". The file is read when the step runs, but it is not tracked, so editing it does not invalidate the target: targets will happily reuse a stale result until some other dependency changes. Simplest form, and a reasonable default once a script has settled.

A tar_target_path() reference

e.g. script = tar_target_path("step_py"), naming an upstream tar_target(step_py, "py/step.py", format = "file"). The file becomes a real targets dependency, so editing it does invalidate this target and the step re-runs. This is what you want while a script is still changing, and the recommended form for reproducible pipelines.

Inline code via tar_code()

e.g. script = tar_code("result = sum(x)"). The code lives in ⁠_targets.R⁠ rather than in a file, and is embedded in the target's command, so targets hashes it and editing it does invalidate the target. A character string carries foreign source (Python, Julia, Rust, C++) or R source; an R { ... } block carries inline R and is accepted only by pre_script / post_script, never by the foreign script.

Mixing forms in one call is fine: a tracked script with a literal post_script, inline code for one and a file for another, and so on. See vignette("scripts") for worked examples of all three and guidance on choosing.

See Also

tar_target_cpp(), tarpolyglot_map(), run_cpp_step(), tar_target_rs_raw(), tar_target_py_raw(), tar_target_jl_raw()

Examples

# Building a target does not run it, so these examples need no C++ compiler.
# scripts/square.cpp:
#   // [[Rcpp::export]]
#   double square(double x) { return x * x; }
# scripts/post.R:
#   square(x)
tarpolyglot::tar_target_cpp_raw(
  name = "cpp_square",
  script = "scripts/square.cpp",
  inputs = c(x = "value"),
  post_script = "scripts/post.R"
)

# The three ways to supply a script (see the "Script options" section):
# 1. Literal path: untracked, editing the file does NOT re-run the step.
tarpolyglot::tar_target_cpp_raw(
  name = "demo_literal", script = "cpp/step.cpp", post_script = "R/post.R"
)

# 2. tar_target_path(): tracked, editing the file DOES re-run the step.
list(
  targets::tar_target(step_cpp, "cpp/step.cpp", format = "file"),
  tarpolyglot::tar_target_cpp_raw(
    name = "demo_tracked",
    script = tarpolyglot::tar_target_path("step_cpp"),
    post_script = "R/post.R"
  )
)

# 3. tar_code(): inline, editing the code DOES re-run the step. A string
#    carries foreign source; an R { } block carries inline R.
tarpolyglot::tar_target_cpp_raw(
  name = "demo_inline",
  script = tarpolyglot::tar_code(
    "// [[Rcpp::export]]\nint one() { return 1; }"
  ),
  post_script = tarpolyglot::tar_code({ one() })
)

tarpolyglot documentation built on Nov. 22, 2026, 5:07 p.m.