[Rcpp-commits] r1392 - in pkg/Rcpp: . inst inst/doc inst/doc/Rcpp-package man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Jun 1 14:13:31 CEST 2010
Author: romain
Date: 2010-06-01 14:13:31 +0200 (Tue, 01 Jun 2010)
New Revision: 1392
Added:
pkg/Rcpp/inst/doc/Rcpp-package.Rnw
pkg/Rcpp/inst/doc/Rcpp-package/
pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package-fake.Rnw
pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
Modified:
pkg/Rcpp/NEWS
pkg/Rcpp/inst/ChangeLog
pkg/Rcpp/inst/doc/Makefile
pkg/Rcpp/man/Rcpp.package.skeleton.Rd
Log:
mini vignette for how to make a package that uses Rcpp (extension of the documentation of Rcpp.package.skeleton
Modified: pkg/Rcpp/NEWS
===================================================================
--- pkg/Rcpp/NEWS 2010-06-01 10:28:09 UTC (rev 1391)
+++ pkg/Rcpp/NEWS 2010-06-01 12:13:31 UTC (rev 1392)
@@ -10,6 +10,9 @@
The Rcpp-modules vignette documents the feature
+ o The 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-01 10:28:09 UTC (rev 1391)
+++ pkg/Rcpp/inst/ChangeLog 2010-06-01 12:13:31 UTC (rev 1392)
@@ -1,5 +1,9 @@
2010-06-01 Romain Francois <romain at r-enthusiasts.com>
+ * inst/doc/Rcpp-package*: new mini vignette "Rcpp-package" to improve the
+ documentation of Rcpp.package.skeleton and details the steps involved in
+ making a package that uses Rcpp
+
* inst/doc/Rcpp-modules/Rcpp-modules.Rnw: document how to use modules
in other packages (namespace, etc ...)
Modified: pkg/Rcpp/inst/doc/Makefile
===================================================================
--- pkg/Rcpp/inst/doc/Makefile 2010-06-01 10:28:09 UTC (rev 1391)
+++ pkg/Rcpp/inst/doc/Makefile 2010-06-01 12:13:31 UTC (rev 1392)
@@ -1,5 +1,5 @@
-all: clean index.html Rcpp-unitTests.pdf Rcpp-introduction.pdf Rcpp-modules.pdf
+all: clean index.html Rcpp-unitTests.pdf Rcpp-introduction.pdf Rcpp-modules.pdf Rcpp-package.pdf
clean:
touch Rcpp-unitTests.pdf
@@ -46,3 +46,21 @@
rm -fr Rcpp-modules.log
rm Rcpp-modules.Rnw
cp Rcpp-modules/Rcpp-modules-fake.Rnw Rcpp-modules.Rnw
+
+Rcpp-package.pdf : Rcpp-package/Rcpp-package.Rnw
+ rm Rcpp-package.Rnw
+ cp -f Rcpp-package/Rcpp-package.Rnw .
+ Rscript -e "require(highlight); driver <- HighlightWeaveLatex(boxes = TRUE, bg = 'white' ); Sweave( 'Rcpp-package.Rnw', driver = driver ); "
+ Rscript -e "tools::texi2dvi( 'Rcpp-package.tex', pdf = TRUE, clean = FALSE )"
+ bibtex Rcpp-package
+ Rscript -e "tools::texi2dvi( 'Rcpp-package.tex', pdf = TRUE, clean = TRUE )"
+ rm -fr Rcpp-package.tex
+ rm -fr Rcpp-package.bbl
+ rm -fr Rcpp-package.blg
+ rm -fr Rcpp-package.aux
+ rm -fr Rcpp-package.out
+ rm -fr Rcpp-package.log
+ rm Rcpp-package.Rnw
+ cp Rcpp-package/Rcpp-package-fake.Rnw Rcpp-package.Rnw
+
+
Added: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package-fake.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package-fake.Rnw (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package-fake.Rnw 2010-06-01 12:13:31 UTC (rev 1392)
@@ -0,0 +1,4 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-package}
+\begin{document}
+\end{document}
Added: pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-package/Rcpp-package.Rnw 2010-06-01 12:13:31 UTC (rev 1392)
@@ -0,0 +1,166 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-package}
+\usepackage{vmargin}
+\usepackage{color}
+\usepackage{alltt}
+\usepackage[authoryear,round,longnamesfirst]{natbib}
+
+\usepackage[colorlinks]{hyperref}
+\setmargrb{0.75in}{0.75in}{0.75in}{0.75in}
+\newcommand{\proglang}[1]{\textsf{#1}}
+\newcommand{\pkg}[1]{{\fontseries{b}\selectfont #1}}
+
+\author{Dirk Eddelbuettel \and Romain Fran\c{c}ois}
+\title{Writing a package that uses \pkg{Rcpp} }
+
+<<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 )
+}
+# this will be integrated to package highlight later
+ex_highlight <- function( file, external.highlight = TRUE, verbatim = FALSE ){
+ if( verbatim ){
+ writeLines( "\\begin{verbatim}" )
+ writeLines( readLines( file ) )
+ writeLines( "\\end{verbatim}" )
+ } else {
+ tf <- tempfile()
+ if( external.highlight ){
+ cmd <- sprintf( 'highlight --input="%s" --output="%s" -L --pretty-symbols', file, tf )
+ tryCatch( {
+ system( cmd )
+ tex <- readLines( tf )
+ keep <- seq( which( tex == "\\noindent" ), which( tex == "\\normalfont" ) )
+ tex <- c(
+ "\\vspace{1em}\\noindent\\fbox{\\begin{minipage}{0.9\\textwidth}" ,
+ tex[ keep ],
+ "\\end{minipage}}\\vspace{1em}" )
+ writeLines( tex )
+ })
+ } else {
+ r = renderer_latex( minipage = TRUE, doc = FALSE )
+ tex <- highlight( file, renderer = r , output = NULL )
+ writeLines( tex )
+ }
+ }
+ invisible(NULL)
+}
+@
+
+\begin{document}
+\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
+ this document.
+}
+
+\section{Rcpp.package.skeleton}
+
+\pkg{Rcpp} includes a function \Sexpr{link("Rcpp.package.skeleton")}, modelled
+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 )
+@
+
+\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
+\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 )
+@
+
+\subsection{C++ code}
+
+The \proglang{C++} function is declared in the \texttt{rcpp\_hello\_world.h}
+header file:
+
+<<echo=FALSE,results=tex>>=
+ex_highlight( file.path( gendir, "mypackage", "src", "rcpp_hello_world.h" ) )
+@
+
+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}
+
+<<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.
+
+\subsection{DESCRIPTION}
+
+The skeleton generates an appropriate \texttt{DESCRIPTION} file, using
+\texttt{Depends} and \texttt{LinkingTo} :
+
+<<echo=FALSE,results=tex>>=
+ex_highlight( file.path( gendir, "mypackage", "DESCRIPTION" ), verbatim = TRUE )
+@
+
+\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.
+
+<<echo=FALSE,results=tex>>=
+local({
+ tf <- sprintf( "%s.make", tempfile() )
+ file.copy( file.path( gendir, "mypackage", "src", "Makevars" ), tf )
+ ex_highlight( tf )
+ unlink( tf )
+})
+@
+
+The \texttt{Makevars.win} is the equivalent, targetting windows.
+
+<<echo=FALSE,results=tex>>=
+local({
+ tf <- sprintf( "%s.make", tempfile() )
+ file.copy( file.path( gendir, "mypackage", "src", "Makevars.win" ), tf )
+ ex_highlight( tf )
+ unlink( tf )
+})
+@
+
+
+\section{References}
+
+\bibliographystyle{abbrvnat}
+\bibliography{Rcpp-modules}
+
+\end{document}
+
Added: pkg/Rcpp/inst/doc/Rcpp-package.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-package.Rnw (rev 0)
+++ pkg/Rcpp/inst/doc/Rcpp-package.Rnw 2010-06-01 12:13:31 UTC (rev 1392)
@@ -0,0 +1,4 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-package}
+\begin{document}
+\end{document}
Modified: pkg/Rcpp/man/Rcpp.package.skeleton.Rd
===================================================================
--- pkg/Rcpp/man/Rcpp.package.skeleton.Rd 2010-06-01 10:28:09 UTC (rev 1391)
+++ pkg/Rcpp/man/Rcpp.package.skeleton.Rd 2010-06-01 12:13:31 UTC (rev 1392)
@@ -47,6 +47,9 @@
defined in this files makes use of the C++ function \samp{rcpp_hello_world}
defined in the C++ file. These files are given as an example and should
eventually by removed from the generated package.
+
+ If the \code{module} argument is \code{TRUE}, a sample Rcpp module will
+ be generated as well.
}
\value{
Nothing, used for its side effects
@@ -69,6 +72,12 @@
# package with a module
Rcpp.package.skeleton( "testmod", module = TRUE )
+# the Rcpp-package vignette
+vignette( "Rcpp-package" )
+
+# the Rcpp-modules vignette for information about modules
+vignette( "Rcpp-modules" )
+
}
}
\keyword{ programming }
More information about the Rcpp-commits
mailing list