Merge pull request #433 from coatless/patch-1

Improved OS X Rcpp Compiler Information

Author: eddelbuettel

vignettes/Rcpp-FAQ.Rnw

@@ -128,7 +128,7 @@ Specific per-platform notes:
     above detect this and set appropriate flags.
   \item[OS X] users, as noted in the `R Administration' manual \citep[Appendix
     C.4]{R:Administration}, need to install the Apple Developer Tools
-    (\textsl{e.g.}, \texttt{Xcode}) (as well as \texttt{gfortran} if \proglang{R} or
+    (\textsl{e.g.}, \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$) (as well as \texttt{gfortran} if \proglang{R} or
     Fortran-using packages are to be built); also see \faq{q:OSX} and
     \faq{q:OSXArma} below. Depending on whether on OS X release before or after
     Mavericks is used, different additional installation may be needed. Consult
@@ -433,22 +433,77 @@ complain to its vendor if you are still upset.
 \subsection{I am having problems building Rcpp on OS X, any help ?}
 \label{q:OSX}
 
-OS X used to be a little more conservative with compiler versions as Apple
-stuck with gcc-4.2. Following the 'Mavericks' release, it is the opposite as
-only llvm is provide in Xcode.  Moreover, OS X currently has two incompatible
-binary modes for the pre- and post-Mavericks world, and CRAN provides
-releases for both variants. Users have to ensure they are not mixing
-releases between packages, and packages and the corresponding R binary package.
+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.
 
-A helpful post was provided by Brian Ripley 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.
+\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.
 
-Another helpful write-up for installation / compilation on OS X Mavericks is
+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>>=
+$ 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>>=
+$ 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.
+
+To do so, open the \texttt{Terminal} found in \texttt{/Applications/Utilities/} and type:
+
+<<osx_xcode_git,engine='bash', eval = F>>=
+$ 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.
+
+\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.
+
+\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:
+
+<<osx_openmp_header, engine="Rcpp", eval = F>>=
+#ifdef _OPENMP
+  #include <omp.h>
+#endif
+@
+
+And when one goes to parallelize portions of code use:
+
+<<osx_openmp_code, engine="Rcpp", eval = F>>=
+#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.
+
+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/}.
+\end{enumerate}
 
-Also see  \faq{q:OSXArma} below. 
+\textbf{Note:} If you are running into trouble compiling code with RcppArmadillo, please also see \faq{q:OSXArma} listed below. 
 
 %At the time of writing this paragraph (in the spring of 2011), \pkg{Rcpp}
 %(just like CRAN) supports all OS X releases greater or equal to 10.5.
@@ -516,17 +571,34 @@ should be available.
 \subsection{I am having problems building RcppArmadillo on OS X, any help ?}
 \label{q:OSXArma}
 
-Odds are your build failures are due to the absense of \texttt{gfortran}
-and its associated libraries. Alternatively, you have them installed,
-but \R simply doesn't know how to locate them.
+Odds are your build failures are due to the absence of \texttt{gfortran}
+and its associated libraries. The errors that you may receive are related to either: 
+\begin{center}
+\textbf{``-lgfortran''} or \textbf{``-lquadmath''}
+\end{center}
+
+To rectify the root of these errors, there are two options available. The first option is to download and use a fixed set of \texttt{gfortran} binaries that are used to compile R for OS X (e.g. given by the maintainers of the OS X build). The second option is to either use pre-existing \texttt{gfortran} binaries on your machine or download the latest.
 
-While \texttt{gfortran} is distributed as part of \texttt{gcc} and hence
-is available by default on most Linux distributions, it is not
-distributed as part of Apple's command line tools. So, unfortunately,
-you're going to need to install \texttt{gfortran} and its associated
-libraries yourself.
+\subsubsection{Fixed set of \texttt{gfortran} binaries}
 
-Most OS X users have opted into using a custom packaging solution;
+Within this option, you will install a pre-compiled \code{gfortran} binary from
+\href{http://r.research.att.com/libs/}{\texttt{r.research.att.com/libs/}}. The binary listed here was compiled by Simon Urbanek the maintainer of the OS X R versions.
+
+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>>=
+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}.
+
+\subsubsection{Pre-existing or latest \texttt{gfortran} binaries}
+
+Most OS X users that have a pre-existing \texttt{gfortran} binaries or want the latest version, typically use a custom packaging solution to install \texttt{gfortran}; 
 \href{https://www.macports.org/}{\texttt{macports}},
 \href{http://brew.sh/}{\texttt{homebrew}}, and
 \href{http://www.finkproject.org/}{\texttt{fink}} are the usual suspects
@@ -562,13 +634,7 @@ 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.
 
-You can also install a pre-compiled \code{gfortran} binary from
-\href{http://r.research.att.com/libs/}{\texttt{r.research.att.com/libs/}}
--- this is a collection of libraries compiled by Simon Urbanek known
-to be compatible with recent releases of \R.
-
-Also see \faq{q:OSX} above, and the links provided in that answer.
-
+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}