1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
\name{sourceCpp}
\alias{sourceCpp}
\title{
Source C++ Code from a File or String
}
\description{
\code{sourceCpp} parses the specified C++ file or source code and looks for functions marked with the \code{\link[=exportAttribute]{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{
\item{file}{
A character string giving the path name of a file
}
\item{code}{
A character string with source code. If supplied, the code is taken from this string instead of a file.
}
\item{env}{
Environment where the R functions and modules should be made available.
}
\item{embeddedR}{
\code{TRUE} to run embedded R code chunks.
}
\item{rebuild}{
Force a rebuild of the shared library.
}
\item{showOutput}{
\code{TRUE} to print \code{R CMD SHLIB} output to the console.
}
\item{verbose}{
\code{TRUE} to print detailed information about generated code to the console.
}
\item{dryRun}{
\code{TRUE} to do a dry run (showing commands that would be used rather than
actually executing the commands).
}
}
\details{
If the \code{code} parameter is provided then the \code{file} parameter is ignored.
Functions exported using \code{sourceCpp} must meet several conditions,
including being defined in the global namespace and having return types
that are compatible with \code{Rcpp::wrap} and parameter types that are
compatible with \code{Rcpp::as}.
See the \code{\link[=exportAttribute]{Rcpp::export}} documentation for more details.
Content of Rcpp Modules will be automatically loaded into the specified
environment using the \code{\link[=Module]{Module}} and
\code{\link[=populate]{populate}} functions.
If the source file has compilation dependencies on other
packages (e.g. \pkg{Matrix}, \pkg{RcppArmadillo}) then an
\code{\link[=dependsAttribute]{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 \code{/*** R}. For example:
\preformatted{
/*** 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:
\tabular{ll}{
\code{functions} \tab Names of exported functions\cr
\code{modules} \tab Names of Rcpp modules\cr
}
}
\note{
The \code{sourceCpp} function will not rebuild the shared library if the source file has not changed since the last compilation.
The \code{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 \code{sourceCpp}. Note that the \code{\link[=exportAttribute]{Rcpp::export}} attribute can also be used within packages via the \code{\link{compileAttributes}} function.
If you are sourcing a C++ file from within the \code{src} directory of a package then the package's \code{LinkingTo} dependencies, \code{inst/include}, and \code{src} directories are automatically included in the compilation.
If no \code{Rcpp::export} attributes or \code{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 \code{rcpp.warnNoExports} option to \code{FALSE}.
}
\seealso{
\code{\link[=exportAttribute]{Rcpp::export}}, \code{\link[=dependsAttribute]{Rcpp::depends}}, \code{\link{cppFunction}}, \code{\link{evalCpp}}
}
\examples{
\dontrun{
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);
}'
)
}
}
|