interfacesAttribute: Rcpp::interfaces Attribute

In Rcpp: Seamless R and C++ Integration

Rcpp::interfaces Attribute

Description

The Rcpp::interfaces attribute is added to a C++ source file to specify which languages to generate bindings for from exported functions. For example:

// [[Rcpp::interfaces(r, cpp)]]

Arguments

...	Interfaces to generate for exported functions within the source file. Valid values are r and cpp, and more than one interface can be specified.

Details

The Rcpp::interfaces attribute is used to determine which bindings to generate for exported functions. The default behavior if no Rcpp::interfaces attribute is specified is to generate only an R interface.

When cpp bindings are requested code is generated as follows:

1. Bindings are generated into a header file located in the inst/include directory of the package using the naming convention PackageName_RcppExports.h

2. If not already present, an additional header file named PackageName.h is also generated which in turn includes the Rcpp exports header.

   In the case that you already have a PackageName.h header for your package then you can manually add an include of the Rcpp exports header to it to make the exported functions available to users of your package.

3. The generated header file allows calling the exported C++ functions without any linking dependency on the package (this is based on using the R_RegisterCCallable and R_GetCCallable functions).

4. The exported functions are defined within a C++ namespace that matches the name of the package.

For example, an exported C++ function foo could be called from package MyPackage as follows:

   // [[Rcpp::depends(MyPackage)]]

   #include <MyPackage.h>

   void foo() {
      MyPackage::bar();
   }

The above example assumes that the sourceCpp function will be used to compile the code. If rather than that you are building a package then you don't need to include the Rcpp::depends attribute, but instead should add an entry for the referenced package in the Depends and LinkingTo fields of your package's DESCRIPTION file.

Note

If a file by the name of PackageName.h that wasn't generated by compileAttributes already exists in in the inst/include directory then it will not be overwritten (rather, an error will occur).

A static naming scheme for generated header files and namespaces is used to ensure consistent usage semantics for clients of exported cpp interfaces. Packages that wish to export more complex interfaces or additional C++ types are therefore typically better off not using this mechanism.

The Rcpp::interfaces attribute is specified using a syntax compatible with the new generalized attributes feature of the C++11 standard. Note however that since this feature is not yet broadly supported by compilers it needs to be specified within a comment (see examples below).

See Also

compileAttributes, Rcpp::export, Rcpp::depends

Examples

## Not run: 

// [[Rcpp::interfaces(r, cpp)]]

## End(Not run)

Rcpp documentation built on Nov. 3, 2024, 1:06 a.m.