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

In romainfrancois/Rcpp98: Seamless R and C++ Integration

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(), 
          rebuild = FALSE, showOutput = verbose, 
          verbose = getOption("verbose"))

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.
rebuild	Force a rebuild of the shared library.
showOutput	TRUE to print R CMD SHLIB output to the console.
verbose	TRUE to print detailed information about generated code to the console.

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++ compliation is completed so all functions and modules will be available to the R code.

Value

Returns (invisibly) a list with two elements:

functions	Names of exported functions
modules	Names of Rcpp modules

Note

The sourceCpp function will not rebuild the shared library if the source file has not changed since the last compilation.

The sourceCpp function is designed for compiling a standalone source file whose only dependencies are R packages. If you are compiling more than one source file or have external dependencies then you should create an R package rather than using sourceCpp. Note that the Rcpp::export attribute can also be used within packages via the compileAttributes function.

If you are sourcing a C++ file from within the src directory of a package then the package's LinkingTo dependencies, inst/include, and src directories are automatically included in the compilation.

If no Rcpp::export attributes or RCPP_MODULE declarations are found within the source file then a warning is printed to the console. You can disable this warning by setting the rcpp.warnNoExports option to FALSE.

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);
  }'
)


## End(Not run)

romainfrancois/Rcpp98 documentation built on May 27, 2019, 1:48 p.m.