[Rcpp-commits] r3944 - in pkg/Rcpp/inst/doc: . Rcpp-attributes

noreply at r-forge.r-project.org noreply at r-forge.r-project.org
Mon Nov 12 19:59:08 CET 2012


Author: jjallaire
Date: 2012-11-12 19:59:08 +0100 (Mon, 12 Nov 2012)
New Revision: 3944

Added:
   pkg/Rcpp/inst/doc/Rcpp-attributes.Rnw
   pkg/Rcpp/inst/doc/Rcpp-attributes/
   pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes-fake.Rnw
   pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
Modified:
   pkg/Rcpp/inst/doc/Makefile
   pkg/Rcpp/inst/doc/Rcpp.bib
Log:
Rcpp-attributes vignette

Modified: pkg/Rcpp/inst/doc/Makefile
===================================================================
--- pkg/Rcpp/inst/doc/Makefile	2012-11-12 13:11:03 UTC (rev 3943)
+++ pkg/Rcpp/inst/doc/Makefile	2012-11-12 18:59:08 UTC (rev 3944)
@@ -12,10 +12,10 @@
 	@echo The 'make all' target is now empty as eg R-Forge builds fall over
 	@echo So please use 'make pdfclean; make pdfall' to rebuild
 
-pdfall: rotateFiles index.html Rcpp-unitTests.pdf Rcpp-introduction.pdf Rcpp-modules.pdf Rcpp-package.pdf Rcpp-FAQ.pdf Rcpp-extending.pdf Rcpp-sugar.pdf Rcpp-quickref.pdf
+pdfall: rotateFiles index.html Rcpp-unitTests.pdf Rcpp-introduction.pdf Rcpp-modules.pdf Rcpp-package.pdf Rcpp-FAQ.pdf Rcpp-extending.pdf Rcpp-sugar.pdf Rcpp-attributes.pdf Rcpp-quickref.pdf
 
 pdfclean:
-	rm -f Rcpp-extending.pdf  Rcpp-FAQ.pdf  Rcpp-introduction.pdf  Rcpp-modules.pdf  Rcpp-package.pdf  Rcpp-quickref.pdf  Rcpp-sugar.pdf  Rcpp-unitTests.pdf
+	rm -f Rcpp-extending.pdf  Rcpp-FAQ.pdf  Rcpp-introduction.pdf  Rcpp-modules.pdf  Rcpp-package.pdf  Rcpp-quickref.pdf  Rcpp-sugar.pdf  Rcpp-attributes.pdf  Rcpp-unitTests.pdf
 
 rotateFiles:
 	cp -f Rcpp-extending/Rcpp-extending-fake.Rnw Rcpp-extending.Rnw
@@ -24,6 +24,7 @@
 	cp -f Rcpp-package/Rcpp-package-fake.Rnw Rcpp-package.Rnw
 	cp -f Rcpp-quickref/Rcpp-quickref-fake.Rnw Rcpp-quickref.Rnw
 	cp -f Rcpp-sugar/Rcpp-sugar-fake.Rnw Rcpp-sugar.Rnw
+	cp -f Rcpp-attributes/Rcpp-attributes-fake.Rnw Rcpp-attributes.Rnw
 
 clean:
 	rm -f index.html
@@ -138,6 +139,21 @@
 	rm Rcpp-sugar.Rnw
 	cp Rcpp-sugar/Rcpp-sugar-fake.Rnw Rcpp-sugar.Rnw
 
+Rcpp-attributes.pdf : Rcpp-attributes/Rcpp-attributes.Rnw
+	cp -f Rcpp-attributes/Rcpp-attributes.Rnw .
+	$(RSCRIPT) --vanilla -e "require(highlight); driver <- HighlightWeaveLatex(boxes = TRUE, bg = 'white' ); Sweave( 'Rcpp-attributes.Rnw', driver = driver ); "
+	$(RSCRIPT) --vanilla -e "tools::texi2dvi( 'Rcpp-attributes.tex', pdf = TRUE, clean = FALSE )"
+	bibtex Rcpp-attributes
+ifneq (,$(findstring edd,$(whoami)))
+	pdflatex Rcpp-attributes
+	pdflatex Rcpp-attributes
+else
+	$(RSCRIPT) -e "tools::texi2dvi( 'Rcpp-attributes.tex', pdf = TRUE, clean = TRUE )"
+endif
+	rm -fr Rcpp-attributes.tex Rcpp-attributes.bbl Rcpp-attributes.blg Rcpp-attributes.aux Rcpp-attributes.out Rcpp-attributes.log
+	rm Rcpp-attributes.Rnw
+	cp Rcpp-attributes/Rcpp-attributes-fake.Rnw Rcpp-attributes.Rnw
+
 Rcpp-quickref.pdf : Rcpp-quickref/Rcpp-quickref.Rnw
 	cp -f Rcpp-quickref/Rcpp-quickref.Rnw .
 	$(RSCRIPT) --vanilla -e "require(highlight); driver <- HighlightWeaveLatex(boxes = TRUE, bg = 'white' ); Sweave( 'Rcpp-quickref.Rnw', driver = driver ); "

