[Rcpp-commits] r1439 - pkg/Rcpp/inst/doc/Rcpp-package

Sat Jun 5 21:32:12 CEST 2010

Author: edd
Date: 2010-06-05 21:32:12 +0200 (Sat, 05 Jun 2010)
New Revision: 1439

Modified:
   pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
Log:
coupe of edits while away with the netbook 
two new subsection for NAMESPACE and help files


Modified: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
===================================================================

--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw	2010-06-05 17:12:50 UTC (rev 1438)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw	2010-06-05 19:32:12 UTC (rev 1439)
@@ -74,34 +74,38 @@
 \maketitle
 
 \abstract{
-  \noindent This document provides a short overview of the suggested process
-  to follow when writing an R package using \pkg{Rcpp}~\citep{CRAN:Rcpp}.
-  This document complements the \textsl{Writing R Extensions}
-  manual~\citep{R:exts} which is the authoritative source. We strongly
-  encourage the reader to familiarize himself with that manual before reading
-  this document.
+  \noindent This document provides a short overview of how to use
+  \pkg{Rcpp}~\citep{CRAN:Rcpp} when writing an \proglang{R} package.  It
+  complements the \textsl{Writing R Extensions} manual~\citep{R:exts} which
+  is the authoritative source on how to extend \proglang{R} in general. We
+  strongly encourage the reader to familiarize himself with that manual
+  before reading this document which provides additional information on using
+  \pkg{Rcpp} in add-on packages.
 }
 
 \section{Introduction}
 
-\pkg{Rcpp}~\citep{CRAN:Rcpp} is somewhat different from a traditional R
-package because its key component is a \proglang{C++} library. A client
-that wants to make use of \pkg{Rcpp} features must link against this library
+\pkg{Rcpp}~\citep{CRAN:Rcpp} is an extension package for \proglang{R}.
+However, it is somewhat different from a traditional \proglang{R} package
+because its key component is a \proglang{C++} library. A client package that
+wants to make use of the \pkg{Rcpp} features must link against the library
 provided by \pkg{Rcpp}.
 
-However, \proglang{R}~\citep{R:exts} only has limited support for \proglang{C(++)} level
-dependencies between packages. The \texttt{LinkingTo} declaration in the
-package \texttt{DESCRIPTION} file allows the client package to retrieve the
-headers of the target package (here \pkg{Rcpp}), but support for
-linking against a library is missing and has to be dealt with manually.
+However, \proglang{R} only has limited support for \proglang{C(++)}-level
+dependencies between packages~\citep{R:exts}. The \texttt{LinkingTo}
+declaration in the package \texttt{DESCRIPTION} file allows the client
+package to retrieve the headers of the target package (here \pkg{Rcpp}), but
+support for linking against a library is not provided by \proglang{R} and has
+to be added manually.
 
 This document follows the steps of the \Sexpr{link("Rcpp.package.skeleton")}
 function to illustrate a recommended way of using \pkg{Rcpp} from a client
-package.
+package. We illustrate this using a simple \proglang{C++} function
+which will be called by an \proglang{R} function.
 
 \section{Rcpp.package.skeleton}
 
-\pkg{Rcpp} includes a function \Sexpr{link("Rcpp.package.skeleton")}, modeled
+\pkg{Rcpp} provides a function \Sexpr{link("Rcpp.package.skeleton")}, modeled
 after the base \proglang{R} function \Sexpr{link("package.skeleton")}, which
 facilitates creation of a skeleton package using \pkg{Rcpp}.
 
@@ -162,17 +166,18 @@
 
 \subsection{R code}
 
-The skeleton contains an \proglang{R} function \texttt{rcpp\_hello\_world}
-that uses the \Sexpr{link(".Call")} interface to invoke the
-\proglang{C++} function called \texttt{rcpp\_hello\_world} from the package.
+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.
 
 <<echo=FALSE,results=tex>>=
 ex_highlight( file.path( gendir, "mypackage", "R", "rcpp_hello_world.R" ), FALSE )
 @
 
-\pkg{Rcpp} users employ the \Sexpr{link(".Call")} calling convention
-because it allows transport of actual \proglang{R} objects back and forth
-between the \proglang{R} side and the \proglang{C++} side. \proglang{R} objects
+\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.
 
 \subsection{C++ code}
@@ -208,10 +213,10 @@
 \Sexpr{link("Rcpp.package.skeleton")} adds the three last lines to the
 \texttt{DESCRIPTION} file generated by \Sexpr{link("package.skeleton")}.
 
-The \texttt{Depends} declaration indicates R-level dependency between
-the client package and \pkg{Rcpp}. The \texttt{LinkingTo}
-declaration indicates that the client package needs to use
-header files exposed by \pkg{Rcpp}.
+The \texttt{Depends} declaration indicates \proglang{R}-level dependency
+between the client package and \pkg{Rcpp}. The \texttt{LinkingTo} declaration
+indicates that the client package needs to use header files exposed by
+\pkg{Rcpp}.
 
 The \texttt{SystemRequirements} declaration indicates that the package depends
 on \proglang{GNU Make} which is needed when compiling the client package
@@ -250,19 +255,40 @@
 extension to the standard \proglang{Make} language which we have found to be
 more reliable than using backticks.
 
-\section{Examples}
+\subsection{NAMESPACE}
 
-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}, through
-both the extended newer API and the older API. The \pkg{RcppExamples} package
-is provided  as a model for employing \pkg{Rcpp} in packages.
+The \texttt{Rcpp.package.skeleton()} function also creates a file
+\texttt{NAMESPACE}. This file serves two purposes. First, it ensure that the
+dymanic library contained in the package we are creating via
+\texttt{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.
 
-Other CRAN packages connect to \pkg{Rcpp}, packages \pkg{highlight}
-\citep{CRAN:highlight} and \pkg{minqa} \citep{CRAN:minqa} both follow
-precisely the guidelines of this document, while other packages follow
-older (but still supported and appropriate) instructions. The full list
-of packages using \pkg{Rcpp} can be found at the
+\subsection{Help files}
+
+Also created is a directory \texttt{man} containing two help files. One is
+for the package itself, the other for the (single) \proglang{R} function
+being provided and exported.
+
+The \textsl{Writing R Extensions} manual~\citep{R:exts} provides the complete
+documentation on how to create suitable content for help files.
+
+\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}
+package is provided as a template for employing \pkg{Rcpp} in packages.
+
+Other CRAN packages using the \pkg{Rcpp} package are \pkg{highlight}
+\citep{CRAN:highlight} and \pkg{minqa} \citep{CRAN:minqa} both of which
+follow precisely the guidelines of this document. 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 be found at the
 \href{http://CRAN.R-project.org/package=Rcpp}{CRAN page} of \pkg{Rcpp}.
 
 \section{Other compilers}

