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

[noreply at r-forge.r-project.org]

Author: romain
Date: 2010-06-05 08:36:38 +0200 (Sat, 05 Jun 2010)
New Revision: 1431

Modified:
   pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
Log:
adding some content

Modified: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw	2010-06-05 05:40:42 UTC (rev 1430)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw	2010-06-05 06:36:38 UTC (rev 1431)
@@ -80,6 +80,22 @@
   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. 
+
+\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. 
+
+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 
+package.
+
 \section{Rcpp.package.skeleton}
 
 \pkg{Rcpp} includes a function \Sexpr{link("Rcpp.package.skeleton")}, modelled
@@ -109,6 +125,11 @@
 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. 
+
 \subsection{C++ code}
 
 The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
@@ -119,8 +140,8 @@
 @
 
 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}
+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" )  )
@@ -139,10 +160,26 @@
 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")}. 
+
+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{SystemRequirements} declaration indicates that the package depends
+on \proglang{GNU make} which is needed when compiling the client package
+on platforms such as solaris. 
+
 \subsection{Makevars and Makevars.win}
 
-The \texttt{Makevars} file is used to link against the \pkg{Rcpp}
-user library, using the \texttt{PKG\_LIBS} variable.
+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 
+unexported function \texttt{Rcpp:::LdFlags()} to ease the process:
 
 <<echo=FALSE,results=tex>>=
 local({