[Rcpp-devel] Fwd: Re: devtools load_all() and modules

[Dirk Eddelbuettel]

Hi Glenn,

On 21 March 2012 at 10:56, Glenn Lawyer wrote:
| Dear Dirk,
| 
| I have now written a patch which incorporates your answer to Hadley in the
| Rcpp-package manual. I am attaching the complete *Rnw file. The diff is below.

I wonder if that should go to the Rcpp-FAQ instead of Rcpp-package?
 
| Please let me know your preferred channel for me to submit future patch
| suggestions.

Posting here is perfect. No need to post the full file, and 'diff -u' output
is usually best for patches.
 
| Kind regards,
| 
| +glenn
| 
| ########## begin diff output ##################
| 
| 233,244d232
| <
| < \subsubsection{\proglang{C++} development workflow}
| < \proglang{R}'s package framework elegantly supports rapid prototyping and
| experimental code development. One suggested workflow tests changes to \
| proglange{C++} code via
| < <<echo=FALSE>>=
| <  $ R CMD INSTALL mypkg && r -lmypkg -e 'someFunctionToTickle(3.14)'
| < @
| < 
| < The second command calls 'r' (littler), not 'R'. Littler is an alternative
| front end to GNU R for '#!' (hashbang) scripting. It has fast start-up times
| and gives a guaranteed clean slate. The -l option calls 'library(mypkg)' before
| executing the \proglang{R} expression. Littler is available via most Linux

Is it really?  I do know about Debian and Ubuntu (and their derivatives) only.

| distribution's package management systems. The project homepage is \href{http:/
| /code.google.com/p/littler/.}

Or is it http://dirk.eddelbuettel.com/code/littler/ ?

Need to talk about Rscript too, of course.

Good start though.  Should add this somewhere...

Dirk

