sourceCpp {Rcpp} | R Documentation

## 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,
              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.
`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).

### 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)

[Package Rcpp version 0.12.5 Index]