[Rcpp-commits] r1856 - / linkingto
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Jul 13 16:15:16 CEST 2010
Author: romain
Date: 2010-07-13 16:15:15 +0200 (Tue, 13 Jul 2010)
New Revision: 1856
Added:
linkingto/
linkingto/Makefile
linkingto/Rcpp.bib
linkingto/linkingto-proposal.Rnw
Log:
first drafty pass at linkingto proposal
Added: linkingto/Makefile
===================================================================
--- linkingto/Makefile (rev 0)
+++ linkingto/Makefile 2010-07-13 14:15:15 UTC (rev 1856)
@@ -0,0 +1,33 @@
+
+## There is an old bug in texidvi that makes it not swallow the ~
+## marker used to denote whitespace. This is actually due to fixing
+## another bug they whereby you could not run texidvi on directory
+## names containing a tilde (as we happen to do for Debian builds of R
+## alpha/beta/rc releases). The 'tilde' bug will go away as it
+## reportedly has been squashed upstream but I am still bitten by it
+## on Ubuntu so for Dirk will insist on pdflatex and this variable helps
+whoami=$(shell whoami)
+
+all: clean linkingto-proposal.pdf
+
+clean:
+ touch linkingto-proposal.pdf
+ rm linkingto-proposal.pdf
+
+linkingto-proposal.pdf : linkingto-proposal.Rnw
+ Rscript -e "require(highlight); driver <- HighlightWeaveLatex(boxes = TRUE, bg = 'white' ); Sweave( 'linkingto-proposal.Rnw', driver = driver ); "
+ Rscript -e "tools::texi2dvi( 'linkingto-proposal.tex', pdf = TRUE, clean = FALSE )"
+ bibtex linkingto-proposal
+ifeq ($(whoami),edd)
+ pdflatex linkingto-proposal
+ pdflatex linkingto-proposal
+else
+ Rscript -e "tools::texi2dvi( 'linkingto-proposal.tex', pdf = TRUE, clean = TRUE )"
+endif
+ rm -fr linkingto-proposal.tex
+ rm -fr linkingto-proposal.bbl
+ rm -fr linkingto-proposal.blg
+ rm -fr linkingto-proposal.aux
+ rm -fr linkingto-proposal.out
+ rm -fr linkingto-proposal.log
+
Added: linkingto/Rcpp.bib
===================================================================
--- linkingto/Rcpp.bib (rev 0)
+++ linkingto/Rcpp.bib 2010-07-13 14:15:15 UTC (rev 1856)
@@ -0,0 +1,117 @@
+ at String{CRAN = "http://cran.r-project.org/" }
+ at String{manuals = CRAN # "doc/manuals/" }
+ at String{RCoreTeam = "{R Development Core Team}" }
+ at String{RFoundation = "R Foundation for Statistical Computing" }
+
+ at manual{Boost:Python,
+ author = { David Abrahams and Ralf W. Grosse-Kunstleve },
+ organization = "Boost Consulting",
+ title = "Building Hybrid Systems with Boost.Python",
+ year = 2003,
+ url = "http://www.boostpro.com/writing/bpl.pdf"
+}
+
+ at Manual{CRAN:Rcpp,
+ title = {Rcpp \proglang{R}/\proglang{C++} interface package},
+ author = {Dirk Eddelbuettel and Romain Fran\c{c}ois},
+ year = 2010,
+ note = {R package version 0.8.1},
+ url = {http://CRAN.R-Project.org/package=Rcpp}
+}
+
+ at Manual{CRAN:RcppArmadillo,
+ title = {Rcpp integration for Armadillo templated linear algebra library},
+ author = {Romain Fran\c{c}ois and Dirk Eddelbuettel and Doug Bates},
+ year = 2010,
+ note = {R package version 0.2.2},
+ url = {http://CRAN.R-Project.org/package=RcppArmadillo},
+}
+
+ at Manual{CRAN:RcppExamples,
+ title = {RcppExamples: Examples using Rcpp to interface \proglang{R} and
+ \proglang{C++}},
+ author = {Dirk Eddelbuettel and Romain Fran\c{c}ois},
+ year = 2010,
+ note = {R package version 0.1.1},
+ url = {http://CRAN.R-Project.org/package=RcppExamples},
+}
+
+ at Manual{CRAN:highlight,
+ title = {highlight: Syntax highlighter},
+ author = {Romain Fran\c{c}ois},
+ year = 2010,
+ note = {R package version 0.2-1},
+ url =
+ {http://romainfrancois.blog.free.fr/index.php?category/R-package/highlight},
+}
+
+ at Manual{CRAN:minqa,
+ title = {minqa: Derivative-free optimization algorithms by
+ quadratic approximation},
+ author = {Douglas Bates and Katharine M. Mullen and John
+ C. Nash and Ravi Varadhan},
+ year = 2010,
+ note = {R package version 1.1.5},
+ url = {http://CRAN.R-Project.org/package=minqa},
+}
+
+ at InProceedings{Leisch:2008,
+ author = {Friedrich Leisch},
+ title = {Tutorial on {C}reating \proglang{R} {P}ackages},
+ booktitle = {COMPSTAT 2008 -- Proceedings in Computational
+ Statistics},
+ year = 2008,
+ editor = {Paula Brito},
+ address = {Heidelberg, Germany},
+ publisher = {Physica Verlag},
+ url =
+ {http://CRAN.R-Project.org/doc/contrib/Leisch-CreatingPackages.pdf}
+}
+
+ at manual{R:exts,
+ author = RCoreTeam,
+ organization = RFoundation,
+ address = {Vienna, Austria},
+ year = 2010,
+ isbn = {3-900051-11-9},
+ title = "Writing R Extensions",
+ url = manuals # "R-exts.html"
+}
+
+ at Manual{CRAN:inline,
+ title = {inline: Inline \proglang{C}, \proglang{C++},
+ \proglang{Fortran} function calls from R},
+ author = {Oleg Sklyar and Duncan Murdoch and Mike Smith and
+ Dirk Eddelbuettel and Romain Fran\c{c}ois},
+ year = 2010,
+ note = {R package version 0.3.5},
+ url = {http://CRAN.R-Project.org/package=inline},
+}
+
+ at Manual{Armadillo,
+ title = {Armadillo: \proglang{C++} linear algebra library},
+ author = {Conrad Sanderson},
+ year = 2010,
+ note = {Library version 0.9.10. Sponsored by \href{http://nicta.com.au}{NICTA}.},
+ url = {http://arma.sourceforge.net}
+}
+
+ at Book{Abrahams+Gurtovoy:2004,
+ author = {David Abrahams and Aleksey Gurtovoy},
+ title = {\proglang{C++} {T}emplate {M}etaprogramming:
+ Concepts, Tools and Techniques from {B}oost and
+ Beyond},
+ publisher = {Addison-Wesley},
+ year = 2004,
+ address = {Boston}
+}
+
+
+ at Book{Vandevoorde+Josuttis:2003,
+ author = {David Vandevoorde and Nicolai M. Josuttis},
+ title = {\proglang{C++} {T}emplates: The Complete Guide},
+ publisher = {Addison-Wesley},
+ year = 2003,
+ address = {Boston}
+}
+
Added: linkingto/linkingto-proposal.Rnw
===================================================================
--- linkingto/linkingto-proposal.Rnw (rev 0)
+++ linkingto/linkingto-proposal.Rnw 2010-07-13 14:15:15 UTC (rev 1856)
@@ -0,0 +1,201 @@
+\documentclass[10pt]{article}
+%\VignetteIndexEntry{Rcpp-modules}
+\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}}
+
+\author{Douglas Bates, Dirk Eddelbuettel and Romain Fran\c{c}ois}
+\title{Proposal for extension of the LinkingTo feature}
+
+<<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 This document is a proposal for extending the role of the
+ \texttt{LinkingTo} directive of \proglang{R} package \texttt{DESCRIPTION}
+ files. Currently \texttt{LinkingTo} facilitates access of header files of
+ one package from another package, but linking to shared or static libraries
+ provided by other packages does not have dedicated support apart from
+ documentation notes in section 5.8 of \cite{R:exts}.
+}
+
+\section{Motivation}
+
+The ability to include compiled code in R packages is a great way to
+leverage performance of compiled languages such as \proglang{C++}
+while keeping the flexibility of \proglang{R}. Adding compiled code is
+straightforward --- and properly documented in \cite{R:exts} --- when
+this involves only one package.
+
+The \texttt{R\_RegisterCCallable} / \texttt{R\_GetCCallable} mechanism
+allows compiled code from one package to invoke a compiled function
+from another package by means of function pointers. The packages
+\texttt{Matrix}/\texttt{lme4} provide an example of the mechanism.
+The mechanism does not involve actual linking since essentially it
+is a way to pass function pointers from one package to another. This requires
+a lot of discipline from both packages and lacks of flexibility, one has to
+expose/retrieve each function. This quickly becomes unusable in C++ where
+actual linking would be preferable.
+
+\cite{R:exts} also includes material on how to link against a library
+included in another package, although the document seems to discourage
+users to do it, because of portability subtleties.
+
+\section{State of the art}
+
+\subsection{What does the current LinkingTo does}
+
+\texttt{LinkingTo} facilitates retrieving the header files of one package
+(the target package) and sets the appropriate compiler flags so that
+another package (the client package) can use the declarations therein.
+
+Assuming the source package \texttt{packA} distributes its headers
+in the \texttt{inst/include} directory, then having the following line
+in the client package \texttt{packB} :
+
+\begin{verbatim}
+LinkingTo: packA
+\end{verbatim}
+
+will add the appropriate \texttt{-I} flag when compiling source files
+of \texttt{packB}.
+
+\subsection{Compiling against target package library}
+
+Because \pkg{Rcpp} essentially consists of a \proglang{C++} library and R does not
+offer explicit support for cross package linking, \pkg{Rcpp} package has been
+using its own mechanism for client packages to link against its library.
+
+The mechanism used by \pkg{Rcpp} consists of :
+\begin{itemize}
+\item create a dynamic library \texttt{lib[/arch]/libRcpp.dylib} in addition
+to the shared object \texttt{libs[/arch]/Rcpp.so} that \proglang{R}
+automatically makes
+\item create a static library \texttt{lib[/arch]/libRcpp.a}
+\item provide the \proglang{R} function \texttt{Rcpp:::LdFlags} to generate the suitable
+flags for linking against the dynamic or static library.
+\end{itemize}
+
+A package that wishes to use the classes of \pkg{Rcpp} then has to :
+
+\begin{itemize}
+\item locate the headers of \pkg{Rcpp}, which is straightforward thanks to
+the use of \texttt{LinkingTo: Rcpp}
+\item link against the library by adding this line in the \texttt{Makevars}
+file
+\end{itemize}
+
+\begin{verbatim}
+PKG_LIBS = $(shell $(R_HOME)/bin/Rscript -e "Rcpp:::LdFlags()" )
+\end{verbatim}
+
+and this line in the \texttt{Makevars.win} file for Windows:
+
+\begin{verbatim}
+PKG_LIBS = $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "Rcpp:::LdFlags()")
+\end{verbatim}
+
+This works, and is tested as part of \pkg{Rcpp} unit tests, but we believe
+that it could be made easier by extending the role played by the \texttt{LinkingTo}
+directive. We believe client package should only have to use \texttt{LinkingTo}
+to both find the headers and link against the library. The rest of this document
+discusses the proposed extension for \texttt{LinkingTo}.
+
+
+
+\section{Compiled library}
+
+By the current implementation, compiled code from the target package may only
+be realistically used from itself. This isolates compiled code and delegates
+abstraction to the R level. This is not sufficient for packages such as
+\pkg{Rcpp} which aim to provide \proglang{C++}-level abstractions.
+
+\subsection{ProvidesDynamicLibrary}
+
+The shared object that is made as part of the compilation of the
+\texttt{src} directory of an \pkg{R} package is not necessarilly
+a dynamic library on all platforms, and is not named appropriately for being useful
+to the linker.
+
+We propose a new \texttt{DESCRIPTION} directive that specifies if a
+dynamic library, suitably named, should also be created in the \texttt{libs}
+directory.
+
+\begin{verbatim}
+ProvidesDynamicLibrary: yes
+\end{verbatim}
+
+When set to \texttt{yes} (the default being \texttt{f alse}), the directive
+\texttt{ProvidesDynamicLibrary} would take appropriate actions to create a
+dynamic library in the \texttt{libs} directory. On platforms where it makes
+sense, this might only create a symbolic link between the usual shared object
+and the dynamic library.
+
+\subsection{ProvidesStaticLibrary}
+
+Similarly, the \texttt{ProvidesStaticLibrary} directive would be used
+to trigger generation of a static library.
+
+\begin{verbatim}
+ProvidesStaticLibrary: yes
+\end{verbatim}
+
+\subsection{LinkingTo}
+
+The \texttt{LinkingTo} flag should be extended to honour the
+\texttt{ProvidesDynamicLibrary} and \texttt{ProvidesStaticLibrary} directives
+of the target package.
+
+More precisely, if package \texttt{packB} has this line in its \texttt{DESCRIPTION}
+file :
+
+\begin{verbatim}
+LinkingTo: packA
+\end{verbatim}
+
+Then the DESCRIPTION directives of \pkg{packA} should be checked, and if
+\pkg{packA} declares that it provides a library, the corresponding platform
+specific flags should be generated so that the shared object of the
+\pkg{packB} package links against the appropriate library.
+
+
+\bibliographystyle{abbrvnat}
+\bibliography{Rcpp}
+
+\end{document}
+
More information about the Rcpp-commits
mailing list