[Rcpp-commits] r1432 - pkg/Rcpp/inst/doc/Rcpp-package
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sat Jun 5 13:42:57 CEST 2010
Author: edd
Date: 2010-06-05 13:42:57 +0200 (Sat, 05 Jun 2010)
New Revision: 1432
Modified:
pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
Log:
some editing
Modified: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2010-06-05 06:36:38 UTC (rev 1431)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2010-06-05 11:42:57 UTC (rev 1432)
@@ -74,61 +74,67 @@
\maketitle
\abstract{
- \noindent This document is a short overview of the process to follow to write
- an R package using \pkg{Rcpp}~\citep{CRAN:Rcpp}. This document only complements~\citep{R:exts}
- which we strongly encourage the reader to familiarize with before reading
+ \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.
}
\section{Introduction}
-\pkg{Rcpp}~\citep{CRAN:Rcpp} is more than a traditional R package because its
-key component is a \proglang{C++} library a client package must link against
-if it wants to make use of \pkg{Rcpp} features.
+\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
+provided by \pkg{Rcpp}.
-\proglang{R}~\citep{R:exts} only has limited support for \proglang{C(++)} level
-dependencies between packages. The \texttt{LinkingTo} declaration in the
+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 (\pkg{Rcpp} in this document), but support for
-linking against a library is missing and has to be dealt with manually.
+headers of the target package (here \pkg{Rcpp}), but support for
+linking against a library is missing and has to be dealt with manually.
This document follows the steps of the \Sexpr{link("Rcpp.package.skeleton")}
-function to illustrate the best way to make use of \pkg{Rcpp} in a client
+function to illustrate a recommended way of using \pkg{Rcpp} from a client
package.
\section{Rcpp.package.skeleton}
-\pkg{Rcpp} includes a function \Sexpr{link("Rcpp.package.skeleton")}, modelled
+\pkg{Rcpp} includes a function \Sexpr{link("Rcpp.package.skeleton")}, modeled
after \Sexpr{link("package.skeleton")}, that facilitates creation of a skeleton
package using \pkg{Rcpp}. This is by far the simplest way.
-<<echo=FALSE>>=
-here <- getwd()
-gendir <- tempfile()
-dir.create( gendir )
-setwd( gendir )
-<<>>=
-Rcpp.package.skeleton( "mypackage" )
-writeLines( system( "tree", intern = TRUE ) )
-<<echo=FALSE>>=
-setwd( here )
-@
+%<<echo=FALSE>>=
+%here <- getwd()
+%gendir <- tempfile()
+%dir.create( gendir )
+%setwd( gendir )
+%<<>>=
+%Rcpp.package.skeleton( "mypackage" )
+%writeLines( system( "tree -n", intern = TRUE ) )
+%<<echo=FALSE>>=
+%setwd( here )
+%@
+%% Can we do manual ascii art here, please ? I didn't even have tree(1)
+%% installed. You may be able to assume 'ls -lR' but tree is too much
+%% I fear
\subsection{R code}
The skeleton contains an \proglang{R} function \texttt{rcpp\_hello\_world}
-that simply uses the \Sexpr{link(".Call")} interface to invoke the
+that uses the \Sexpr{link(".Call")} interface to invoke the
\proglang{C++} function called \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 mainly use 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
-(\texttt{SEXP}) can be conveniently manipulated using the \pkg{Rcpp} API.
+\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
+(\texttt{SEXP}) can be conveniently manipulated using the \pkg{Rcpp} API.
\subsection{C++ code}
@@ -140,7 +146,7 @@
@
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
+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>>=
@@ -160,25 +166,25 @@
ex_highlight( file.path( gendir, "mypackage", "DESCRIPTION" ), verbatim = TRUE )
@
-\Sexpr{link("Rcpp.package.skeleton")} adds the three last lines to the
-\texttt{DESCRIPTION} file generated by \Sexpr{link("package.skeleton")}.
+\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 \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}.
+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
-on platforms such as solaris.
+on \proglang{GNU Make} which is needed when compiling the client package
+on platforms such as Solaris.
\subsection{Makevars and Makevars.win}
Unfortunately, the \texttt{LinkingTo} declaration in itself is not
enough to link to the user \proglang{C++} library of \pkg{Rcpp}. Until more
-explicit support for libraries is added to \proglang{R}, we need to manually
-add the \pkg{Rcpp} library to the \texttt{PKG\_LIBS} variable in the
-\texttt{Makevars} and \texttt{Makevars.win} files. \pkg{Rcpp} provides the
+explicit support for libraries is added to \proglang{R}, we need to manually
+add the \pkg{Rcpp} library to the \texttt{PKG\_LIBS} variable in the
+\texttt{Makevars} and \texttt{Makevars.win} files. \pkg{Rcpp} provides the
unexported function \texttt{Rcpp:::LdFlags()} to ease the process:
<<echo=FALSE,results=tex>>=
@@ -201,17 +207,22 @@
})
@
+The use of \verb|$(shell)| to execute a sub-command is a \proglang{GNU Make}
+extension to the standard \proglang{Make} language which we have found to be
+more reliable than using backticks.
+
\section{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}, through
-both the current API and the older API. \pkg{RcppExamples} may be used as a model.
+\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.
-Other CRAN packages connect to \pkg{Rcpp}, packages \pkg{highlight}
+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
+older (but still supported and appropriate) instructions. 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}.
More information about the Rcpp-commits
mailing list