| < Alternately, rapid prototyping can be conducted  using the inline package and
| \Sexpr{cxxfunction}.
| <
| <
| 
| ########## end diff output ##################
| 
| 
| 
| -------- Original Message --------
| Subject: Re: [Rcpp-devel] devtools load_all() and modules
|    Date: Tue, 20 Mar 2012 12:38:37 -0500
|    From: Dirk Eddelbuettel <edd at debian.org>
|      To: Hadley Wickham <hadley at rice.edu>
|      CC: rcpp-devel at r-forge.wu-wien.ac.at
| 
| 
| 
| On 20 March 2012 at 12:22, Hadley Wickham wrote:
| | > For usage beyond what we document and test, you're on your own.  If you want
| | > to explore usage with devtools and other means, go for it.
| | >
| | > But I will be unlikely to have time to work this out for you, unfortunately.
| |
| | Let me flip this around on you - when you're developing a package that
| | uses Rcpp, could you outline your workflow?  After modifying your R
| | and C++ code, what sequence of steps do you take so that you can try
| | out the code in an R session?  It would be really useful to hear what
| | workflow that you (and others) find most helpful.
| 
| Sure, very valid question.  I tend to do two things:
| 
|  a) at times experiment/try/play with the inline package and cxxfunction
| 
|  b) much more often, work with a package where, for force of habit, my
|     typical workflow often is
| 
|         $ R CMD INSTALL mypkg && r -lmypkg -e 'someFunctionToTickle(3.14)'
| 
|     which does a 'library(mypkg)' for me (which is how r resolves the -l
|     arguments) and then executes the R expression
| 
| as I never got really happy with any of the unloading attempts. Littler's r
| starts very quickly and gives me a guaranteed clean slate, so I tend to work
| from there.
| 
| Dirk
| 
| --
| "Outside of a dog, a book is a man's best friend. Inside of a dog, it is too
| dark to read." -- Groucho Marx
| _______________________________________________
| Rcpp-devel mailing list
| Rcpp-devel at lists.r-forge.r-project.org
| https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel
| 
| 
| ----------------------------------------------------------------------
| \documentclass[10pt]{article}
| %\VignetteIndexEntry{Rcpp-package}
| \usepackage{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}}
| 
| %% defined as a stop-gap measure til interaction with highlight is sorted out
| \newcommand{\hlboxlessthan}{   \hlnormalsizeboxlessthan}
| \newcommand{\hlboxgreaterthan}{\hlnormalsizeboxgreaterthan}
| \newcommand{\hlboxopenbrace}{  \hlnormalsizeboxopenbrace}
| \newcommand{\hlboxclosebrace}{ \hlnormalsizeboxclosebrace}
| \newcommand{\hlboxbacktick}{   \hlnormalsizeboxbacktick}
| \newcommand{\hlboxunderscore}{ \hlnormalsizeboxunderscore}
| 
| <<echo=FALSE,print=FALSE>>=
| prettyVersion <- packageDescription("Rcpp")$Version
| prettyDate <- format(Sys.Date(), "%B %e, %Y")
| @
| 
| \author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
| \title{Writing a package that uses \pkg{Rcpp} }
| \date{\pkg{Rcpp} version \Sexpr{prettyVersion} as of \Sexpr{prettyDate}}
| 
| <<echo=FALSE>>=
| require( Rcpp )
| 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 This document provides a short overview of how to use
|   \pkg{Rcpp}~\citep{CRAN:Rcpp,JSS:Rcpp} when writing an \proglang{R} package.  It
|   shows how usage of the function \Sexpr{link("Rcpp.package.skeleton")}
|   which creates 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:Extensions} which is the authoritative source on how to extend
|   \proglang{R} in general.
| }
| 
| \section{Introduction}
| 
| \pkg{Rcpp}~\citep{CRAN:Rcpp,JSS: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}.
| 
| It should be noted that \proglang{R} has only limited support for
| \proglang{C(++)}-level dependencies between packages~\citep{R:Extensions}. 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.
| 
| We strongly encourage the reader to become familiar with the material in the
| \textsl{Writing R Extensions} manual~\citep{R:Extensions}, as well as with other
| documents on \proglang{R} package creation such as \cite{Leisch:2008:Tutorial}. 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()
| dir.create( gendir )
| setwd( gendir )
| Rcpp.package.skeleton( "mypackage" )
| dir.create( tlib <- tempfile() )
| system( sprintf( 'R CMD INSTALL --library="%s" mypackage ', tlib ) )
| require( "mypackage", lib.loc = tlib )
| @
| 
| % <<>>=
| % Rcpp.package.skeleton( "mypackage" )
| % writeLines( system( "tree" , intern = TRUE ) )
| % @
| \begin{Hchunk}
| \begin{Hinput}
| \ttfamily\noindent
| \hlprompt{\usebox{\hlboxgreaterthan}{\ }}\hlfunctioncall{Rcpp.package.skeleton}\hlkeyword{(}{\ }\hlstring{"mypackage"}{\ }\hlkeyword{)}\mbox{}
| \normalfont
| 
| \end{Hinput}
| 
| \begin{Hinput}
| \ttfamily\noindent
| \hlprompt{\usebox{\hlboxgreaterthan}{\ }}\hlfunctioncall{writeLines}\hlkeyword{(}{\ }\hlfunctioncall{system}\hlkeyword{(}{\ }\hlstring{"tree"}\hlkeyword{,}{\ }\hlargument{intern}{\ }\hlargument{=}{\ }\hlnumber{TRUE}{\ }\hlkeyword{)}{\ }\hlkeyword{)}\mbox{}
| \normalfont
| \end{Hinput}
| 
| \begin{Houtput}
| \ttfamily\noindent
| .\hspace*{\fill}\\
| \hlstd{}\usebox{\hlboxbacktick}--{\ }mypackage\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|--{\ }DESCRIPTION\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|--{\ }NAMESPACE\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|--{\ }R\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.R\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|--{\ }Read-and-delete-me\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|--{\ }man\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }|--{\ }mypackage-package.Rd\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }|{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.Rd\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }src\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }Makevars\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }Makevars.win\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }|--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.cpp\hspace*{\fill}\\
| \hlstd{}{\ }{\ }{\ }{\ }{\ }{\ }{\ }{\ }\usebox{\hlboxbacktick}--{\ }rcpp\usebox{\hlboxunderscore}hello\usebox{\hlboxunderscore}world.h\hspace*{\fill}\\
| \hlstd{}\hspace*{\fill}\\
| \hlstd{}4{\ }directories,{\ }10{\ }files\hspace*{\fill}\\
| \hlstd{}\mbox{}
| \normalfont
| \end{Houtput}
| \end{Hchunk}
| 
| Using \Sexpr{link("Rcpp.package.skeleton")} is by far the simplest approach
| as it fulfills two roles. It creates the complete set of files needed for a
| package, and it also includes the different components needed for using
| \pkg{Rcpp} that we discuss in the following sections.
| 
| \subsection{\proglang{R} code}
| 
| 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 \texttt{mypackage}.
| 
| <<echo=FALSE,results=tex>>=
| highlight( 
|     file.path( gendir, "mypackage", "R", "rcpp_hello_world.R" ), 
|     renderer = renderer_latex( doc = FALSE )
|     )
| @
| 
| \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.
| 
| Note 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{\proglang{C++} code}
| 
| The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
| header file:
| 
| <<echo=FALSE,results=tex>>=
| external_highlight( 
|     file.path( gendir, "mypackage", "src", "rcpp_hello_world.h" ),
|     type = "LATEX", 
|     doc = FALSE
|     )
| @
| 
| 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.cpp} file
| 
| <<echo=FALSE,results=tex>>=
| external_highlight( 
|     file.path( gendir, "mypackage", "src", "rcpp_hello_world.cpp" ), 
|     type = "LATEX", 
|     doc = FALSE
| )
| @
| 
| The function creates an \proglang{R} list that contains a
| \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:
| 
| <<>>=
| rcpp_hello_world( )
| @
| 
| 
| \subsubsection{\proglang{C++} development workflow}
| \proglang{R}'s package framework elegantly supports rapid prototyping and experimental code development. One suggested workflow tests changes to \proglange{C++} code via
| <<echo=FALSE>>=
|  $ R CMD INSTALL mypkg && r -lmypkg -e 'someFunctionToTickle(3.14)'
| @
|  
| The second command calls 'r' (littler), not 'R'. Littler is an alternative front end to GNU R for '#!' (hashbang) scripting. It has fast start-up times and gives a guaranteed clean slate. The -l option calls 'library(mypkg)' before executing the \proglang{R} expression. Littler is available via most Linux distribution's package management systems. The project homepage is \href{http://code.google.com/p/littler/.}
| 
| Alternately, rapid prototyping can be conducted  using the inline package and \Sexpr{cxxfunction}.
| 
| 
| \subsection{\texttt{DESCRIPTION}}
| 
| The skeleton generates an appropriate \texttt{DESCRIPTION} file, using
| both \texttt{Depends:} and \texttt{LinkingTo} for \pkg{Rcpp}:
| 
| <<echo=FALSE,results=tex>>=
| local({
| 	tf <- sprintf( "%s.make", tempfile() )
| 	file.copy( file.path( gendir, "mypackage", "DESCRIPTION" ), tf )
| 	external_highlight( tf, type = "LATEX", doc = FALSE )
| 	unlink( tf )
| })
| @
| 
| \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 \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}.
| 
| \subsection{\texttt{Makevars} and \texttt{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
| unexported function \texttt{Rcpp:::LdFlags()} to ease the process:
| 
| <<echo=FALSE,results=tex>>=
| local({
| 	tf <- sprintf( "%s.make", tempfile() )
| 	file.copy( file.path( gendir, "mypackage", "src", "Makevars" ), tf )
| 	external_highlight( tf, type = "LATEX", doc = FALSE )
| 	unlink( tf )
| })
| @
| 
| The \texttt{Makevars.win} is the equivalent, targeting windows.
| 
| <<echo=FALSE,results=tex>>=
| local({
| 	tf <- sprintf( "%s.make", tempfile() )
| 	file.copy( file.path( gendir, "mypackage", "src", "Makevars.win" ), tf )
| 	external_highlight( tf, type = "LATEX", doc = FALSE )
| 	unlink( tf )
| })
| @
| 
| \subsection{\texttt{NAMESPACE}}
| 
| 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 )
| 	external_highlight( tf, type = "LATEX", doc = FALSE )
| 	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
| for the package itself, the other for the (single) \proglang{R} function
| being provided and exported.
| 
| The \textsl{Writing R Extensions} manual~\citep{R:Extensions} provides the complete
| documentation on how to create suitable content for help files.
| 
| \subsubsection{\texttt{mypackage-package.Rd}}
| 
| The help file \texttt{mypackage-package.Rd} can be used to describe
| the new package.
| 
| <<echo=FALSE,results=tex>>=
| local({
| 	tf <- sprintf( "%s.make", tempfile() )
| 	file.copy( file.path( gendir, "mypackage", "man", "mypackage-package.Rd" ), tf )
| 	external_highlight( tf, type = "LATEX", doc = FALSE )
| 	unlink( tf )
| })
| @
| 
| 
| \subsubsection{\texttt{rcpp\_hello\_world.Rd}}
| 
| The help file \texttt{rcpp\_hello\_world.Rd} serves as documentation for the
| example \proglang{R} function.
| 
| <<echo=FALSE,results=tex>>=
| local({
| 	tf <- sprintf( "%s.make", tempfile() )
| 	file.copy( file.path( gendir, "mypackage", "man", "rcpp_hello_world.Rd" ), tf )
| 	external_highlight( tf, type = "LATEX", doc = FALSE )
| 	unlink( tf )
| })
| @
| 
| 
| \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{RcppArmadillo}
| \citep{CRAN:RcppArmadillo}, \pkg{highlight} \citep{CRAN:highlight},
| and \pkg{minqa} \citep{CRAN:minqa} all 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}
| 
| Less experienced \proglang{R} users on the Windows platform frequently ask
| about using \pkg{Rcpp} with the Visual Studio toolchain.  That is simply not
| possible as \proglang{R} is built with the \pkg{gcc} compiler. Different
| compilers have different linking conventions. These conventions are
| particularly hairy when it comes to using \proglang{C++}.  In short, it is
| not possible to simply drop sources (or header files) from \pkg{Rcpp} into a
| \proglang{C++} project built with Visual Studio, and this note makes no
| attempt at claiming otherwise.
| 
| \pkg{Rcpp} is fully usable on Windows provided the standard Windows
| toolchain for \proglang{R} is used. See the \textsl{Writing R Extensions}
| manual~\citep{R:Extensions} for details.
| 
| \section{Summary}
| 
| This document described how to use the \pkg{Rcpp} package for \proglang{R}
| and \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{plainnat}
| \bibliography{Rcpp}
| 
| \end{document}
| 

-- 
"Outside of a dog, a book is a man's best friend. Inside of a dog, it is too
dark to read." -- Groucho Marx