View source: R/tar-target-cpp.R
| tar_target_cpp_raw | R Documentation |
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().
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")
)
name |
Character string, the target name. |
script |
Path to the C++ script with |
post_script |
Path to an R script run after compilation, where the compiled functions and |
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. |
output |
Output mode: |
depends |
Optional character vector of extension packages (e.g. |
pattern |
Optional branching pattern as described in the targets package documentation, as a language object (e.g. |
packages, library |
Character vectors of R packages (and library paths) to load for the target, forwarded to |
deps, string |
Advanced |
format, repository, iteration |
Storage/iteration settings forwarded to |
error, memory, garbage_collection, deployment, priority, resources, storage, retrieval, cue, description |
Standard |
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().
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.
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.
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.
tar_target_path() referencee.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.
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.
tar_target_cpp(), tarpolyglot_map(), run_cpp_step(), tar_target_rs_raw(), tar_target_py_raw(), tar_target_jl_raw()
# 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() })
)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.