Rcpp (version 1.0.1)

sourceCpp: Source C++ Code from a File or String

Description

sourceCpp parses the specified C++ file or source code and looks for functions marked with the Rcpp::export attribute and RCPP_MODULE declarations. A shared library is then built and its exported functions and Rcpp modules are made available in the specified environment.

Usage

sourceCpp(file = "", code = NULL, env = globalenv(), embeddedR = TRUE, rebuild = FALSE, 
          cacheDir = getOption("rcpp.cache.dir", tempdir()), cleanupCacheDir = FALSE,
          showOutput = verbose, verbose = getOption("verbose"), dryRun = FALSE)

Arguments

file

A character string giving the path name of a file

code

A character string with source code. If supplied, the code is taken from this string instead of a file.

env

Environment where the R functions and modules should be made available.

embeddedR

TRUE to run embedded R code chunks.

rebuild

Force a rebuild of the shared library.

cacheDir

Directory to use for caching shared libraries. If the underlying file or code passed to sourceCpp has not changed since the last invocation then a cached version of the shared library is used. The default value of tempdir() results in the cache being valid only for the current R session. Pass an alternate directory to preserve the cache across R sessions.

cleanupCacheDir

Cleanup all files in the cacheDir that were not a result of this compilation. Note that this will cleanup the cache from all other calls to sourceCpp with the same cacheDir. This option should therefore only be specified by callers that provide a unique cacheDir per scope (e.g. chunk labels in a weaved document).

showOutput

TRUE to print R CMD SHLIB output to the console.

verbose

TRUE to print detailed information about generated code to the console.

dryRun

TRUE to do a dry run (showing commands that would be used rather than actually executing the commands).

Value

Returns (invisibly) a list with two elements:

functions Names of exported functions
modules Names of Rcpp modules

Details

If the code parameter is provided then the file parameter is ignored.

Functions exported using sourceCpp must meet several conditions, including being defined in the global namespace and having return types that are compatible with Rcpp::wrap and parameter types that are compatible with Rcpp::as. See the Rcpp::export documentation for more details.

Content of Rcpp Modules will be automatically loaded into the specified environment using the Module and populate functions.

If the source file has compilation dependencies on other packages (e.g. Matrix, RcppArmadillo) then an Rcpp::depends attribute should be provided naming these dependencies.

It's possible to embed chunks of R code within a C++ source file by including the R code within a block comment with the prefix of /*** R. For example:

/*** R

# Call the fibonacci function defined in C++ fibonacci(10)

*/

Multiple R code chunks can be included in a C++ file. R code is sourced after the C++ compilation is completed so all functions and modules will be available to the R code.

See Also

Rcpp::export, Rcpp::depends, cppFunction, evalCpp

Examples

# NOT RUN {
sourceCpp("fibonacci.cpp")

sourceCpp(code='
  #include <Rcpp.h>

  // [[Rcpp::export]]
  int fibonacci(const int x) {
    if (x == 0) return(0);
    if (x == 1) return(1);
    return (fibonacci(x - 1)) + fibonacci(x - 2);
  }'
)

# }