[Rcpp-commits] r1440 - in pkg/Rcpp: . inst inst/doc inst/doc/Rcpp-package
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Jun 5 22:51:36 CEST 2010
Author: edd
Date: 2010-06-05 22:51:35 +0200 (Sat, 05 Jun 2010)
New Revision: 1440
Modified:
pkg/Rcpp/NEWS
pkg/Rcpp/inst/ChangeLog
pkg/Rcpp/inst/doc/Rcpp-modules.bib
pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
Log:
a bit more spit and polish on the Rcpp-package vignette
Modified: pkg/Rcpp/NEWS
===================================================================
--- pkg/Rcpp/NEWS 2010-06-05 19:32:12 UTC (rev 1439)
+++ pkg/Rcpp/NEWS 2010-06-05 20:51:35 UTC (rev 1440)
@@ -1,17 +1,19 @@
0.8.1 (under development)
- o This release add Rcpp modules. An Rcpp module is a collection of
- internal (c++) functions and classes that are exposed to R. Inspired
- from Boost.Python
+ o This release adds Rcpp modules. An Rcpp module is a collection of
+ internal (C++) functions and classes that are exposed to R. This
+ functionality has been inspired by Boost.Python.
Modules are created internally using the RCPP_MODULE macro and
retrieved in the R side with the Module function. This is a preview
release of the module functionality, which will keep improving until
- the Rcpp 0.9.0 release. The vignette "Rcpp-modules" documents the current
- feature set of modules.
+ the Rcpp 0.9.0 release.
+
+ The new vignette "Rcpp-modules" documents the current feature set of
+ Rcpp modules.
- o The vignette "Rcpp-package" details the steps involved in making a
- package that uses Rcpp.
+ o The new vignette "Rcpp-package" details the steps involved in making a
+ package that uses Rcpp.
o Rcpp.package.skeleton has been improved to generate a package using
an Rcpp module, controlled by the "module" argument
Modified: pkg/Rcpp/inst/ChangeLog
===================================================================
--- pkg/Rcpp/inst/ChangeLog 2010-06-05 19:32:12 UTC (rev 1439)
+++ pkg/Rcpp/inst/ChangeLog 2010-06-05 20:51:35 UTC (rev 1440)
@@ -1,3 +1,7 @@
+2010-06-05 Dirk Eddelbuettel <edd at debian.org>
+
+ * inst/doc/Rcpp-package*: Extended mini vignette "Rcpp-package"
+
2010-06-04 Romain Francois <romain at r-enthusiasts.com>
* inst/include/Rcpp/Module.h:
Modified: pkg/Rcpp/inst/doc/Rcpp-modules.bib
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-modules.bib 2010-06-05 19:32:12 UTC (rev 1439)
+++ pkg/Rcpp/inst/doc/Rcpp-modules.bib 2010-06-05 20:51:35 UTC (rev 1440)
@@ -26,7 +26,7 @@
author = {Dirk Eddelbuettel and Romain Fran\c{c}ois},
year = {2010},
note = {R package version 0.8.1},
- url = {http://CRAN.R-project.org/package=Rcpp}
+ url = {http://CRAN.R-Project.org/package=Rcpp}
}
@Manual{CRAN:RcppExamples,
@@ -34,7 +34,7 @@
author = {Dirk Eddelbuettel and Romain Fran\c{c}ois},
year = {2010},
note = {R package version 0.1.1},
- url = {http://CRAN.R-project.org/package=RcppExamples},
+ url = {http://CRAN.R-Project.org/package=RcppExamples},
}
@Manual{CRAN:highlight,
@@ -46,11 +46,21 @@
}
@Manual{CRAN:minqa,
- title = {minqa: Derivative-free optimization algorithms by quadratic
-approximation},
+ title = {minqa: Derivative-free optimization algorithms by quadratic approximation},
author = {Douglas Bates and Katharine M. Mullen and John C. Nash and Ravi Varadhan},
year = {2010},
note = {R package version 1.1.5},
- url = {http://CRAN.R-project.org/package=minqa},
+ url = {http://CRAN.R-Project.org/package=minqa},
}
+ at InProceedings{Leisch:2008,
+ author = {Friedrich Leisch},
+ title = {Tutorial on {C}reating {R} {P}ackages},
+ booktitle = {COMPSTAT 2008 -- Proceedings in Computational Statistics},
+ year = 2008,
+ editor = {Paula Brito},
+ address = {Heidelberg, Germany},
+ publisher = {Physica Verlag},
+ url = {http://CRAN.R-Project.org/doc/contrib/Leisch-CreatingPackages.pdf}
+}
+
Modified: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2010-06-05 19:32:12 UTC (rev 1439)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2010-06-05 20:51:35 UTC (rev 1440)
@@ -76,39 +76,57 @@
\abstract{
\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.
+ shows how usage of the function \Sexpr{link("Rcpp.package.skeleton")}
+ provides a complete and self-sufficient example package using
+ \pkg{Rcpp}. All components of the directory tree created by
+ \Sexpr{link("Rcpp.package.skeleton")} are discussed in detail. This
+ document thereby complements the \textsl{Writing R Extensions}
+ manual~\citep{R:exts} which is the authoritative source on how to extend
+ \proglang{R} in general.
}
\section{Introduction}
-\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}.
+\pkg{Rcpp}~\citep{CRAN:Rcpp} is an extension package for \proglang{R} which
+offers an easy-to-use yet featureful interface between \proglang{C++} and
+\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} 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.
+It should be noted that \proglang{R} has only 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. We illustrate this using a simple \proglang{C++} function
which will be called by an \proglang{R} function.
-\section{Rcpp.package.skeleton}
+We strongly encourage the reader to become familiar with the material in the
+\textsl{Writing R Extensions} manual~\citep{R:exts}, as well as with other
+documents on \proglang{R} package creation such as \cite{Leisch:2008}. Given
+a basic understanding of how to create \proglang{R} package, the present
+document aims to provide the additional information on how to use \pkg{Rcpp}
+in such add-on packages.
+\section{Using \texttt{Rcpp.package.skeleton}}
+
+\subsection{Overview}
+
\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}.
+\Sexpr{link("Rcpp.package.skeleton")} has a number of arguments documented on
+its help page (and similar to those of \Sexpr{link("package.skeleton")}). The
+main argument is the first one which provides the name of the package one
+aims to create by invoking the function. An illustration of a call using an
+argument \texttt{mypackage} is provided below.
+
<<echo=FALSE>>=
here <- getwd()
gendir <- tempfile()
@@ -169,7 +187,7 @@
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.
+package \texttt{mypackage}.
<<echo=FALSE,results=tex>>=
ex_highlight( file.path( gendir, "mypackage", "R", "rcpp_hello_world.R" ), FALSE )
@@ -180,6 +198,11 @@
\proglang{R} side and the \proglang{C++} side. \proglang{R} objects
(\texttt{SEXP}) can be conveniently manipulated using the \pkg{Rcpp} API.
+Noe 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.
+
\subsection{C++ code}
The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
@@ -190,21 +213,22 @@
@
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.rcpp} file
+needs to be included to use \pkg{Rcpp}. The function is then implemented in
+the \texttt{rcpp\_hello\_world.rcpp} file
<<echo=FALSE,results=tex>>=
ex_highlight( file.path( gendir, "mypackage", "src", "rcpp_hello_world.cpp" ) )
@
The function creates an \proglang{R} list that contains a
-\Sexpr{link("character")} vector and a \Sexpr{link("numeric")} using \pkg{Rcpp}
-classes.
+\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.
\subsection{DESCRIPTION}
The skeleton generates an appropriate \texttt{DESCRIPTION} file, using
-\texttt{Depends} and \texttt{LinkingTo} :
+both \texttt{Depends:} and \texttt{LinkingTo} for \pkg{Rcpp}:
<<echo=FALSE,results=tex>>=
ex_highlight( file.path( gendir, "mypackage", "DESCRIPTION" ), verbatim = TRUE )
@@ -257,14 +281,25 @@
\subsection{NAMESPACE}
-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.
+The \Sexpr{link("Rcpp.package.skeleton")} function also creates a file
+\texttt{NAMESPACE}.
+<<echo=FALSE,results=tex>>=
+local({
+ tf <- sprintf( "%s.make", tempfile() )
+ file.copy( file.path( gendir, "mypackage", "NAMESPACE" ), tf )
+ ex_highlight( tf )
+ unlink( tf )
+})
+@
+
+This file serves two purposes. First, it ensure that the dynamic library
+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.
+
\subsection{Help files}
Also created is a directory \texttt{man} containing two help files. One is
@@ -308,9 +343,10 @@
\section{Summary}
-This document described how to use \pkg{Rcpp} when writing an \proglang{R}
-extension package. The use of the \texttt{Rcpp.package.skeleton()} was shown
-in detail, and references to further examples were provided.
+This document described how to use the \pkg{Rcpp} package for \proglang{R}
+amd \proglang{C++} integration when writing an \proglang{R} extension
+package. The use of the \Sexpr{link("Rcpp.package.skeleton")} was shown in
+detail, and references to further examples were provided.
\bibliographystyle{abbrvnat}
\bibliography{Rcpp-modules}
More information about the Rcpp-commits
mailing list