[Rcpp-commits] r3998 - in pkg/Rcpp: . inst inst/doc/Rcpp-attributes man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Mon Nov 19 21:11:32 CET 2012
Author: jjallaire
Date: 2012-11-19 21:11:32 +0100 (Mon, 19 Nov 2012)
New Revision: 3998
Modified:
pkg/Rcpp/ChangeLog
pkg/Rcpp/TODO
pkg/Rcpp/inst/NEWS.Rd
pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
pkg/Rcpp/man/compileAttributes.Rd
pkg/Rcpp/man/sourceCpp.Rd
Log:
update vignette for changes to attributes in 0.10.1
Modified: pkg/Rcpp/ChangeLog
===================================================================
--- pkg/Rcpp/ChangeLog 2012-11-19 14:41:12 UTC (rev 3997)
+++ pkg/Rcpp/ChangeLog 2012-11-19 20:11:32 UTC (rev 3998)
@@ -4,6 +4,10 @@
* src/AttributesParser.cpp: support for argument default values
* src/Attributes.cpp: support for argument default values
* man/exportAttribute.Rd: documentation updates
+ * man/compileAttributes.Rd: documentation updates
+ * man/sourceCpp.Rd: documentation updates
+ * inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw: add documentation
+ on changes to attributes in 0.10.1
2012-11-18 JJ Allaire <jj at rstudio.org>
Modified: pkg/Rcpp/TODO
===================================================================
--- pkg/Rcpp/TODO 2012-11-19 14:41:12 UTC (rev 3997)
+++ pkg/Rcpp/TODO 2012-11-19 20:11:32 UTC (rev 3998)
@@ -135,9 +135,6 @@
o Typechecking on CppFunction calls so that seg-faults don't occur
when passing incorrect types
- o Clarify in 5.1 of vignette that attribute package features still
- require Makevars, etc. created by Rcpp.package.skeleton
-
o Add docstring parameter to Rcpp::export attribute
Testing
Modified: pkg/Rcpp/inst/NEWS.Rd
===================================================================
--- pkg/Rcpp/inst/NEWS.Rd 2012-11-19 14:41:12 UTC (rev 3997)
+++ pkg/Rcpp/inst/NEWS.Rd 2012-11-19 20:11:32 UTC (rev 3998)
@@ -22,7 +22,8 @@
\itemize{
\item Ability to embed R code chunks (via specially formatted
block comments) in C++ source files
- \item New scheme for more flexible mixing of user and generated
+ \item Allow specification of argument defaults for exported functions
+ \item New scheme for more flexible mixing of generated and user composed
C++ headers
\item Print warning if no export attributes are found in source file
}
Modified: pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw 2012-11-19 14:41:12 UTC (rev 3997)
+++ pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw 2012-11-19 20:11:32 UTC (rev 3998)
@@ -19,7 +19,6 @@
\newcommand{\proglang}[1]{\textsf{#1}}
\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
-\newcommand{\ith}{\textsl{i}-\textsuperscript{th}}
\newcommand{\code}[1]{\texttt{#1}}
<<echo=FALSE,print=FALSE>>=
@@ -83,7 +82,7 @@
\noindent
\textsl{Rcpp attributes} provide a high-level syntax for declaring \proglang{C++}
functions as callable from \proglang{R} and automatically generating the code
- required to invoke them. Attributes are intended to facilate both interactive use
+ required to invoke them. Attributes are intended to facilitate both interactive use
of \proglang{C++} within \proglang{R} sessions as well as to support \proglang{R}
package development. Attributes are built on top of \pkg{Rcpp} modules
and their implementation is based on previous work in the \pkg{inline}
@@ -138,8 +137,10 @@
\pagebreak
-\section{Sourcing C++ Functions}
+\section{Using Attributes}
+\subsection{Sourcing C++ Functions}
+
The \texttt{sourceCpp} function parses a \proglang{C++} file and looks for
functions marked with the \texttt{Rcpp::export} attribute. A shared
library is then built and its exported functions are made available as R
@@ -218,15 +219,64 @@
can be used in the signatures of exported functions (and since as and wrap are
in turn extensible, a wide variety of custom types can be supported).
-You can change the name of the exported function as it appears to \proglang{R} by
-adding a name parameter to \texttt{Rcpp::export}. For example the
-following will export \texttt{convolveCpp} as a hidden \proglang{R} function:
+The \texttt{sourceCpp} function performs caching based on the last
+modified date of the source file so as long as the source file does not
+change the compilation will occur only once per R session.
+\pagebreak
+
+\subsection{Specifying Argument Defaults}
+
+If default argument values are provided in the C++ function definition
+then these defaults are also used for the exported R function. For example,
+the following C++ function:
+
% \begin{verbatim}
+% DataFrame readData(
+% CharacterVector file,
+% CharacterVector exclude = CharacterVector::create(),
+% bool fill = true)
+% \end{verbatim}
+\begin{kframe}
+\noindent
+\ttfamily
+\hlstd{\hspace*{\fill}\\
+DataFrame\ }\hlkwd{readData}\hlstd{}\hlopt{(}\hspace*{\fill}\\
+\hlstd{}\hlstd{\ \ \ \ }\hlstd{CharacterVector\ file}\hlopt{,\ }\hspace*{\fill}\\
+\hlstd{}\hlstd{\ \ \ \ }\hlstd{CharacterVector\ exclude\ }\hlopt{=\ }\hlstd{CharacterVector}\hlopt{::}\hlstd{}\hlkwd{create}\hlstd{}\hlopt{(),}\hspace*{\fill}\\
+\hlstd{}\hlstd{\ \ \ \ }\hlstd{}\hlkwb{bool\ }\hlstd{fill\ }\hlopt{=\ }\hlstd{}\hlkwa{true}\hlstd{}\hlopt{)}\hspace*{\fill}
+\mbox{}
+\normalfont
+\normalsize
+\end{kframe}
+
+Will be exported to R as:
+
+% \begin{verbatim}
+% function (file, exclude = character(0), fill = TRUE)
+% \end{verbatim}
+\begin{kframe}
+\noindent
+\ttfamily
+\hlstd{}\hlkwa{function\ }\hlstd{}\hlopt{(}\hlstd{file}\hlopt{,\ }\hlstd{exclude\ }\hlopt{=\ }\hlstd{}\hlkwd{character}\hlstd{}\hlopt{(}\hlstd{}\hlnum{0}\hlstd{}\hlopt{),\ }\hlstd{fill\ }\hlopt{=\ }\hlstd{}\hlkwb{TRUE}\hlstd{}\hlopt{)}\hlstd{}\hspace*{\fill}
+\mbox{}
+\normalfont
+\normalsize
+\end{kframe}
+
+Note that C++ rules for default arguments still apply: they must occur
+consecutively at the end of the function signature and (unlike R) can't rely
+on the values of other arguments.
+
+\subsection{Modifying Function Names}
+
+You can change the name of an exported function as it appears to \proglang{R} by
+adding a name parameter to \texttt{Rcpp::export}. For example:
+
+% \begin{verbatim}
% // [[Rcpp::export(".convolveCpp")]]
% NumericVector convolveCpp(NumericVector a, NumericVector b)
% \end{verbatim}
-
\begin{kframe}
\noindent
\ttfamily
@@ -237,13 +287,31 @@
\normalsize
\end{kframe}
-The \texttt{sourceCpp} function performs caching based on the last
-modified date of the source file so as long as the source file does not
-change the compilation will occur only once per R session.
+Note that in this case since the specified name is prefaced by a \code{.} the exported R
+function will be hidden.
+\subsection{Function Requirements}
+
+Functions marked with the \texttt{Rcpp::export} attribute must meet several
+requirements to be correctly handled:
+
+\begin{itemize}
+\item
+ Be defined in the global namespace (i.e. not within a C++ namespace declaration)
+\item
+ Have a return type that is either void or compatible with \texttt{Rcpp::wrap}
+ and parameter types that are compatible with \texttt{Rcpp::as} (see sections
+ 3.1 and 3.2 of the `\textsl{Rcpp-introduction}' vignette for more details).
+ \item
+ Use fully qualified type names for the return value and all parameters.
+ Rcpp types may however appear without a namespace qualifier (i.e.
+ \texttt{DataFrame} is okay as a type name but \texttt{std::string} must be
+ specified fully).
+\end{itemize}
+
\pagebreak
-\section{Importing Dependencies}
+\subsection{Importing Dependencies}
It's also possible to use the \texttt{Rcpp::depends} attribute to declare
dependencies on other packages. For example:
@@ -328,15 +396,53 @@
\pagebreak
-\section{Using C++ Inline}
+\subsection{Embedding R Code}
+Typically \proglang{C++} and \proglang{R} code are kept in their own source
+files. However, it's often convenient to bundle code from both languages into
+a common source file that can be executed using single call to \texttt{sourceCpp}.
+
+To embed chunks of \proglang{R} code within a \proglang{C++}
+source file you include the \proglang{R} code within a block comment that
+has the prefix of \texttt{/*** R}. For example:
+
+% \begin{verbatim}
+% /*** R
+%
+% # Call the fibonacci function defined in C++
+% fibonacci(10)
+%
+% */
+% \end{verbatim}
+\begin{kframe}
+\noindent
+\ttfamily
+\hlstd{}\hlopt{/{*}{*}{*}\ }\hlstd{R}\hspace*{\fill}\\
+\hspace*{\fill}\\
+\hlslc{\#\ Call\ the\ fibonacci\ function\ defined\ in\ C++}\hspace*{\fill}\\
+\hlstd{}\hlkwd{fibonacci}\hlstd{}\hlopt{(}\hlstd{}\hlnum{10}\hlstd{}\hlopt{)}\hspace*{\fill}\\
+\hlstd{}\hspace*{\fill}\\
+\hlopt{{*}/}\hlstd{}\hspace*{\fill}
+\mbox{}
+\normalfont
+\normalsize
+\end{kframe}
+
+Multiple \proglang{R} code chunks can be included in a \proglang{C++} file. The
+\texttt{sourceCpp} function will first compile the \proglang{C++} code into a
+shared library and then source the embedded \proglang{R} code.
+
+\subsection{Using C++ Inline}
+
Maintaining C++ code in it's own source file provides several benefits including
the ability to use \proglang{C++} aware text-editing tools and straightforward
mapping of compilation errors to lines in the source file. However, it's also
-possible to do inline declaration and execution of C++ code. This is accomplished
-by either passing a code string to \texttt{sourceCpp} or using the shorter-form
-\texttt{cppFunction} or \texttt{evalCpp} functions. For example:
+possible to do inline declaration and execution of C++ code.
+There are several ways to accomplish this, including passing a code
+string to \texttt{sourceCpp} or using the shorter-form \texttt{cppFunction}
+or \texttt{evalCpp} functions. For example:
+
% \begin{verbatim}
% > cppFunction('
% int fibonacci(const int x) {
@@ -383,23 +489,27 @@
\normalsize
\end{kframe}
-Note that using \texttt{sourceCpp}, \texttt{cppFunction}, and \texttt{evalCpp}
-require that \proglang{C++} development tools be available to build the code.
-If you want to distribute \pkg{Rcpp} code to users that don't have these tools
-installed you can bundle your code into an R package. The next section describes
-how you can use \pkg{Rcpp} attributes for package development.
-
\section{Package Development}
+Using \texttt{sourceCpp} requires that \proglang{C++} development tools be
+available to build the code. If you want to distribute code to
+users that don't have these tools installed you should bundle your code into
+an R package.
+
+To build a package that is based on \pkg{Rcpp} you should first follow the
+guidelines in the `\textsl{Rcpp-package}' vignette (for a new package this
+typically entails creating the package using \texttt{Rcpp.package.skeleton}).
+
\subsection{Exporting R Functions}
-\proglang{C++} source code that uses attributes to export R functions can also be
-included in an \proglang{R} package. In this case rather than calling \texttt{sourceCpp}
-on individual files you call a single utility function for the whole package.
-The \texttt{compileAttributes} function scans the source files within a package
-for export attributes and generates code as required.
+Within interactive sessions you call the \texttt{sourceCpp} function
+on individual files to export \proglang{C++} functions into the global
+environment. However, for packages you call a single utility function to
+export all \proglang{C++} functions within the package.
-For example, executing this from within the package working directory:
+ The \texttt{compileAttributes} function scans the source files within a package
+for export attributes and generates code as required. For example, executing
+this from within the package working directory:
% \begin{verbatim}
% > compileAttributes()
@@ -424,10 +534,16 @@
\pkg{Rcpp} module
\end{itemize}
-The generated code deals only with interface of functions rather than the
-implementation, so \texttt{compileAttributes} needs to be run only when functions
-are added, removed, or have their signatures changed.
+You should re-run \texttt{compileAttributes} whenever functions are added,
+removed, or have their signatures changed.
+The \texttt{compileAttributes} function deals only with exporting
+\proglang{C++} functions to \proglang{R}. If you want the functions to
+additionally be publicly available from your package's namespace another
+step may be required. Specifically, if your package \texttt{NAMESPACE} file
+does not use a pattern to export functions then you should add an explicit
+entry to \texttt{NAMESPACE} for each R function you want publicly available.
+
\subsection{Providing a C++ Interface}
You can use the \texttt{Rcpp::interfaces} attribute to expose the underlying
@@ -448,15 +564,23 @@
\end{kframe}
The \texttt{Rcpp::interfaces} attribute is specified on a per-source file basis.
-If you request a \texttt{cpp} interface for a source file then \texttt{compileAttributes}
-does the following:
+If you request a \texttt{cpp} interface for a source file then
+\texttt{compileAttributes} does the following:
\begin{enumerate}
\item
Bindings are generated into a header file located in the
\texttt{inst/include} directory of the package using the naming
- convention \emph{PackageName.h}
+ convention \code{PackageName\_RcppExports.h}
\item
+ If not already present, an additional header file named \code{PackageName.h}
+ is also generated which in turn includes \code{PackageName\_RcppExports.h}
+
+ In the case that you already have a \code{PackageName.h} header for your
+ package then you can manually add an include of
+ \code{PackageName\_RcppExports.h} to it to make the exported
+ functions available to users of your package.
+\item
The generated header file enables calling the exported \proglang{C++}functions
without any linking dependency on the package. This is based on using the
\texttt{R\_RegisterCCallable} and \texttt{R\_GetCCallable} functions described
@@ -497,6 +621,27 @@
Note that the default behavior if an \texttt{Rcpp::interfaces} attribute
is not included in a source file is to generate an R interface only.
+\subsection{Packages and sourceCpp}
+
+One of the goals of \pkg{Rcpp} attributes is to simultaneously facilitate
+ad-hoc and interactive work with \proglang{C++} while also making it very easy to
+migrate that work into an \proglang{R} package. Two major benefits of moving code
+from a standalone \proglang{C++} source file to a package are:
+
+\begin{enumerate}
+\item
+ Users without \proglang{C++} development tools available can use your code.
+\item
+ Multiple source files and their dependencies are handled automatically
+ by the \proglang{R} package build system.
+\end{enumerate}
+
+Once you've migrated \proglang{C++} code into a package it's still possible use
+\texttt{sourceCpp} with it for iterative development. The main thing to keep in
+mind is that the dependencies for source files within a package are derived from
+the \texttt{Depends} and \texttt{LinkingTo} fields in the package
+\texttt{DESCRIPTION} file rather than the \texttt{Rcpp::depends} attribute.
+
\pagebreak
\subsection{Using Roxygen}
@@ -523,7 +668,6 @@
\noindent
\ttfamily
\hlstd{}\hlslc{//\textquotesingle\ The\ length\ of\ a\ string\ (in\ characters).}\hspace*{\fill}\\
-\hlstd{}\hlslc{//\textquotesingle}\hspace*{\fill}\\
\hlstd{}\hlslc{//\textquotesingle\ @param\ str\ input\ character\ vector}\hspace*{\fill}\\
\hlstd{}\hlslc{//\textquotesingle\ @return\ characters\ in\ each\ element\ of\ the\ vector}\hspace*{\fill}\\
\hlstd{}\hlslc{//\ {[}{[}Rcpp::export{]}{]}}\hspace*{\fill}\\
@@ -547,7 +691,6 @@
\noindent
\ttfamily
\hlstd{}\hlslc{\#\textquotesingle\ The\ length\ of\ a\ string\ (in\ characters).}\hspace*{\fill}\\
-\hlstd{}\hlslc{\#\textquotesingle}\hspace*{\fill}\\
\hlstd{}\hlslc{\#\textquotesingle\ @param\ str\ input\ character\ vector}\hspace*{\fill}\\
\hlstd{}\hlslc{\#\textquotesingle\ @return\ characters\ in\ each\ element\ of\ the\ vector}\hspace*{\fill}\\
\hlstd{strLength\ }\hlopt{$<${-}\ }\hlstd{}\hlkwa{function}\hlstd{}\hlopt{(}\hlstd{str}\hlopt{)}\hlstd{}\hspace*{\fill}
@@ -556,27 +699,18 @@
\normalsize
\end{kframe}
-\subsection{Packages and sourceCpp}
-
-One of the goals of \pkg{Rcpp} attributes is to simultaneously facilitate
-ad-hoc and interactive work with \proglang{C++} while also making it very easy to
-migrate that work into an \proglang{R} package. Two major benefits of moving code
-from a standalone \proglang{C++} source file to a package are:
-
+Two notes about the R functions written to \texttt{RcppExports.R} for use with
+roxygen:
\begin{enumerate}
-\item
- Users without \proglang{C++} development tools available can use your code.
-\item
- Multiple source files and their dependencies are handled automatically
- by the \proglang{R} package build system.
+\item The generated R functions have an empty body. This is because they are
+only present for binding to roxygen comments (they'll be replaced by the
+corresponding \proglang{C++} functions by \texttt{loadModule}).
+\item The functions do not include argument defaults since they are
+not known at the time of generation. If you have argument defaults that you'd
+like included in the Rd usage section you can do this by adding an explicit
+\texttt{@usage} roxygen tag.
\end{enumerate}
-Once you've migrated \proglang{C++} code into a package it's still possible use
-\texttt{sourceCpp} with it for iterative development. The main thing to keep in
-mind is that the dependencies for source files within a package are derived from
-the \texttt{Depends} and \texttt{LinkingTo} fields in the package
-\texttt{DESCRIPTION} file rather than the \texttt{Rcpp::depends} attribute.
-
\pagebreak
\bibliographystyle{plainnat}
Modified: pkg/Rcpp/man/compileAttributes.Rd
===================================================================
--- pkg/Rcpp/man/compileAttributes.Rd 2012-11-19 14:41:12 UTC (rev 3997)
+++ pkg/Rcpp/man/compileAttributes.Rd 2012-11-19 20:11:32 UTC (rev 3998)
@@ -30,6 +30,8 @@
}
\note{
+ The \code{compileAttributes} function deals only with exporting C++ functions to R. If you want the functions to additionally be publicly available from your package's namespace another step may be required. Specifically, if your package \code{NAMESPACE} file does not use a pattern to export functions then you should add an explicit entry to \code{NAMESPACE} for each R function you want publicly available.
+
In addition to exporting R bindings for C++ functions, the \code{compileAttributes} function can also generate a direct C++ interface to the functions using the \code{\link[=interfacesAttribute]{Rcpp::interfaces}} attribute.
}
Modified: pkg/Rcpp/man/sourceCpp.Rd
===================================================================
--- pkg/Rcpp/man/sourceCpp.Rd 2012-11-19 14:41:12 UTC (rev 3997)
+++ pkg/Rcpp/man/sourceCpp.Rd 2012-11-19 20:11:32 UTC (rev 3998)
@@ -39,7 +39,7 @@
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 the C++ that will be sourced alone with the C++ functions. This is done by starting a block comment with the prefix of \code{/*** R}. For example:
+ 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
@@ -49,8 +49,8 @@
*/
}
-
- The \code{sourceCpp} function will not rebuild the shared library if the source file has not changed since the last compilation.
+
+ Multiple R code chunks can be included in a C++ file. All R code is sourced after the C++ functions within the file have been defined.
}
\value{
@@ -58,6 +58,8 @@
}
\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.
More information about the Rcpp-commits
mailing list