some polish for James's nice Rcpp-FAQ addition

also added to ChangeLog and NEWS

Author: eddelbuettel

ChangeLog

@@ -1,3 +1,8 @@
+2016-02-06  James J Balamuta  <[email protected]>
+
+        * vignettes/Rcpp-FAQ.Rnw (Rcpp): Additional material, and corrections,
+        for use on OS X
+
 2016-01-30  Qiang Kou  <[email protected]>
 
         * inst/include/Rcpp/vector/Subsetter.h: Fix the error under gc

inst/NEWS.Rd

@@ -28,6 +28,8 @@
     \itemize{
       \item An entry was added to the Rcpp-FAQ vignette describing the required
       packages for vignette building (\ghit{422}).
+      \item Use on OS X was further detailed (James Balamuta in \ghpr{433} with
+      further review by Bob Rudis)
     }
   }
 }

vignettes/Rcpp-FAQ.Rnw

@@ -433,74 +433,112 @@ complain to its vendor if you are still upset.
 \subsection{I am having problems building Rcpp on OS X, any help ?}
 \label{q:OSX}
 
-There are three known issues regarding Rcpp build problems on OS X.  If you are building packages with RcppArmadillo, there is yet another issue that is addressed separately in \faq{q:OSXArma} below.
+There are three known issues regarding Rcpp build problems on OS X.  If you are
+building packages with RcppArmadillo, there is yet another issue that is
+addressed separately in \faq{q:OSXArma} below.
 
 \subsubsection{Lack of a Compiler}
