[Rcpp-commits] r3915 - in pkg/Rcpp: . man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Nov 7 23:18:34 CET 2012
Author: jjallaire
Date: 2012-11-07 23:18:34 +0100 (Wed, 07 Nov 2012)
New Revision: 3915
Added:
pkg/Rcpp/man/interfacesAttribute.Rd
Modified:
pkg/Rcpp/ChangeLog
pkg/Rcpp/man/compileAttributes.Rd
pkg/Rcpp/man/dependsAttribute.Rd
pkg/Rcpp/man/exportAttribute.Rd
pkg/Rcpp/man/sourceCpp.Rd
Log:
update and enhance documentation
Modified: pkg/Rcpp/ChangeLog
===================================================================
--- pkg/Rcpp/ChangeLog 2012-11-07 20:10:21 UTC (rev 3914)
+++ pkg/Rcpp/ChangeLog 2012-11-07 22:18:34 UTC (rev 3915)
@@ -11,7 +11,12 @@
* src/AttributesParser.cpp: add signature and isHidden methods
* src/exceptions.cpp: add function_not_exported exception
* include/Rcpp/exceptions.h: add function_not_exported exception
- * man/cppFunction.Rd: update documentation on depends parameter
+ * man/cppFunction.Rd: update documentation
+ * man/sourceCpp.Rd: update documentation
+ * man/compileAttributes.Rd: update documentation
+ * man/dependsAttribute.Rd: update documentation
+ * man/exportAttribute.Rd: update documentation
+ * man/interfacesAttribute.Rd: update documentation
2012-11-07 Romain Francois <romain at r-enthusiasts.com>
Modified: pkg/Rcpp/man/compileAttributes.Rd
===================================================================
--- pkg/Rcpp/man/compileAttributes.Rd 2012-11-07 20:10:21 UTC (rev 3914)
+++ pkg/Rcpp/man/compileAttributes.Rd 2012-11-07 22:18:34 UTC (rev 3915)
@@ -29,8 +29,12 @@
Returns (invisibly) a character vector with the paths to any files that were updated as a result of the call.
}
+\note{
+ 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.
+}
+
\seealso{
-\code{\link[=exportAttribute]{Rcpp::export}}
+\code{\link[=exportAttribute]{Rcpp::export}}, \code{\link[=interfacesAttribute]{Rcpp::interfaces}}
}
Modified: pkg/Rcpp/man/dependsAttribute.Rd
===================================================================
--- pkg/Rcpp/man/dependsAttribute.Rd 2012-11-07 20:10:21 UTC (rev 3914)
+++ pkg/Rcpp/man/dependsAttribute.Rd 2012-11-07 22:18:34 UTC (rev 3915)
@@ -19,13 +19,15 @@
\details{
The \code{Rcpp::depends} attribute is used by the implementation of the \code{\link{sourceCpp}} function to correctly setup the build environment for \code{R CMD SHLIB}.
- The include directories of the specified packages are added to the \code{PKG_CXXFLAGS} environment varible. In addition, if the referenced package provides an \link[inline:plugins]{inline plugin} it is called to determine additional environment variables required to sucessfully build.
-
- The \code{Rcpp::depends} attribute is specified using a syntax compatible with the new \href{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf}{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).
+ The include directories of the specified packages are added to the \code{CLINK_CPPFLAGS} environment variable. In addition, if the referenced package provides an \link[inline:plugins]{inline plugin} it is called to determine additional environment variables required to successfully build.
}
+\note{
+ The \code{Rcpp::depends} attribute is specified using a syntax compatible with the new \href{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf}{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).
+}
+
\seealso{
\code{\link{sourceCpp}}
}
Modified: pkg/Rcpp/man/exportAttribute.Rd
===================================================================
--- pkg/Rcpp/man/exportAttribute.Rd 2012-11-07 20:10:21 UTC (rev 3914)
+++ pkg/Rcpp/man/exportAttribute.Rd 2012-11-07 22:18:34 UTC (rev 3915)
@@ -14,12 +14,20 @@
}
\details{
- Functions marked with the \code{Rcpp::export} attribute must have return types that are compatible with \code{Rcpp::wrap} and parameter types that are compatible with \code{Rcpp::as}.
+ Functions marked with the \code{Rcpp::export} attribute must meet several conditions to be correctly handled:
+\enumerate{
+ \item Be defined in the global namespace (i.e. not within a C++ \code{namespace} declaration).
+ \item Have a return type that is either void or compatible with \code{Rcpp::wrap} and parameter types that are compatible with \code{Rcpp::as} (see sections 3.1 and 3.2 of the \emph{Rcpp-introduction} vignette for more details).
+ \item Use fully qualified type names for the return value and all parameters. However, Rcpp types may appear without the namespace qualifier (i.e. \code{DataFrame} is okay as a type name but \code{std::string} must be specified fully).
+}
+}
+
+\note{
+ When a C++ function has export bindings automatically generated by the \code{\link{compileAttributes}} function, it can optionally also have a direct C++ interface generated using the \code{\link[=interfacesAttribute]{Rcpp::interfaces}} attribute.
The \code{Rcpp::export} attribute is specified using a syntax compatible with the new \href{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf}{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).
}
-
\seealso{
\code{\link{sourceCpp}}, \code{\link{compileAttributes}}
}
@@ -27,6 +35,10 @@
\examples{
\dontrun{
+#include <Rcpp.h>
+
+using namespace Rcpp;
+
// [[Rcpp::export]]
int fibonacci(const int x) {
Added: pkg/Rcpp/man/interfacesAttribute.Rd
===================================================================
--- pkg/Rcpp/man/interfacesAttribute.Rd (rev 0)
+++ pkg/Rcpp/man/interfacesAttribute.Rd 2012-11-07 22:18:34 UTC (rev 3915)
@@ -0,0 +1,65 @@
+\name{interfacesAttribute}
+\alias{interfacesAttribute}
+
+\title{Rcpp::interfaces Attribute}
+
+\description{
+The \code{Rcpp::interfaces} attribute is added to a C++ source file to specify which languages to generate bindings for from exported functions. For example:
+\preformatted{
+// [[Rcpp::interfaces(r, cpp)]]
+}
+}
+
+\arguments{
+ \item{\dots}{
+ Interfaces to generate for exported functions within the source file. Valid values are \code{r} and \code{cpp}, and more than one interface can be specified.
+}
+}
+
+\details{
+ The \code{Rcpp::interfaces} attribute is used to determine which bindings to generate for exported functions. The default behavior if no \code{Rcpp::interfaces} attribute is specified is to generate only an R interface.
+
+ When \code{cpp} bindings are requested code is generated as follows:
+
+\enumerate{
+ \item Bindings are generated into a header file located in the \code{inst/include} directory of the package using the naming convention \emph{PackageName.hpp}
+ \item The generated header file allows calling the exported C++ functions without any linking dependency on the package (this is based on using the \code{R_RegisterCCallable} and \code{R_GetCCallable} functions).
+ \item The exported functions are defined within a C++ namespace that matches the name of the package.
+}
+For example, an exported C++ function \code{foo} could be called from package \code{MyPackage} as follows:
+
+\preformatted{
+ // [[Rcpp::depends(MyPackage)]]
+
+ #include <MyPackage.hpp>
+
+ void foo() {
+ MyPackage::bar();
+ }
+}
+
+ The above example assumes that the \code{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 \code{Rcpp::depends} attribute, but instead should add an entry for the referenced package in the \code{Depends} and \code{LinkingTo} fields of your package's \code{DESCRIPTION} file.
+
+}
+
+\note{
+
+ If a file by the name of \emph{PackageName.hpp} that wasn't generated by \code{compileAttributes} already exists in in the \code{inst/include} directory then it will not be overwritten (rather, an error will occur).
+
+ A static naming scheme for generated header files is used to ensure consistent usage semantics for clients of exported \code{cpp} interfaces. Packages that wish to export more complex interfaces or additional C++ types are therefore typically better off not using this mechanism.
+
+ The \code{Rcpp::interfaces} attribute is specified using a syntax compatible with the new \href{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf}{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).
+}
+
+
+\seealso{
+\code{\link{compileAttributes}}, \code{\link[=exportAttribute]{Rcpp::export}}, \code{\link[=dependsAttribute]{Rcpp::depends}}
+}
+
+\examples{
+\dontrun{
+
+// [[Rcpp::interfaces(r, cpp)]]
+}
+}
+
Modified: pkg/Rcpp/man/sourceCpp.Rd
===================================================================
--- pkg/Rcpp/man/sourceCpp.Rd 2012-11-07 20:10:21 UTC (rev 3914)
+++ pkg/Rcpp/man/sourceCpp.Rd 2012-11-07 22:18:34 UTC (rev 3915)
@@ -13,10 +13,10 @@
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{file}{
- A character string giving the pathname of a file
+ A character string giving the path name of a file
}
\item{code}{
- A charcter string with source code. If supplied, the code is taken from this string instead of a file.
+ 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 should be made available.
@@ -34,9 +34,9 @@
\details{
If the \code{code} parameter is provided then the \code{file} parameter is ignored.
- Functions marked with the \code{\link[=exportAttribute]{Rcpp::export}} attribute must have return types that are compatible with \code{Rcpp::wrap} and parameter types that are compatible with \code{Rcpp::as}.
+ 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.
- If the code has compilation dependencies on other packages (e.g. \pkg{Matrix}, \pkg{RcppArmadillo}) then an \code{\link[=dependsAttribute]{Rcpp::depends}} attribute should be added naming these dependencies.
+ If the code has compilation dependencies on other packages (e.g. \pkg{Matrix}, \pkg{RcppArmadillo}) then an \code{\link[=dependsAttribute]{Rcpp::depends}} attribute should be added naming these dependencies. Note that if you are sourcing a C++ file from within the \code{src} directory of a package then the package's \code{LinkingTo} dependencies are automatically included in the compilation.
The \code{sourceCpp} function will not rebuild the shared library if the underlying code has not changed since the last compilation.
}
More information about the Rcpp-commits
mailing list