[Rcpp-commits] r4508 - in pkg/Rcpp: . vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Sep 18 10:47:26 CEST 2013
Author: romain
Date: 2013-09-18 10:47:26 +0200 (Wed, 18 Sep 2013)
New Revision: 4508
Modified:
pkg/Rcpp/ChangeLog
pkg/Rcpp/vignettes/Rcpp-package.Rnw
Log:
updating the package vignett
Modified: pkg/Rcpp/ChangeLog
===================================================================
--- pkg/Rcpp/ChangeLog 2013-09-18 08:11:46 UTC (rev 4507)
+++ pkg/Rcpp/ChangeLog 2013-09-18 08:47:26 UTC (rev 4508)
@@ -1,3 +1,10 @@
+2013-09-16 Romain Francois <romain at r-enthusiasts.com>
+
+ * vignettes/Rcpp-package.Rnw: Updating the vignette. Setting attributes to TRUE
+ by default.
+ * R/Rcpp.package.skeleton.R: Setting attributes to TRUE by default. This is
+ what we should encourage people to use.
+
2013-09-17 JJ Allaire <jj at rstudio.org>
* R/Attributes.R: Call inlineCxxPlugin and Rcpp.plugin.maker without
Modified: pkg/Rcpp/vignettes/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/vignettes/Rcpp-package.Rnw 2013-09-18 08:11:46 UTC (rev 4507)
+++ pkg/Rcpp/vignettes/Rcpp-package.Rnw 2013-09-18 08:47:26 UTC (rev 4508)
@@ -116,26 +116,25 @@
\begin{Hchunk}
\begin{verbatim}
$ ls -1R mypackage/
-mypackage/:
DESCRIPTION
-man
NAMESPACE
R
Read-and-delete-me
+man
src
+mypackage/R:
+RcppExports.R
+
mypackage/man:
mypackage-package.Rd
rcpp_hello_world.Rd
-mypackage/R:
-rcpp_hello_world.R
-
mypackage/src:
Makevars
Makevars.win
+RcppExports.cpp
rcpp_hello_world.cpp
-rcpp_hello_world.h
$
\end{verbatim}
\end{Hchunk}
@@ -145,83 +144,88 @@
package, and it also includes the different components needed for using
\pkg{Rcpp} that we discuss in the following sections.
-\subsection{\proglang{R} code}
+\subsection{\proglang{C++} code}
-The skeleton contains an example \proglang{R} function
-\texttt{rcpp\_hello\_world} that uses the \Sexpr{link(".Call")} interface to
-invoke the \proglang{C++} function \texttt{rcpp\_hello\_world} from the
-package \texttt{mypackage}.
+If the \texttt{attributes} argument is set to
+\texttt{TRUE}\footnote{Setting \texttt{attributes} to \texttt{TRUE} is the default. This document
+does not cover the behavior of \texttt{Rcpp.package.skeleton} when \texttt{attributes} is set
+to \texttt{FALSE} as we try to encourage package developpers to use
+attributes. },
+the following \proglang{C++} file is included in the \texttt{src/} directory:
-<<lang=r>>=
-rcpp_hello_world <- function(){
- .Call( "rcpp_hello_world", PACKAGE = "mypackage" )
+<<lang=cpp>>=
+#include <Rcpp.h>
+using namespace Rcpp;
+
+// [[Rcpp::export]]
+List rcpp_hello_world() {
+
+ CharacterVector x = CharacterVector::create( "foo", "bar" ) ;
+ NumericVector y = NumericVector::create( 0.0, 1.0 ) ;
+ List z = List::create( x, y ) ;
+
+ return z ;
}
@
-\pkg{Rcpp} uses the \Sexpr{link(".Call")} calling convention as it allows
-transport of actual \proglang{R} objects back and forth between the
-\proglang{R} side and the \proglang{C++} side. \proglang{R} objects
-(\texttt{SEXP}) can be conveniently manipulated using the \pkg{Rcpp} API.
+The file defines the simple \texttt{rcpp\_hello\_world} function that
+uses a few \pkg{Rcpp} classes and returns a \texttt{List}.
-Note that in this example, no arguments were passed from \proglang{R} down to
-the \proglang{C++} layer. Doing so is straightforward (and one of the key
-features of \pkg{Rcpp}) but not central to our discussion of the package
-creation mechanics.
+This function is preceded by the \texttt{Rcpp::export} attribute to automatically
+handle argument conversion because \proglang{R} has to be taught how to
+e.g. handle the \texttt{List} class.
-\subsection{\proglang{C++} code}
+\Sexpr{link("Rcpp.package.skeleton")} then invokes \Sexpr{link("compileAttributes")}
+on the package, which generates the \texttt{RcppExports.cpp} file:
-The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
-header file:
-
<<lang=cpp>>=
-#ifndef _mypackage_RCPP_HELLO_WORLD_H
-#define _mypackage_RCPP_HELLO_WORLD_H
+// This file was generated by Rcpp::compileAttributes
+// Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
#include <Rcpp.h>
-/*
- * note : RcppExport is an alias to `extern "C"` defined by Rcpp.
- *
- * It gives C calling convention to the rcpp_hello_world function so that
- * it can be called from .Call in R. Otherwise, the C++ compiler mangles the
- * name of the function and .Call cannot find it.
- *
- * It is only useful to use RcppExport when the function is intended to be called
- * by .Call. See the thread http://thread.gmane.org/gmane.comp.lang.r.rcpp/649/focus=672
- * on Rcpp-devel for a misuse of RcppExport
- */
-RcppExport SEXP rcpp_hello_world() ;
+using namespace Rcpp;
-#endif
+// rcpp_hello_world
+List rcpp_hello_world();
+RcppExport SEXP mypackage_rcpp_hello_world() {
+BEGIN_RCPP
+ SEXP __sexp_result;
+ {
+ Rcpp::RNGScope __rngScope;
+ List __result = rcpp_hello_world();
+ PROTECT(__sexp_result = Rcpp::wrap(__result));
+ }
+ UNPROTECT(1);
+ return __sexp_result;
+END_RCPP
+}
@
-The header includes the \texttt{Rcpp.h} file, which is the only file that
-needs to be included to use \pkg{Rcpp}. The function is then implemented in
-the \texttt{rcpp\_hello\_world.cpp} file
+This file defines a function with the appropriate calling convention, suitable for
+\Sexpr{link(".Call")}. It needs to be regenerated each time functions
+exposed by attributes are modified. This is the task of the
+\Sexpr{link("compileAttributes")} function. A discussion on attributes is
+beyond the scope of this document and more information is available
+in the attributes vignette \citep{CRAN:Rcpp:Attributes}.
-<<lang=cpp>>=
-#include "rcpp_hello_world.h"
+\subsection{\proglang{R} code}
-SEXP rcpp_hello_world(){
- using namespace Rcpp ;
+The \Sexpr{link("compileAttributes")} also generates \proglang{R} code
+that uses the \proglang{C++} function.
- CharacterVector x = CharacterVector::create( "foo", "bar" ) ;
- NumericVector y = NumericVector::create( 0.0, 1.0 ) ;
- List z = List::create( x, y ) ;
+<<lang=cpp>>=
+# This file was generated by Rcpp::compileAttributes
+# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
- return z ;
+rcpp_hello_world <- function() {
+ .Call('mypackage_rcpp_hello_world', PACKAGE = 'mypackage')
}
@
-The function creates an \proglang{R} list that contains a
-\Sexpr{link("character")} vector and a \Sexpr{link("numeric")} vector using \pkg{Rcpp}
-classes. At the \proglang{R} level, we will therefore receive a list of
-length two containing these two vectors.
+This is also a generated file so it should not be modified manually, rather
+regenerated as needed by \Sexpr{link("compileAttributes")}.
-<<eval=FALSE>>=
-rcpp_hello_world( )
-@
-
\subsection{\texttt{DESCRIPTION}}
The skeleton generates an appropriate \texttt{DESCRIPTION} file, using
@@ -317,7 +321,7 @@
\Sexpr{link("Rcpp.package.skeleton")} will be loaded and thereby made
available to the newly created \proglang{R} package. Second, it declares
which functions should be globally visible from the namespace of this
-package. As a reasonable default, we export all functions.
+package. As a reasonable default, we export all functions.
\subsection{Help files}
@@ -403,19 +407,22 @@
\end{verbatim}
\end{Hchunk}
+\section{Using modules}
+This document does not cover the use of the \texttt{module} argument
+of \Sexpr{link("Rcpp.package.skeleton")}. It is covered
+in the modules vignette \citep{CRAN:Rcpp:Modules}.
+
\section{Further examples}
The canonical example of a package that uses \pkg{Rcpp} is the
\pkg{RcppExamples} \citep{CRAN:RcppExamples} package. \pkg{RcppExamples}
-contains various examples of using \pkg{Rcpp} using both the extended
-(``new'') API and the older (``classic'') API. Hence, the \pkg{RcppExamples}
+contains various examples of using \pkg{Rcpp}. Hence, the \pkg{RcppExamples}
package is provided as a template for employing \pkg{Rcpp} in packages.
Other CRAN packages using the \pkg{Rcpp} package are \pkg{RcppArmadillo}
-\citep{CRAN:RcppArmadillo}, \pkg{highlight} \citep{CRAN:highlight},
-and \pkg{minqa} \citep{CRAN:minqa} all of which follow precisely the guidelines
-of this document. Several other packages follow older (but still supported
+\citep{CRAN:RcppArmadillo},
+and \pkg{minqa} \citep{CRAN:minqa}. Several other packages follow older (but still supported
and appropriate) instructions. They can serve examples on how to get data to
and from \proglang{C++} routines, but should not be considered templates for
how to connect to \pkg{Rcpp}. The full list of packages using \pkg{Rcpp} can
More information about the Rcpp-commits
mailing list