-By default, OS X does not ship with an active compiler. To enable a compiler one must either install \href{https://itunes.apple.com/us/app/xcode/id497799835?mt=12}{Xcode} (OS X $\le 10.8$) or \href{https://developer.apple.com/library/ios/technotes/tn2339/_index.html}{Xcode Command Line Tools} (OS X $\ge 10.9$). We will focus on the later as the installation requires the use of \texttt{Terminal} and the install size is significantly less than the prior, which is setup using an installer.
+By default, OS X does not ship with an active compiler. To enable a compiler one
+must either install
+\href{https://itunes.apple.com/us/app/xcode/id497799835?mt=12}{Xcode} (OS X
+$\le 10.8$) or
+\href{https://developer.apple.com/library/ios/technotes/tn2339/_index.html}{Xcode
+  Command Line Tools} (OS X $\ge 10.9$). We will focus on the later as the
+installation requires the use of \texttt{Terminal} and the install size is
+significantly less than the prior, which is setup using an installer.
 
 To install XCode Command Line Tools, one must do the following:
 
 \begin{enumerate}
     \item Open \texttt{Terminal} found in \texttt{/Applications/Utilities/}
     \item Type the following: 
-<<osx_xcode,engine='bash', eval = F>>=
+
+<<lang=bash>>=
 $ xcode-select --install
 @
     \item Press "Install" on the window that pops up.
     \item After the installation is complete, type the following in \texttt{Terminal} to ensure the installation was successful:
 
-<<osx_xcode_gcc,engine='bash', eval = F>>=
+<<lang=bash>>=
 $ gcc --version
 @
 \end{enumerate}
 
-After major system's update, e.g. 10.11 to 10.12, you may need to accept the terms and licenses associated the the Xcode command line tools prior to being allowed to compile again.
+After major system updates, e.g. going from version 10.11 to 10.12, you may need
+to accept the terms and licenses associated the the Xcode command line tools
+prior to being allowed to compile again.
 
 To do so, open the \texttt{Terminal} found in \texttt{/Applications/Utilities/} and type:
 
-<<osx_xcode_git,engine='bash', eval = F>>=
+<<lang=bash>>=
 $ git
 @
 
-Press spacebar to move down to the end of the file. There, you should see a prompt asking whether or not you accept the terms via either "Yes" or "No". Enter "Yes" if you agree to the terms to have the command line tools reactivated.
+Press spacebar to move down to the end of the file. There, you should see a
+prompt asking whether or not you accept the terms via either "Yes" or
+"No". Enter "Yes" if you agree to the terms to have the command line tools
+reactivated.
 
 \subsubsection{Differing Mac OS X R Versions Leading to Binary Failures}
 
-There are currently two distinct versions of R for OS X. The first version is a legacy version meant for Mac OS X 10.6 (Snow Leopard) - 10.8 (Mountain Lion). The second version is for more recent system Mac OS X 10.9 (Mavericks), 10.10 (Yosemite), 10.11 (El Capitan). The distinction comes as a result of a change in the compilers shipped with the operating system. As a result, avoid sending package binaries if it is known that your collaborators are working on older systems as the R binaries for these two versions will not be able to mix.
+There are currently two distinct versions of R for OS X. The first version is a
+legacy version meant for Mac OS X 10.6 (Snow Leopard) - 10.8 (Mountain
+Lion). The second version is for more recent system Mac OS X 10.9 (Mavericks),
+10.10 (Yosemite), 10.11 (El Capitan). The distinction comes as a result of a
+change in the compilers shipped with the operating system. As a result, avoid
+sending package binaries if it is known that your collaborators are working on
+older systems as the R binaries for these two versions will not be able to mix.
 
 \subsubsection{No OpenMP Support}
-The OS X operating environment lacks the ability to parallelize sections of code using the \href{http://openmp.org/wp/}{OpenMP} standard. As a result, make sure to protect any reference to OpenMP. In this case, protect the inclusion of headers with:
+The OS X operating environment lacks the ability to parallelize sections of code
+using the \href{http://openmp.org/wp/}{OpenMP} standard. As a result, make sure
+to protect any reference to OpenMP. In this case, protect the inclusion of
+headers with:
 
-<<osx_openmp_header, engine="Rcpp", eval = F>>=
+<<lang=cpp>>=
 #ifdef _OPENMP
   #include <omp.h>
 #endif
 @
 
 And when one goes to parallelize portions of code use:
 
-<<osx_openmp_code, engine="Rcpp", eval = F>>=
+<<lang=cpp>>=
 #ifdef _OPENMP
     // multithreaded OpenMP version of code
 #else
     // single-threaded version of code
 #endif
 @
 
-Doing so will enable the parallelization of the process on Linux and Windows. In the event that Apple enables OpenMP later on, this code will also allow for parallelization to occur.
+Doing so will enable the parallelization of the process on Linux and Windows. In
+the event that Apple enables OpenMP later on, this code will also allow for
+parallelization to occur.
 
-The reason for the lack of OpenMP support is because under OS X, you are not using the \texttt{gcc} compiler. Instead, all the requests are being redirected to \texttt{llvm}. As of LLVM 3.7, the \href{https://clang-omp.github.io/}{community initiative} to enable OpenMP has been merged into the \href{http://openmp.llvm.org/}{official branch}. Thus, there is hope in the next release of Xcode (around WWDC in June 2016) that OpenMP will work on OS X. 
+The reason for the lack of OpenMP support is because under OS X, you are not
+using the \texttt{gcc} compiler. Instead, all the requests are being redirected
+to \texttt{llvm}. As of LLVM 3.7, the
+\href{https://clang-omp.github.io/}{community initiative} to enable OpenMP has
+been merged into the \href{http://openmp.llvm.org/}{official branch}. Thus,
+there is hope in the next release of Xcode (around WWDC in June 2016) that
+OpenMP will work on OS X.
 
 
 \subsubsection{Additional Information / Help}
 
 Below are additional resources that provide information regarding compiling Rcpp code on OS X.
 
 \begin{enumerate}
-    \item A helpful post was provided by Brian Ripley regarding the use of compiling R code with OS X in April 2014 \href{https://stat.ethz.ch/pipermail/r-sig-mac/2014-April/010835.html}{on the \code{r-sig-mac} list}, which is generally recommended for OS X-specific questions and further consultation.
-    \item Another helpful write-up for installation / compilation on OS X Mavericks is
-provided \href{http://www.bioconductor.org/developers/how-to/mavericks-howto/}{by the BioConductor project}.
-    \item Lastly, another resource that exists for installation / compilation help is provided at \url{http://thecoatlessprofessor.com/programming/r-compiler-tools-for-rcpp-on-os-x/}.
+    \item A helpful post was provided by Brian Ripley regarding the use of
+      compiling R code with OS X in April 2014
+      \href{https://stat.ethz.ch/pipermail/r-sig-mac/2014-April/010835.html}{on
+        the \code{r-sig-mac} list}, which is generally recommended for OS
+      X-specific questions and further consultation. 
+    \item Another helpful write-up for installation / compilation on OS X Mavericks is provided
+      \href{http://www.bioconductor.org/developers/how-to/mavericks-howto/}{by the BioConductor project}. 
+    \item Lastly, another resource that exists for installation / compilation
+      help is provided at
+      \url{http://thecoatlessprofessor.com/programming/r-compiler-tools-for-rcpp-on-os-x/}. 
 \end{enumerate}
 
 \textbf{Note:} If you are running into trouble compiling code with RcppArmadillo, please also see \faq{q:OSXArma} listed below. 
@@ -588,10 +626,12 @@ To install the pre-compiled \code{gfortran} binary, do the following:
 \begin{enumerate}
     \item Open \texttt{Terminal} found in \texttt{/Applications/Utilities/}
     \item Type the following: 
-<<osx_gfortran, engine='bash', eval = F>>=
+
+<<lang=bash>>=
 curl -O http://r.research.att.com/libs/gfortran-4.8.2-darwin13.tar.bz2
 sudo tar fvxz gfortran-4.8.2-darwin13.tar.bz2 -C /
 @
+
 \end{enumerate}
 
 For more information on this error, please see TheCoatlessProfessor's  \href{http://thecoatlessprofessor.com/programming/rcpp-rcpparmadillo-and-os-x-mavericks-lgfortran-and-lquadmath-error/}{Rcpp, RcppArmadillo and OS X Mavericks "-lgfortran" and "-lquadmath" error}.
@@ -634,7 +674,8 @@ of paths suitable to be passed to \code{FLIBS}. \R will then search
 these paths when attempting to locate e.g \code{libgfortran} when
 compiling \pkg{RcppArmadillo} or other FORTRAN-dependent code.
 
-Also see \faq{q:OSX} above, and the links provided in that answer. In the event the above solution does not satisfy all the OS X build problems. 
+Also see \faq{q:OSX} above, and the links provided in that answer. In the event
+the above solution does not satisfy all the OS X build problems.  
 
 \section{Examples}