updating the package vignett

Author: romainfrancois

ChangeLog

@@ -1,3 +1,10 @@
+2013-09-16  Romain Francois <romain@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@rstudio.org>
 
 	* R/Attributes.R: Call inlineCxxPlugin and Rcpp.plugin.maker without

vignettes/Rcpp-package.Rnw

@@ -116,26 +116,25 @@ Rcpp.package.skeleton("mypackage")
 \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,82 +144,87 @@ as it fulfills two roles. It creates the complete set of files needed for a
 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=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 ) ;
 
-<<lang=r>>=
-rcpp_hello_world <- function(){
-	.Call( "rcpp_hello_world", PACKAGE = "mypackage" )
+    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.
-
-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.
+The file defines the simple \texttt{rcpp\_hello\_world} function that
+uses a few \pkg{Rcpp} classes and returns a \texttt{List}. 
 
-\subsection{\proglang{C++} code}
+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. 
 
-The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
-header file:
+\Sexpr{link("Rcpp.package.skeleton")} then invokes \Sexpr{link("compileAttributes")}
+on the package, which generates the \texttt{RcppExports.cpp} 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() ;
-
-#endif
+using namespace Rcpp;
+
+// 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.
-
-<<eval=FALSE>>=
-rcpp_hello_world( )
-@
+This is also a generated file so it should not be modified manually, rather
+regenerated as needed by \Sexpr{link("compileAttributes")}. 
 
 \subsection{\texttt{DESCRIPTION}}
 
@@ -317,7 +321,7 @@ contained in the package we are creating via
 \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 @@ rcpp_hello_world()
 \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