Added: pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes-fake.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes-fake.Rnw	                        (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes-fake.Rnw	2012-11-12 18:59:08 UTC (rev 3944)
@@ -0,0 +1,4 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-attributes}
+\begin{document}
+\end{document}

Added: pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw	                        (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw	2012-11-12 18:59:08 UTC (rev 3944)
@@ -0,0 +1,375 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-attributes}
+\usepackage[USletter]{vmargin}
+\setmargrb{0.75in}{0.75in}{0.75in}{0.75in}
+
+\usepackage{color, alltt}
+\usepackage[authoryear,round,longnamesfirst]{natbib}
+\usepackage[colorlinks]{hyperref}
+\definecolor{link}{rgb}{0,0,0.3}	%% next few lines courtesy of RJournal.sty
+\hypersetup{
+    colorlinks,%
+    citecolor=link,%
+    filecolor=link,%
+    linkcolor=link,%
+    urlcolor=link
+}
+
+\newcommand{\proglang}[1]{\textsf{#1}}
+\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
+\newcommand{\ith}{\textsl{i}-\textsuperscript{th}}
+\newcommand{\code}[1]{\texttt{#1}}
+
+<<echo=FALSE,print=FALSE>>=
+prettyVersion <- packageDescription("Rcpp")$Version
+prettyDate <- format(Sys.Date(), "%B %e, %Y")
+@
+
+\author{J.J. Allaire \and Dirk Eddelbuettel \and Romain Fran\c{c}ois}
+\title{\pkg{Rcpp} Attributes}
+\date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
+
+<<echo=FALSE>>=
+link <- function( f, package, text = f, root = "http://finzi.psych.upenn.edu/R/library/" ){
+	h <- if( missing(package) ) {
+		as.character( help( f ) )
+	} else {
+		as.character( help( f, package = paste( package, sep = "" ) ) )
+	}
+	if( ! length(h) ){
+		sprintf( "\\\\textbf{%s}", f )
+	} else {
+		rx <- "^.*/([^/]*?)/help/(.*?)$"
+		package <- sub( rx, "\\1", h, perl = TRUE )
+		page <- sub( rx, "\\2", h, perl = TRUE )
+		sprintf( "\\\\href{%s%s/html/%s.html}{\\\\texttt{%s}}", root, package, page, text )
+	}
+}
+linkS4class <- function( cl, package, text = cl, root = "http://finzi.psych.upenn.edu/R/library/" ){
+	link( sprintf("%s-class", cl), package, text, root )
+}
+@
+
+\begin{document}
+\maketitle
+
+\abstract{
+  \noindent
+  \textsl{Rcpp attributes} provide a high-level syntax for declaring \proglang{C++} 
+  functions as callable from \proglang{R} and automatically generating the code 
+  required to invoke them. Attributes are intended to facilate both interactive use
+  of \proglang{C++} within \proglang{R} sessions as well as to support \proglang{R} 
+  package development. Attributes are built on top of \pkg{Rcpp} modules
+  and their implementation is based on previous work in the \pkg{inline} 
+  package \citep{CRAN:inline}. 
+}
+
+
+\section{Introduction}
+
+Rcpp attributes are a new feature of \pkg{Rcpp} version 0.10 \citep{CRAN:Rcpp,JSS:Rcpp}
+that provide infrastructure for seamless language bindings between \proglang{R} and 
+\proglang{C++}. The motivation for attributes is several-fold:
+
+\begin{enumerate}
+\item
+  Reducing the learning curve associated with using C++ and R together
+\item
+  Eliminating boilerplate conversion and marshaling code wherever
+  possible
+\item
+  Seamless use of C++ within interactive R sessions
+\item
+  Unified syntax for interactive work and package development
+\end{enumerate}
+
+The core concept is to add declarative attributes to \proglang{C++} source
+files that provide the context required to automatically generate \proglang{R} 
+bindings to \proglang{C++} functions. Attributes and their supporting 
+functions include:
+
+\begin{itemize}
+\item
+  \texttt{Rcpp::export} attribute to export a \proglang{C++} function 
+  to \proglang{R}
+\item
+  \texttt{sourceCpp} function to source exported functions from a file
+\item
+  \texttt{cppFunction} and \texttt{evalCpp} functions for inline
+  declarations and execution
+\item
+  \texttt{Rcpp::depends} attribute for specifying additional build
+  dependencies for \texttt{sourceCpp}
+\end{itemize}
+
+Attributes can also be used for package development via the
+\texttt{compileAttributes} function, which generates an \pkg{Rcpp} module for
+all exported functions within a package.
+
+Attributes derive their syntax from \proglang{C++11} style attributes
+\citep{Maurer+Wong:2008:AttributesInC++} and are included in source files using specially 
+formatted comments.
+
+\section{Sourcing C++ Functions}
+
+The \texttt{sourceCpp} function parses a \proglang{C++} file and looks for
+functions marked with the \texttt{Rcpp::export} attribute. A shared
+library is then built and its exported functions are made available as R
+functions in the specified environment. For example, this source file
+contains an implementation of convolve (note the \texttt{Rcpp::export}
+attribute in the comment above the function):
+
+<<lang=cpp>>=
+#include <Rcpp.h>
+using namespace Rcpp;
+
+// [[Rcpp::export]]
+NumericVector convolveCpp(NumericVector a, NumericVector b) {
+
+    int na = a.size(), nb = b.size();
+    int nab = na + nb - 1;
+    NumericVector xab(nab);
+
+    for (int i = 0; i < na; i++)
+        for (int j = 0; j < nb; j++)
+            xab[i + j] += a[i] * b[j];
+
+    return xab;
+}
+@
+
+The addition of the export attribute allows us to do this from the \proglang{R}
+prompt:
+
+<<eval=FALSE>>=
+sourceCpp("convolve.cpp")
+convolveCpp(x, y)
+@
+
+
+We can now write \proglang{C++} functions using standard \proglang{C++} types
+and then source them just like an \proglang{R} script using the \texttt{sourceCpp}
+function. Any types that can be marshaled with \texttt{as} and \texttt{wrap} 
+can be used in the signatures of exported functions (and since as and wrap are
+in turn extensible,  a wide variety of custom types can be supported).
+
+You can change the name of the exported function as it appears to \proglang{R} by
+adding a name parameter to \texttt{Rcpp::export}. For example the
+following will export \texttt{convolveCpp} as a hidden \proglang{R} function:
+
+<<lang=cpp>>=
+// [[Rcpp::export(".convolveCpp")]]
+NumericVector convolveCpp(NumericVector a, NumericVector b)
+@
+
+The \texttt{sourceCpp} function performs caching based on the last
+modified date of the source file so as long as the source file does not
+change the compilation will occur only once per R session.
+
+\section{Importing Dependencies}
+
+It's also possible to use the \texttt{Rcpp::depends} attribute to declare
+dependencies on other packages. For example:
+
+<<lang=cpp>>=
+// [[Rcpp::depends(RcppArmadillo)]]
+
+#include <RcppArmadillo.h>
+using namespace Rcpp
+
+// [[Rcpp::export]]
+List fastLm(NumericVector yr, NumericMatrix Xr) {
+
+    int n = Xr.nrow(), k = Xr.ncol();
+
+    arma::mat X(Xr.begin(), n, k, false); 
+    arma::colvec y(yr.begin(), yr.size(), false);
+
+    arma::colvec coef = arma::solve(X, y); 
+    arma::colvec resid = y - X*coef; 
+
+    double sig2 = arma::as_scalar(arma::trans(resid)*resid/(n-k));
+    arma::colvec stderrest = arma::sqrt(
+          sig2 * arma::diagvec( arma::inv(arma::trans(X)*X)) );
+
+    return List::create(Named("coefficients") = coef,
+                        Named("stderr")       = stderrest);
+}
+@
+
+The inclusion of the \texttt{Rcpp::depends} attribute causes \texttt{sourceCpp} 
+to configure the build environment to correctly compile and link against the
+\pkg{RcppArmadillo} package. Source files can declare more than one dependency 
+either by using multiple \texttt{Rcpp::depends} attributes or with syntax like this:
+
+<<lang=cpp>>=
+// [[Rcpp::depends(Matrix, RcppArmadillo)]]
+@
+
+Dependencies are discovered both by scanning for package include directories 
+and by invoking \pkg{inline} plugins if they are available for a package.
+
+\section{Using C++ Inline}
+
+Maintaining C++ code in it's own source file provides several benefits including
+the ability to use \proglang{C++} aware text-editing tools and straightforward 
+mapping of compilation errors to lines in the source file. However, it's also
+possible to do inline declaration and execution of C++ code. This is accomplished
+by either passing a code string to \texttt{sourceCpp} or using the shorter-form
+\texttt{cppFunction} or \texttt{evalCpp} functions. For example:
+
+<<eval=FALSE>>=
+cppFunction('
+    int fibonacci(const int x) {
+        if (x == 0) return(0);
+        if (x == 1) return(1);
+        return (fibonacci(x - 1)) + fibonacci(x - 2);
+    }
+')
+
+evalCpp('std::numeric_limits<double>::max()')
+@
+
+You can also specify a depends parameter to \texttt{cppFunction} or \texttt{evalCpp}:
+
+<<eval=FALSE>>=
+cppFunction(depends = 'RcppArmadillo', code = '...')
+@
+
+Note that using \texttt{sourceCpp}, \texttt{cppFunction}, and \texttt{evalCpp} 
+require that \proglang{C++} development tools be available to build the code. 
+If you want to distribute \pkg{Rcpp} code to users that don't have these tools 
+installed you can bundle your code into an R package. The next section describes
+how you can use \pkg{Rcpp} attributes for package development.
+
+\section{Package Development}
+
+\subsection{Exporting R Functions}
+
+\proglang{C++} source code that uses attributes to export R functions can also be
+included in an \proglang{R} package. In this case rather than calling \texttt{sourceCpp}
+on individual files you call a single utility function for the whole package. 
+The \texttt{compileAttributes} function scans the source files within a package
+for export attributes and generates code as required.
+
+For example, executing this from within the package working directory:
+
+<<eval=FALSE>>=
+compileAttributes()
+@
+
+Results in the generation of the following two source files:
+
+\begin{itemize}
+\item
+  \texttt{src/RcppExports.cpp} -- An \pkg{Rcpp} module that exports the functions
+\item
+  \texttt{R/RcppExports.R} -- The \proglang{R} code required to load the
+  \pkg{Rcpp} module
+\end{itemize}
+
+The generated code deals only with interface of functions rather than the 
+implementation, so \texttt{compileAttributes} needs to be run only when functions
+are added, removed, or have their signatures changed.
+
+\subsection{Providing a C++ Interface}
+
+You can use the \texttt{Rcpp::interfaces} attribute to expose the underlying 
+\proglang{C++} functions directly to users of your package. For example, the following 
+specifies that both R and \proglang{C++} interfaces should be generated:
+
+<<lang=cpp>>==
+// [[Rcpp::interfaces(r, cpp)]]
+@
+
+The \texttt{Rcpp::interfaces} attribute is specified on a per-source file basis. 
+If you request a \texttt{cpp} interface for a source file then \texttt{compileAttributes} 
+does the following:
+
+\begin{enumerate}
+\item
+  Bindings are generated into a header file located in the
+  \texttt{inst/include} directory of the package using the naming
+  convention \emph{PackageName.h}
+\item
+  The generated header file enables calling the exported \proglang{C++}functions 
+  without  any linking dependency on the package. This is based on using the 
+  \texttt{R\_RegisterCCallable} and \texttt{R\_GetCCallable} functions described 
+  in `\textsl{Writing R Extensions}' \citep{R:Extensions}.
+\item
+  The exported functions are defined within a \proglang{C++} namespace that matches
+  the name of the package.
+\end{enumerate}
+
+For example, an exported \proglang{C++} function \texttt{foo} could be called from
+package \texttt{MyPackage} as follows:
+
+<<lang=cpp>>==
+// [[Rcpp::depends(MyPackage)]]
+
+#include <MyPackage.h>
+
+void foo() {
+    MyPackage::bar();
+}
+@
+
+Note that the default behavior if an \texttt{Rcpp::interfaces} attribute
+is not included in a source file is to generate an R interface only.
+
+\subsection{Using Roxygen}
+
+The \pkg{roxygen2} package \citep{CRAN:roxygen2} provides a facility for 
+automatically generating \proglang{R} documentation files based on specially
+formatted comments in \proglang{R} source code.
+
+If you include roxygen comments in your \proglang{C++} source file with a
+\texttt{//'} prefix then \texttt{compileAttributes} will transpose them
+into R roxygen comments within \texttt{R/RcppExports.R}. For example the
+following code in a \proglang{C++} source file:
+
+<<lang=cpp>>=
+//' The length of a string (in characters).
+//'
+//' @param str input character vector
+//' @return characters in each element of the vector
+// [[Rcpp::export]]
+NumericVector strLength(CharacterVector str)
+@
+
+Results in the following code in the generated \proglang{R} source file:
+
+<<lang=r>>=
+#' The length of a string (in characters).
+#'
+#' @param str input character vector
+#' @return characters in each element of the vector
+strLength <- function(str)
+@
+
+\subsection{Packages and sourceCpp}
+
+One of the goals of \pkg{Rcpp} attributes is to simultaneously facilitate
+ad-hoc and interactive work with \proglang{C++} while also making it very easy to
+migrate that work into an \proglang{R} package. Two major benefits of moving code
+from a standalone \proglang{C++} source file to a package are:
+
+\begin{enumerate}
+\item
+  Users without \proglang{C++} development tools available can use your code.
+\item
+  Multiple source files and their dependencies are handled automatically
+  by the \proglang{R} package build system.
+\end{enumerate}
+
+Once you've migrated \proglang{C++} code into a package it's still possible use
+\texttt{sourceCpp} with it for iterative development. The main thing to keep in 
+mind is that the dependencies for source files within a package are derived from
+the \texttt{Depends} and \texttt{LinkingTo} fields in the package
+\texttt{DESCRIPTION} file rather than the \texttt{Rcpp::depends} attribute.
+
+\bibliographystyle{plainnat}
+\bibliography{Rcpp}
+
+\end{document}
+

Added: pkg/Rcpp/inst/doc/Rcpp-attributes.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-attributes.Rnw	                        (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-attributes.Rnw	2012-11-12 18:59:08 UTC (rev 3944)
@@ -0,0 +1,4 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-attributes}
+\begin{document}
+\end{document}

Modified: pkg/Rcpp/inst/doc/Rcpp.bib
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp.bib	2012-11-12 13:11:03 UTC (rev 3943)
+++ pkg/Rcpp/inst/doc/Rcpp.bib	2012-11-12 18:59:08 UTC (rev 3944)
@@ -209,6 +209,13 @@
   url =		 CRAN # "package=minqa"
 }
 
+ at Manual{CRAN:roxygen2,
+  title =	 {roxygen2: In-source documentation for R},
+  author =	 {Hadley Wickham and Peter Danenberg and Manuel Eugster},
+  year =	 2011,
+  note =	 {R package version 2.2.12},
+  url =		 CRAN # "package=roxygen2"
+}
 
 @Book{Gentleman:2009:RProgramming,
   author = 	 {Robert Gentleman},
@@ -458,6 +465,15 @@
   month =	 {May}
 }
 
+ at InProceedings{Maurer+Wong:2008:AttributesInC++,
+  author    = {Jens Maurer and Michael Wong},
+  title     = {Towards support for attributes in C++ (Revision 6)},
+  booktitle = {JTC1/SC22/WG21 - The C++ Standards Committee},
+  year      = {2008},
+  url       = {http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf}, 
+  note      = {{N2761=08-0271}}  
+}
+
 @InProceedings{Urbanek:2003:Rserve,
   author =	 {Simon Urbanek},
   title =	 {{Rserve}: A Fast Way to Provide {R} Functionality to



More information about the Rcpp-commits mailing list