Merge branch 'feature/windows-tbb' of github.com:RcppCore/RcppParallel into feature/windows-tbb

Author: jjallaire

NAMESPACE

@@ -1,3 +1,4 @@
 export(setThreadOptions)
 export(defaultNumThreads)
+export(RcppParallelLibs)
 

R/build.R

@@ -1,20 +1,22 @@
 
 
+# Output the LD flags for building against TBB. These flags are propagated
+# to sourceCpp via the inlineCxxPlugin (defined below) and to packages 
+# via a line in Makevars.win like this:
+#
+#   PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "RcppParallel::LdFlags()")
+#
+# Note that this is only required for Windows builds (on Linux and OS X no 
+# explicit link to TBB is required).
+RcppParallelLibs <- function() {
+   cat(tbbLdFlags())
+}
 
-inlineCxxPlugin <- function() {
 
-   # For sourceCpp on Windows we need to explicitly link against tbb.dll
-   if (Sys.info()['sysname'] == "Windows") {
-      tbb <- tbbLibPath()
-      pkgLibs <- paste("-L", asBuildPath(dirname(tbb)), 
-                       " -ltbb", sep="")
-      env <- list(PKG_LIBS = pkgLibs)
-   } else {
-      env <- list() 
-   }
-   
+# Inline plugin used by sourceCpp to link to the TBB library
+inlineCxxPlugin <- function() {
    list(
-      env = env,
+      env = list(PKG_LIBS = tbbLdFlags()),
       includes = "#include <RcppParallel.h>",
       LinkingTo = "RcppParallel",
       body = function( x ) x,
@@ -23,6 +25,19 @@ inlineCxxPlugin <- function() {
 }
 
 
+# Return the linker flags requried for TBB on this platform
+tbbLdFlags <- function() {
+   # on Windows we need to explicitly link against tbb.dll
+   if (Sys.info()['sysname'] == "Windows") {
+      tbb <- tbbLibPath()
+      paste("-L", asBuildPath(dirname(tbb)), " -ltbb", sep="")
+   } else {
+      ""
+   }
+}
+
+
+# Determine the platform-specific path to the TBB library
 tbbLibPath <- function() {
    sysname <- Sys.info()['sysname']
    tbbSupported <- list(
@@ -41,14 +56,15 @@ tbbLibPath <- function() {
    }
 }
 
+
+# Helper function to ape the behavior of the R build system
+# when providing paths to libraries
 asBuildPath <- function(path) {
-   
    if (.Platform$OS.type == "windows") {
       path <- normalizePath(path)
       if (grepl(' ', path, fixed=TRUE))
          path <- utils::shortPathName(path)
       path <- gsub("\\\\", "/", path)
    }
-   
    return(path)
 }

README.md

@@ -35,17 +35,25 @@ You can use the RcppParallel library from within a standalone C++ source file as
 
 #### Packages
 
-If you want to use RcppParallel from within an R package you add the following to your DESCRIPTION file:
+If you want to use RcppParallel from within an R package you add the following to your **DESCRIPTION** file:
 
 ```yaml
 Imports: RcppParallel
 LinkingTo: RcppParallel
 ```
 
-And the following to your NAMESPACE file:
+And the following to your **NAMESPACE** file:
 
-```s
-import(RcppParallel)
+```R
+importFrom(RcppParallel, RcppParallelLibs)
+```
+
+Finally, for Windows builds you'll need the following in **src\\Makevars.win**
+to ensure that your package can link against the TBB DLL:
+
+```makefile
+PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" \
+              -e "RcppParallel::RcppParallelLibs()")
 ```
 
 ### License

man/RcppParallelLibs.Rd

@@ -0,0 +1,27 @@
+\name{RcppParallelLibs}
+\alias{RcppParallelLibs}
+\alias{RcppParallelLibs}
+\title{
+Linker flags for RcppParallel
+}
+\description{
+Output the linker flags required to link to RcppParallel. On
+Windows this includes the underlying TBB library, on other 
+platforms no linker flags are required.
+}
+\usage{
+RcppParallelLibs()
+}
+\details{
+This function is typically called from \code{Makevars.win} as follows:
+
+\code{PKG_LIBS += $(shell "${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe" -e "RcppParallel::RcppParallelLibs()")}
+
+}
+
+\value{
+  Returns \code{NULL} invisibly. The function is not called for it's
+  return value rather for the side effect of outputting the linker
+  flags.
+}
+