| \input texinfo |
| @c %**start of header |
| @setfilename R-admin.info |
| @settitle R Installation and Administration |
| @setchapternewpage on |
| @defcodeindex en |
| @c %**end of header |
| |
| @syncodeindex fn vr |
| |
| @dircategory Programming |
| @direntry |
| * R Administration: (R-admin). R Installation and Administration. |
| @end direntry |
| |
| @finalout |
| |
| @include R-defs.texi |
| @include version.texi |
| |
| @copying |
| This manual is for R, version @value{VERSION}. |
| |
| @Rcopyright{2001} |
| |
| @quotation |
| @permission{} |
| @end quotation |
| @end copying |
| |
| @titlepage |
| @title R Installation and Administration |
| @subtitle Version @value{VERSION} |
| @author R Core Team |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| @end titlepage |
| |
| @ifplaintext |
| @insertcopying |
| @end ifplaintext |
| |
| @c @ifnothtml |
| @contents |
| @c @end ifnothtml |
| |
| @ifnottex |
| @node Top, Obtaining R, (dir), (dir) |
| @top R Installation and Administration |
| |
| This is a guide to installation and administration for R. |
| |
| @insertcopying |
| |
| @end ifnottex |
| |
| @menu |
| * Obtaining R:: |
| * Installing R under Unix-alikes:: |
| * Installing R under Windows:: |
| * Installing R under macOS:: |
| * Running R:: |
| * Add-on packages:: |
| * Internationalization:: |
| * Choosing between 32- and 64-bit builds:: |
| * The standalone Rmath library:: |
| * Essential and useful other programs under a Unix-alike:: |
| * Configuration on a Unix-alike:: |
| * Platform notes:: |
| * Function and variable index:: |
| * Concept index:: |
| * Environment variable index:: |
| @end menu |
| |
| @node Obtaining R, Installing R under Unix-alikes, Top, Top |
| @chapter Obtaining R |
| @cindex Obtaining R |
| |
| Sources, binaries and documentation for @R{} can be obtained via |
| @acronym{CRAN}, the ``Comprehensive R Archive Network'' whose current |
| members are listed at @uref{https://CRAN.R-project.org/mirrors.html}. |
| |
| @menu |
| * Getting and unpacking the sources:: |
| * Getting patched and development versions:: |
| @end menu |
| |
| @node Getting and unpacking the sources, Getting patched and development versions, Obtaining R, Obtaining R |
| @section Getting and unpacking the sources |
| @cindex Sources for R |
| |
| The simplest way is to download the most recent |
| @file{R-@var{x}.@var{y}.@var{z}.tar.gz} file, and unpack it with |
| |
| @example |
| tar -xf R-@var{x}.@var{y}.@var{z}.tar.gz |
| @end example |
| |
| @noindent |
| on systems that have a suitable@footnote{e.g.@: @acronym{GNU} |
| @command{tar} version 1.15 or later, or that from the @samp{libarchive} |
| (as used on macOS) or `Heirloom Toolchest' distributions.} |
| @command{tar} installed. On other systems you need to have the |
| @command{gzip} program installed, when you can use |
| |
| @example |
| gzip -dc R-@var{x}.@var{y}.@var{z}.tar.gz | tar -xf - |
| @end example |
| |
| The pathname of the directory into which the sources are unpacked should |
| not contain spaces, as most @command{make} programs (and specifically |
| @acronym{GNU} @command{make}) do not expect spaces. |
| |
| If you want the build to be usable by a group of users, set @code{umask} |
| before unpacking so that the files will be readable by the target group |
| (e.g.,@: @code{umask 022} to be usable by all users). Keep this |
| setting of @code{umask} whilst building and installing. |
| |
| If you use a fairly recent @acronym{GNU} version of @command{tar} and do |
| this as a root account (which on Windows includes accounts with |
| administrator privileges) you may see many warnings about changing |
| ownership. In which case you can use |
| |
| @example |
| tar --no-same-owner -xf R-@var{x}.@var{y}.@var{z}.tar.gz |
| @end example |
| |
| @noindent |
| and perhaps also include the option @option{--no-same-permissions}. |
| @enindex TAR_OPTIONS |
| (These options can also be set in the @env{TAR_OPTIONS} environment |
| variable: if more than one option is included they should be separated |
| by spaces.) |
| |
| |
| |
| @node Getting patched and development versions, , Getting and unpacking the sources, Obtaining R |
| @section Getting patched and development versions |
| |
| A patched version of the current release, @samp{r-patched}, and the |
| current development version, @samp{r-devel}, are available as daily |
| tarballs and via access to the @R{} Subversion repository. (For the two |
| weeks prior to the release of a minor (4.x.0) version, @samp{r-patched} |
| tarballs may refer to beta/release candidates of the upcoming release, |
| the patched version of the current release being available via |
| Subversion.) |
| |
| The tarballs are available from |
| @uref{https://stat.ethz.ch/R/daily/}. Download |
| @file{R-patched.tar.gz} or @file{R-devel.tar.gz} (or the @file{.tar.bz2} |
| versions) and unpack as described in the previous section. They are |
| built in exactly the same way as distributions of @R{} releases. |
| |
| @menu |
| * Using Subversion and rsync:: |
| @end menu |
| |
| @node Using Subversion and rsync, , Getting patched and development versions, Getting patched and development versions |
| @subsection Using Subversion and rsync |
| @cindex Subversion |
| |
| Sources are also available via @uref{https://svn.R-project.org/R/}, the |
| R Subversion repository. If you have a Subversion client (see |
| @uref{https://subversion.apache.org/}), you can check out and update the |
| current @samp{r-devel} from |
| @uref{https://svn.r-project.org/R/trunk/} and the current |
| @samp{r-patched} from |
| @samp{https://svn.r-project.org/@/R/@/branches/@/R-@var{x}-@var{y}-branch/} |
| (where @var{x} and @var{y} are the major and minor number of the current |
| released version of R). E.g., use |
| |
| @example |
| svn checkout https://svn.r-project.org/R/trunk/ @var{path} |
| @end example |
| |
| @noindent |
| to check out @samp{r-devel} into directory @var{path} (which will be |
| created if necessary). The alpha, beta and RC versions of an upcoming |
| @var{x.y.0} release are available from |
| @samp{https://svn.r-project.org/R/branches/R-@var{x}-@var{y}-branch/} in |
| the four-week period prior to the release. |
| |
| Note that @samp{https:} is required@footnote{for some Subversion clients |
| @samp{http:} may appear to work, but requires continual redirection.}, |
| and that the SSL certificate for the Subversion server of the @R{} |
| project should be recognized as from a trusted source. |
| |
| Note that retrieving the sources by e.g.@: @command{wget -r} or |
| @command{svn export} from that URL will not work (and will give a error |
| early in the @command{make} process): the Subversion information is |
| needed to build @R{}. |
| |
| The Subversion repository does not contain the current sources for the |
| recommended packages, which can be obtained by @command{rsync} or |
| downloaded from @acronym{CRAN}. To use @code{rsync} to install the |
| appropriate sources for the recommended packages, run |
| @code{./tools/rsync-recommended} from the top-level directory of the |
| @R{} sources. |
| |
| If downloading manually from @acronym{CRAN}, do ensure that you have the |
| correct versions of the recommended packages: if the number in the file |
| @file{VERSION} is @samp{@var{x}.@var{y}.@var{z}} you need to download |
| the contents of @samp{https://CRAN.R-project.org/src/contrib/@var{dir}}, |
| where @var{dir} is @samp{@var{x}.@var{y}.@var{z}/Recommended} for |
| r-devel or @file{@var{x}.@var{y}-patched/Recommended} for r-patched, |
| respectively, to directory @file{src/library/Recommended} in the sources |
| you have unpacked. After downloading manually you need to execute |
| @command{tools/link-recommended} from the top level of the sources to |
| make the requisite links in @file{src/library/Recommended}. A suitable |
| incantation from the top level of the @R{} sources using @command{wget} |
| might be (for the correct value of @file{@var{dir}}) |
| |
| @example |
| wget -r -l1 --no-parent -A\*.gz -nd -P src/library/Recommended \ |
| https://CRAN.R-project.org/src/contrib/@var{dir} |
| ./tools/link-recommended |
| @end example |
| |
| |
| |
| @node Installing R under Unix-alikes, Installing R under Windows, Obtaining R, Top |
| @chapter Installing R under Unix-alikes |
| @cindex Installing under Unix-alikes |
| |
| @R{} will configure and build under most common Unix and Unix-alike |
| platforms including @samp{@var{cpu}-*-linux-gnu} for the |
| @cputype{alpha}, @cputype{arm64}, @cputype{hppa}, @cputype{ix86}, |
| @cputype{m68k}, @cputype{mips}, @cputype{mipsel}#, @cputype{ppc64}, |
| @cputype{s390x}, @cputype{sparc64}, and @cputype{x86_64} @acronym{CPU}s, |
| @c (see e.g.@: @uref{https://buildd.debian.org/build.php?&pkg=r-base}), |
| @c Actually, see https://packages.debian.org/unstable/math/r-base-core as |
| @c the build daemon is not used for all platforms; note also that Debian |
| @c has x86_64 <=> amd64, ix86 <=> i386. |
| @samp{x86_64-@/apple-@/darwin} and |
| @samp{aarch64-@/apple-@/darwin}@footnote{aka `Apple Silicon', known to |
| some as @samp{arm64-@/apple-@/darwin}.} as well as perhaps (it is |
| tested less frequently on these platforms) @samp{i386-@/sun-@/solaris}, |
| @samp{i386-@/*-@/freebsd}, @samp{x86_64-@/*-@/freebsd}, |
| @samp{i386-@/*-@/netbsd}, @samp{x86_64-@/*-@/openbsd} and |
| @samp{powerpc-@/ibm-@/aix6*} |
| |
| @cindex Linux |
| @cindex macOS |
| In addition, binary distributions are available for some common Linux |
| distributions (see the @acronym{FAQ} for current details) and for |
| macOS. These are installed in platform-specific ways, so for the rest |
| of this chapter we consider only building from the sources. |
| |
| Cross-building is not possible: installing @R{} builds a minimal version |
| of @R{} and then runs many @R{} scripts to complete the build. |
| |
| @menu |
| * Simple compilation:: |
| * Help options:: |
| * Making the manuals:: |
| * Installation:: |
| * Uninstallation:: |
| * Sub-architectures:: |
| * Other Options:: |
| * Testing a Unix-alike Installation:: |
| @end menu |
| |
| @node Simple compilation, Help options, Installing R under Unix-alikes, Installing R under Unix-alikes |
| @section Simple compilation |
| |
| First review the essential and useful tools and libraries in |
| @ref{Essential and useful other programs under a Unix-alike}, and install |
| those you |
| @enindex TMPDIR |
| want or need. Ensure that either the environment variable @env{TMPDIR} |
| is either unset (and @file{/tmp} exists and can be written in and |
| scripts can be executed from) or points to the absolute path to a valid |
| temporary directory (one from which execution of scripts is allowed) |
| which does not contain spaces.@footnote{Most aspects will work with |
| paths containing spaces, but external software used by @R{} may not.} |
| |
| @findex R_HOME |
| Choose a directory to install the @R{} tree (@R{} is not just a binary, but |
| has additional data sets, help files, font metrics etc). Let us call |
| this place @var{R_HOME}. Untar the source code. This should create |
| directories @file{src}, @file{doc}, and several more under a top-level |
| directory: change to that top-level directory (At this point North |
| American readers should consult @ref{Setting paper size}.) Issue the |
| following commands: |
| |
| @findex configure |
| |
| @example |
| ./configure |
| make |
| @end example |
| |
| @noindent |
| (See @ref{Using make} if your make is not called @samp{make}.) Users of |
| Debian-based 64-bit systems@footnote{which use @file{lib} rather than |
| @file{lib64} for their primary 64-bit library directories: attempts are |
| made to detect such systems.} may need |
| |
| @example |
| ./configure LIBnn=lib |
| make |
| @end example |
| |
| |
| Then check the built system works correctly by |
| |
| @example |
| make check |
| @end example |
| |
| @noindent |
| Failures are not necessarily problems as they might be caused by missing |
| functionality, but you should look carefully at any reported |
| discrepancies. (Some non-fatal errors are expected in locales that do |
| not support Latin-1, in particular in true @code{C} locales and |
| non-UTF-8 non-Western-European locales.) A failure in |
| @file{tests/ok-errors.R} may indicate inadequate resource limits |
| (@pxref{Running R}). |
| |
| More comprehensive testing can be done by |
| |
| @example |
| make check-devel |
| @end example |
| |
| @noindent |
| or |
| |
| @example |
| make check-all |
| @end example |
| |
| @noindent |
| see file @file{tests/README} and @ref{Testing a Unix-alike Installation} |
| for the possibilities of doing this in parallel. Note that these checks |
| are only run completely if the recommended packages are installed. |
| |
| If the @command{configure} and @command{make} commands execute |
| successfully, a shell-script front-end called @file{R} will be created |
| and copied to @file{@var{R_HOME}/bin}. You can link or copy this script |
| to a place where users can invoke it, for example to |
| @file{/usr/local/bin/R}. You could also copy the man page @file{R.1} to |
| a place where your @command{man} reader finds it, such as |
| @file{/usr/local/man/man1}. If you want to install the complete @R{} |
| tree to, e.g., @file{/usr/local/lib/R}, see @ref{Installation}. Note: |
| you do not @emph{need} to install @R{}: you can run it from where it was |
| built. |
| |
| You do not necessarily have to build @R{} in the top-level source |
| directory (say, @file{@var{TOP_SRCDIR}}). To build in |
| @file{@var{BUILDDIR}}, run |
| |
| @findex configure |
| |
| @example |
| cd @var{BUILDDIR} |
| @var{TOP_SRCDIR}/configure |
| make |
| @end example |
| |
| @noindent |
| and so on, as described further below. This has the advantage of always |
| keeping your source tree clean and is particularly recommended when you |
| work with a version of @R{} from Subversion. (You may need |
| @acronym{GNU} @command{make} to allow this, and you will need no spaces |
| in the path to the build directory. It is unlikely to work if the |
| source directory has previously been used for a build.) |
| |
| There are many settings which can be customized when building @R{} and |
| most are described in the file @file{config.site} in the top-level |
| source directory. This can be edited, but for an installation using |
| @file{@var{BUILDDIR}} it is better to put the changed settings in a |
| newly-created file @file{config.site} in the build directory. |
| |
| @c For those obtaining @R{} @emph{via} Subversion, one additional step is |
| @c necessary: |
| @c @cindex Vignettes |
| @c @cindex Subversion |
| |
| @c @example |
| @c make vignettes |
| @c @end example |
| |
| @c @noindent |
| @c which makes the @pkg{grid} vignettes (which are contained in the |
| @c tarballs): it make take several minutes. |
| |
| Now @code{rehash} if necessary, type @kbd{R}, and read the @R{} manuals |
| and the @R{} @acronym{FAQ} (files @file{FAQ} or |
| @file{doc/manual/R-FAQ.html}, or |
| @uref{https://CRAN.R-project.org/doc/FAQ/R-FAQ.html} which always |
| has the version for the latest release of @R{}). |
| |
| Note: if you already have @R{} installed, check that where you installed |
| @R{} replaces or comes earlier in your path than the previous |
| installation. Some systems are set up to have @file{/usr/bin} (the |
| standard place for a system installation) ahead of @file{/usr/local/bin} |
| (the default place for installation of @R{}) in their default path, and |
| some do not have @file{/usr/local/bin} on the default path. |
| |
| @node Help options, Making the manuals, Simple compilation, Installing R under Unix-alikes |
| @section Help options |
| |
| @R{} by default provides help pages as plain text displayed in a pager, |
| with the options (see the help for @code{help}) of displaying help as |
| HTML or PDF. |
| |
| By default @HTML{} help pages are created when needed rather than being |
| built at install time. |
| |
| If you need to disable the server and want @HTML{} help, there is the |
| option to build @HTML{} pages when packages are installed |
| (including those installed with @R{}). This is enabled by the |
| @command{configure} option @option{--enable-prebuilt-html}. Whether |
| @command{R CMD INSTALL} (and hence @code{install.packages}) pre-builds |
| @HTML{} pages is determined by looking at the @R{} installation and is |
| reported by @command{R CMD INSTALL --help}: it can be overridden by |
| specifying one of the @command{INSTALL} options @option{--html} or |
| @option{--no-html}. |
| |
| The server is disabled by setting the environment variable |
| @enindex R_DISABLE_HTTPD |
| @env{R_DISABLE_HTTPD} to a non-empty value, either before @R{} is |
| started or within the @R{} session before @HTML{} help (including |
| @code{help.start}) is used. It is also possible that system security |
| measures will prevent the server from being started, for example if the |
| loopback interface has been disabled. See |
| @code{?tools::startDynamicHelp} for more details. |
| |
| @node Making the manuals, Installation, Help options, Installing R under Unix-alikes |
| @section Making the manuals |
| @cindex Manuals |
| |
| There is a set of manuals that can be built from the sources, |
| |
| @table @samp |
| @item fullrefman |
| Printed versions of all the help pages for base and recommended packages |
| (around 3750 pages). |
| @item refman |
| Printed versions of the help pages for selected base packages (around |
| 2200 pages) |
| @item R-FAQ |
| R @acronym{FAQ} |
| @item R-intro |
| ``An Introduction to R''. |
| @item R-data |
| ``R Data Import/Export''. |
| @item R-admin |
| ``R Installation and Administration'', this manual. |
| @item R-exts |
| ``Writing R Extensions''. |
| @item R-lang |
| ``The R Language Definition''. |
| @end table |
| |
| @noindent |
| To make these (with @samp{fullrefman} rather than @samp{refman}), use |
| |
| @example |
| make pdf @r{to create PDF versions} |
| make info @r{to create info files (not @samp{refman} nor @samp{fullrefman}).} |
| @end example |
| |
| @c texi2any from Mar 2013. |
| You will not be able to build any of these unless you have |
| @command{texi2any} version 5.1 or later installed, and for PDF you must |
| have @command{texi2dvi} and @file{texinfo.tex} installed (which are part |
| of the @acronym{GNU} @pkg{texinfo} distribution but are, especially |
| @file{texinfo.tex}, often made part of the @TeX{} package in |
| re-distributions). The path to @command{texi2any} can be set by macro |
| @samp{TEXI2ANY} in @file{config.site}. NB: @command{texi2any} requires |
| @command{perl}. |
| |
| The PDF versions can be viewed using any recent PDF viewer: they have |
| hyperlinks that can be followed. The info files are suitable for |
| reading online with Emacs or the standalone @acronym{GNU} @command{info} |
| program. The PDF versions will be created using the paper size selected |
| at configuration (default ISO a4): this can be overridden by setting |
| @env{R_PAPERSIZE} |
| @enindex R_PAPERSIZE |
| on the @command{make} command line, or setting @env{R_PAPERSIZE} in the |
| environment and using @command{make -e}. (If re-making the manuals for |
| a different paper size, you should first delete the file |
| @file{doc/manual/version.texi}. The usual value for North America would |
| be @samp{letter}.) |
| |
| There are some issues with making the PDF reference manual, |
| @file{fullrefman.pdf} or @file{refman.pdf}. The help files contain both |
| non-ASCII characters (e.g.@: in @file{text.Rd}) and upright quotes, |
| neither of which are contained in the standard @LaTeX{} Computer Modern |
| fonts. We have provided the following alternatives: |
| |
| @table @code |
| @item times |
| (The default.) Using standard PostScript fonts, Times Roman, Helvetica |
| and Courier. This works well both for on-screen viewing and for |
| printing. One disadvantage is that the Usage and Examples sections may |
| come out rather wide: this can be overcome by using @emph{in addition} |
| either of the options @code{inconsolata} (on a Unix-alike only if found |
| by @command{configure}) or @code{beramono}, which replace the Courier |
| monospaced font by Inconsolata or Bera Sans mono respectively. (You |
| will need the @LaTeX{} package @pkg{inconsolata}@footnote{Instructions |
| on how to install the latest version are at |
| @uref{https://www.ctan.org/tex-archive/fonts/inconsolata/}.} or |
| @pkg{bera} installed.) |
| |
| Note that in most @LaTeX{} installations this will not actually use the |
| standard fonts for PDF, but rather embed the URW clones NimbusRom, |
| NimbusSans and (for Courier, if used) NimbusMon. |
| |
| This needs @LaTeX{} packages @pkg{times}, @pkg{helvetic} and (if used) |
| @pkg{courier} installed. |
| |
| @item lm |
| Using the @emph{Latin Modern} fonts. These are not often installed as |
| part of a @TeX{} distribution, but can obtained from |
| @uref{https://www.ctan.org/tex-archive/fonts/ps-type1/lm/} and |
| mirrors. This uses fonts rather similar to Computer Modern, but is not |
| so good on-screen as @code{times}. |
| |
| @c @item cm-super |
| @c Using type-1 versions of the Computer Modern fonts by Vladimir Volovich. |
| @c This is a large installation, obtainable from |
| @c @uref{https://www.ctan.org/tex-archive/fonts/ps-type1/cm-super/} |
| @c and its mirrors. These type-1 fonts have poor hinting and so are |
| @c nowhere near as readable on-screen as the other three options. |
| @end table |
| |
| The default can be overridden by setting the environment variable |
| @enindex R_RD4PDF |
| @env{R_RD4PDF}. (On Unix-alikes, this will be picked up at install time |
| and stored in @file{etc/Renviron}, but can still be overridden when the |
| manuals are built, using @command{make -e}.) The usual@footnote{on a |
| Unix-alike, @samp{inconsolata} is omitted if not found by |
| @command{configure}.} default value for @env{R_RD4PDF} is |
| @samp{times,inconsolata,hyper}: omit @samp{inconsolata} if you do not have |
| @LaTeX{} package @pkg{inconsolata} installed. As from @R{} 4.2.0, |
| @samp{hyper} is always enabled (with a fallback if @LaTeX{} package |
| @pkg{hyperref} is not installed). |
| |
| Further options, e.g@: for @pkg{hyperref}, can be included in a file |
| @file{Rd.cfg} somewhere on your @LaTeX{} search path. For example, if |
| you prefer to hyperlink the text and not the page number in the table of |
| contents use |
| @example |
| \ifthenelse@{\boolean@{Rd@@use@@hyper@}@}@{\hypersetup@{linktoc=section@}@}@{@} |
| @end example |
| |
| @noindent |
| or |
| @example |
| \ifthenelse@{\boolean@{Rd@@use@@hyper@}@}@{\hypersetup@{linktoc=all@}@}@{@} |
| @end example |
| |
| @noindent |
| to hyperlink both text and page number. |
| |
| Ebook versions of most of the manuals in one or both of @file{.epub} and |
| @file{.mobi} formats can be made by running in @file{doc/manual} one of |
| @example |
| make ebooks |
| make epub |
| make mobi |
| @end example |
| |
| @noindent |
| This requires @command{ebook-convert} from |
| @uref{https://calibre-ebook.com/download, @command{Calibre}}, or from |
| most Linux distributions. If necessary the path to |
| @command{ebook-convert} can be set as make macro @env{EBOOK} by editing |
| @file{doc/manual/Makefile} (which contains a commented value suitable |
| for macOS) or using @command{make -e}. |
| |
| |
| @node Installation, Uninstallation, Making the manuals, Installing R under Unix-alikes |
| @section Installation |
| @cindex Installation |
| |
| To ensure that the installed tree is usable by the right group of users, |
| set @code{umask} appropriately (perhaps to @samp{022}) before unpacking |
| the sources and throughout the build process. |
| |
| After |
| |
| @findex configure |
| @example |
| ./configure |
| make |
| make check |
| @end example |
| |
| @noindent |
| (or, when building outside the source, |
| @code{@var{TOP_SRCDIR}/configure}, etc) have been completed |
| successfully, you can install the complete @R{} tree to your system by |
| typing |
| |
| @example |
| make install |
| @end example |
| |
| @noindent |
| A parallel make can be used (but run @command{make} before @command{make |
| install}). Those using GNU @command{make} 4.0 or later may want to use |
| @command{make -j @var{n} -O} to avoid interleaving of output. |
| |
| This will install to the following directories: |
| |
| @table @asis |
| @item @file{@var{prefix}/bin} or @file{@var{bindir}} |
| the front-end shell script and other scripts and executables |
| @item @file{@var{prefix}/man/man1} or @file{@var{mandir}/man1} |
| the man page |
| @item @file{@var{prefix}/@var{LIBnn}/R} or @file{@var{libdir}/R} |
| all the rest (libraries, on-line help system, @dots{}). Here |
| @var{LIBnn} is usually @samp{lib}, but may be @samp{lib64} on some |
| 64-bit Linux systems. This is known as the @R{} home directory. |
| @end table |
| |
| @noindent |
| where @var{prefix} is determined during configuration (typically |
| @file{/usr/local}) and can be set by running @command{configure} with |
| the option @option{--prefix}, as in |
| |
| @findex configure |
| @example |
| ./configure --prefix=/where/you/want/R/to/go |
| @end example |
| |
| @noindent |
| where the value should be an absolute path. This causes @command{make |
| install} to install the @R{} script to |
| @file{/where/you/want/R/to/go/bin}, and so on. The prefix of the |
| installation directories can be seen in the status message that is |
| displayed at the end of @command{configure}. The installation may need |
| to be done by the owner of @file{@var{prefix}}, often a root account. |
| |
| There is the option of using @command{make install-strip} (@pxref{Debugging |
| Symbols}). |
| |
| |
| You can install into another directory tree by using |
| |
| @example |
| make prefix=/path/to/here install |
| @end example |
| |
| @noindent |
| at least with @acronym{GNU} @command{make} (but not some other Unix |
| makes). |
| |
| More precise control is available at configure time via options: see |
| @command{configure --help} for details. (However, most of the `Fine |
| tuning of the installation directories' options are not used by @R{}.) |
| |
| Configure options @option{--bindir} and @option{--mandir} are supported |
| and govern where a copy of the @command{R} script and the @command{man} |
| page are installed. |
| |
| The configure option @option{--libdir} controls where the main @R{} |
| files are installed: the default is @samp{@var{eprefix}/@var{LIBnn}}, |
| where @var{eprefix} is the prefix used for installing |
| architecture-dependent files, defaults to @var{prefix}, and can be set |
| via the configure option @option{--exec-prefix}. |
| |
| Each of @code{bindir}, @code{mandir} and @code{libdir} can also be |
| specified on the @command{make install} command line (at least for |
| @acronym{GNU} @command{make}). |
| |
| The @command{configure} or @command{make} variables @code{rdocdir} and |
| @code{rsharedir} can be used to install the system-independent |
| @file{doc} and @file{share} directories to somewhere other than |
| @code{libdir}. The C header files can be installed to the value of |
| @code{rincludedir}: note that as the headers are not installed into a |
| subdirectory you probably want something like |
| @code{rincludedir=/usr/local/include/R-@value{VERSIONno}}. |
| |
| If you want the @R{} home to be something other than |
| @file{@var{libdir}/R}, use @option{rhome}: for example |
| |
| @example |
| make install rhome=/usr/local/lib64/R-@value{VERSIONno} |
| @end example |
| |
| @noindent |
| will use a version-specific @R{} home on a non-Debian Linux 64-bit |
| system. |
| |
| If you have made @R{} as a shared/static library you can install it in |
| your system's library directory by |
| |
| @example |
| make prefix=/path/to/here install-libR |
| @end example |
| |
| @noindent |
| where @code{prefix} is optional, and @code{libdir} will give more |
| precise control.@footnote{This will be needed if more than one |
| sub-architecture is to be installed.} However, you should not install |
| to a directory mentioned in @env{LDPATHS} (e.g.@: |
| @file{/usr/local/lib64}) if you intend to work with multiple versions of |
| @R{}, since that directory may be given precedence over the @file{lib} |
| directory of other @R{} installations. |
| |
| @example |
| make install-strip |
| @end example |
| |
| @noindent |
| will install stripped executables, and on platforms where this is |
| supported, stripped libraries in directories @file{lib} and |
| @file{modules} and in the standard packages. |
| |
| Note that installing @R{} into a directory whose path contains spaces is |
| not supported, and some aspects (such as installing source packages) |
| will not work. |
| @c The main problem is the Makefile include in etc/Makeconf |
| |
| @cindex Manuals, installing |
| |
| To install info and PDF versions of the manuals, use one or both of |
| |
| @example |
| make install-info |
| make install-pdf |
| @end example |
| |
| @noindent |
| Once again, it is optional to specify @code{prefix}, @code{libdir} or |
| @code{rhome} (the PDF manuals are installed under the @R{} home |
| directory). |
| |
| More precise control is possible. For info, the setting used is that of |
| @code{infodir} (default @file{@var{prefix}/info}, set by configure |
| option @option{--infodir}). The PDF files are installed into the @R{} |
| @file{doc} tree, set by the @command{make} variable @code{rdocdir}. |
| |
| A staged installation is possible, that it is installing @R{} into a |
| temporary directory in order to move the installed tree to its final |
| destination. In this case @code{prefix} (and so on) should reflect the |
| @enindex DESTDIR |
| final destination, and @env{DESTDIR} should be used: see |
| @uref{https://www.gnu.org/prep/standards/html_node/DESTDIR.html}. |
| |
| You can optionally install the run-time tests that are part of |
| @command{make check-all} by |
| |
| @example |
| make install-tests |
| @end example |
| |
| @noindent |
| which populates a @file{tests} directory in the installation. |
| |
| |
| @node Uninstallation, Sub-architectures, Installation, Installing R under Unix-alikes |
| @section Uninstallation |
| |
| You can uninstall @R{} by |
| |
| @example |
| make uninstall |
| @end example |
| |
| @noindent |
| optionally specifying @code{prefix} etc in the same way as specified for |
| installation. |
| |
| This will also uninstall any installed manuals. There are specific |
| targets to uninstall info and PDF manuals in file |
| @file{doc/manual/Makefile}. |
| |
| Target @code{uninstall-tests} will uninstall any installed tests, as |
| well as removing the directory @file{tests} containing the test results. |
| |
| An installed shared/static @code{libR} can be uninstalled by |
| |
| @example |
| make prefix=/path/to/here uninstall-libR |
| @end example |
| |
| |
| @node Sub-architectures, Other Options, Uninstallation, Installing R under Unix-alikes |
| @section Sub-architectures |
| |
| Some platforms can support closely related builds of @R{} which can |
| share all but the executables and dynamic objects. Examples include |
| builds under Linux for different @acronym{CPU}s or 32- and 64-bit |
| builds. |
| |
| @R{} supports the idea of architecture-specific builds, specified by |
| adding @samp{r_arch=@var{name}} to the @command{configure} line. Here |
| @var{name} can be anything non-empty, and is used to name subdirectories |
| of @file{lib}, @file{etc}, @file{include} and the package @file{libs} |
| subdirectories. Example names from other software are the use of |
| @file{sparcv9} on Sparc Solaris and @file{32} by @command{gcc} on |
| @cputype{x86_64} Linux. |
| |
| If you have two or more such builds you can install them over each other |
| (and for 32/64-bit builds on one architecture, one build can be done |
| without @samp{r_arch}). The space savings can be considerable: on |
| @cputype{x86_64} Linux a basic install (without debugging symbols) took |
| 74Mb, and adding a 32-bit build added 6Mb. If you have installed |
| multiple builds you can select which build to run by |
| |
| @example |
| R --arch=@var{name} |
| @end example |
| |
| @noindent |
| and just running @samp{R} will run the last build that was installed. |
| |
| @code{R CMD INSTALL} will detect if more than one build is installed and |
| try to install packages with the appropriate library objects for each. |
| This will not be done if the package has an executable @code{configure} |
| script or a @file{src/Makefile} file. In such cases you can install for |
| extra builds by |
| |
| @example |
| R --arch=@var{name} CMD INSTALL --libs-only @var{pkg1} @var{pkg2} @dots{} |
| @end example |
| |
| If you want to mix sub-architectures compiled on different platforms |
| (for example @cputype{x86_64} Linux and @cputype{i686} Linux), it is |
| wise to use explicit names for each, and you may also need to set |
| @option{libdir} to ensure that they install into the same place. |
| |
| When sub-architectures are used the version of @command{Rscript} in |
| e.g.@: @file{/usr/bin} will be the last installed, but |
| architecture-specific versions will be available in e.g.@: |
| @file{/usr/lib64/R/bin/exec$@{@var{R_ARCH}@}}. Normally all installed |
| architectures will run on the platform so the architecture of |
| @command{Rscript} itself does not matter. The executable |
| @command{Rscript} will run the @command{R} script, and at that time the |
| @enindex R_ARCH |
| setting of the @env{R_ARCH} environment variable determines the |
| architecture which is run. |
| |
| When running post-install tests with sub-architectures, use |
| |
| @example |
| R --arch=@var{name} CMD make check[-devel|all] |
| @end example |
| |
| @noindent |
| to select a sub-architecture to check. |
| |
| Sub-architectures are also used on Windows, but by selecting executables |
| within the appropriate @file{bin} directory, |
| @file{@var{R_HOME}/bin/i386} or @file{@var{R_HOME}/bin/x64}. For |
| backwards compatibility there are executables |
| @file{@var{R_HOME}/bin/R.exe} and @file{@var{R_HOME}/bin/Rscript.exe}: |
| these will run an executable from one of the subdirectories, which one |
| being taken first from the |
| @enindex R_ARCH |
| @env{R_ARCH} environment variable, then from the |
| @option{--arch} command-line option@footnote{with possible values |
| @samp{i386}, @samp{x64}, @samp{32} and @samp{64}.} and finally from the |
| installation default (which is 32-bit for a combined 32/64 bit @R{} |
| installation). @R{} 4.2.0 follows the scheme, but supports and includes |
| only 64-bit builds. |
| |
| @menu |
| * Multilib:: |
| @end menu |
| |
| @node Multilib, , Sub-architectures, Sub-architectures |
| @subsection Multilib |
| |
| For some Linux distributions@footnote{mainly on RedHat and Fedora, whose |
| layout is described here.}, there is an alternative mechanism for mixing |
| 32-bit and 64-bit libraries known as @emph{multilib}. If the Linux |
| distribution supports multilib, then parallel builds of @R{} may be |
| installed in the sub-directories @file{lib} (32-bit) and @file{lib64} |
| (64-bit). The build to be run may then be selected using the |
| @command{setarch} command. For example, a 32-bit build may be run by |
| |
| @example |
| setarch i686 R |
| @end example |
| |
| The @command{setarch} command is only operational if both 32-bit and |
| 64-bit builds are installed. If there is only one installation of @R{}, |
| then this will always be run regardless of the architecture specified |
| by the @command{setarch} command. |
| |
| There can be problems with installing packages on the non-native |
| architecture. It is a good idea to run e.g.@: @code{setarch i686 R} for |
| sessions in which packages are to be installed, even if that is the only |
| version of @R{} installed (since this tells the package installation |
| code the architecture needed). |
| |
| There is a potential problem with packages using Java, as the |
| post-install for a @cputype{i686} RPM on @cputype{x86_64} Linux |
| reconfigures Java and will find the @cputype{x86_64} Java. If you know |
| where a 32-bit Java is installed you may be able to run (as root) |
| |
| @example |
| export JAVA_HOME=<path to jre directory of 32-bit Java> |
| setarch i686 R CMD javareconf |
| @end example |
| |
| @noindent |
| to get a suitable setting. |
| |
| When this mechanism is used, the version of @command{Rscript} in |
| e.g.@: @file{/usr/bin} will be the last installed, but an |
| architecture-specific version will be available in |
| e.g.@: @file{/usr/lib64/R/bin}. Normally all installed architectures |
| will run on the platform so the architecture of @command{Rscript} does |
| not matter. |
| |
| @node Other Options, Testing a Unix-alike Installation, Sub-architectures, Installing R under Unix-alikes |
| @section Other Options |
| |
| There are many other installation options, most of which are listed by |
| @command{configure --help}. Almost all of those not listed elsewhere in |
| this manual are either standard @command{autoconf} options not relevant |
| to @R{} or intended for specialist uses by the @R{} developers. |
| |
| One that may be useful when working on @R{} itself is the option |
| @option{--disable-byte-compiled-packages}, which ensures that the base |
| and recommended packages are not byte-compiled. (Alternatively the |
| (make or environment) variable @env{R_NO_BASE_COMPILE} can be set to a |
| non-empty value for the duration of the build.) |
| |
| Option @option{--with-internal-tzcode} makes use of @R{}'s own code and |
| copy of the IANA database for managing timezones. This will be |
| preferred where there are issues with the system implementation, usually |
| involving times after 2037 or before 1916. An alternative time-zone |
| directory@footnote{How to prepare such a directory is described in file |
| @file{src/extra/tzone/Notes} in the @R{} sources.} can be used, pointed |
| to by environment variable @env{TZDIR}: this should contain files such |
| as @file{Europe/London}. On all tested OSes the system timezone was |
| deduced correctly, but if necessary it can be set as the value of |
| environment variable @env{TZ}. |
| |
| Options @option{--with-internal-iswxxxxx}, |
| @option{--with-internal-towlower} and @option{--with-internal-wcwidth} |
| were introduced in @R{} 4.1.0. These control the replacement of the |
| system wide-character classification (such as @code{iswprint}), |
| case-changing (@code{wctrans}) and width (@code{wcwidth} and |
| @code{wcswidth}) functions by ones contained in the @R{} sources. |
| Replacement of the classification functions has been done for many years |
| on macOS and AIX (and Windows): option @option{--with-internal-iswxxxxx} |
| allows this to be suppressed on those platforms or used on others. |
| Replacing the case-changing functions was new in @R{} 4.1.0 and the |
| default on macOS (and on Windows since @R{} 4.2.0). Replacement of the |
| width functions has also been done for many years and remains the |
| default. These options will only matter to those working with non-ASCII |
| character data, especially in languages written in a non-Western |
| script@footnote{But on Windows problems have been seen with |
| case-changing functions on accented Latin-1 characters.} (which includes |
| `symbols' such as emoji). Note that one of those @code{iswxxxxx} is |
| @code{iswprint} which is used to decide whether to output a character as |
| a glyph or as a @samp{\U@{xxxxxx@}} escape---for example, try |
| @samp{"\U1f600"}, an emoji. The width functions are of most importance |
| in East Asian locale: their values differ between such locales. |
| (Replacing the system functions provides a degree of |
| plaform-independence (including to OS updates) but replaces it with a |
| dependence on the @R{} version.) |
| |
| @menu |
| * Debugging Symbols:: |
| * OpenMP Support:: |
| * C++ Support:: |
| * Link-Time Optimization:: |
| @end menu |
| |
| @node Debugging Symbols, OpenMP Support, Other Options, Other Options |
| @subsection Debugging Symbols |
| |
| By default, @command{configure} adds a flag (usually @option{-g}) to the |
| compilation flags for C, Fortran and CXX sources. This will slow down |
| compilation and increase object sizes of both @R{} and packages, so it |
| may be a good idea to change those flags (set @samp{CFLAGS} etc in |
| @file{config.site} before configuring, or edit files @file{Makeconf} |
| and @file{etc/Makeconf} between running @command{configure} and |
| @command{make}). |
| |
| Having debugging symbols available is useful both when running @R{} under a |
| debugger (e.g., @command{R -d gdb}) and when using sanitizers and |
| @command{valgrind}, all things intended for experts. |
| |
| Debugging symbols (and some others) can be `stripped' on installation by |
| using |
| @example |
| make install-strip |
| @end example |
| @noindent |
| How well this is supported depends on the platform: it works best on |
| those using GNU @code{binutils}. On @cputype{x86_64} Linux a typical |
| reduction in overall size was from 92MB to 66MB. On macOS debugging |
| symbols are not by default included in @file{.dylib} and @file{.so} |
| files, so there is negligible difference. |
| |
| @node OpenMP Support, C++ Support, Debugging Symbols, Other Options |
| @subsection OpenMP Support |
| |
| By default @command{configure} searches for suitable flags@footnote{for |
| example, @option{-fopenmp}, @option{-xopenmp} or @option{-qopenmp}. |
| This includes for @command{clang} and the Intel and Oracle compilers.} |
| for OpenMP support for the C, C++ (default standard) and Fortran |
| compilers. |
| |
| Only the C result is currently used for @R{} itself, and only if |
| @code{MAIN_LD}/@code{DYLIB_LD} were not specified. This can be |
| overridden by specifying |
| @example |
| R_OPENMP_CFLAGS |
| @end example |
| |
| Use for packages has similar restrictions (involving @code{SHLIB_LD} and |
| similar: note that as Fortran code is by default linked by the C (or |
| C++) compiler, both need to support OpenMP) and can be overridden by |
| specifying some of |
| @example |
| SHLIB_OPENMP_CFLAGS |
| SHLIB_OPENMP_CXXFLAGS |
| SHLIB_OPENMP_FFLAGS |
| @end example |
| |
| @noindent |
| Setting these to an empty value will disable OpenMP for that compiler |
| (and configuring with @option{--disable-openmp} will disable all |
| detection@footnote{This does not necessarily disable @emph{use} of |
| OpenMP -- the @command{configure} code allows for platforms where OpenMP |
| is used without a flag. For the @command{flang} compiler in late 2017, |
| the Fortran runtime always used OpenMP.} of OpenMP). The |
| @command{configure} detection test is to compile and link a standalone |
| OpenMP program, which is not the same as compiling a shared object and |
| loading it into the C program of @R{}'s executable. Note that |
| overridden values are not tested. |
| |
| @node C++ Support, Link-Time Optimization, OpenMP Support, Other Options |
| @subsection C++ Support |
| |
| C++ is not used by @R{} itself, but support is provided for installing |
| packages with C++ code via @command{make} macros defined in file |
| @file{etc/Makeconf} (and with explanations in file @file{config.site}): |
| @example |
| CXX |
| CXXFLAGS |
| CXXPICFLAGS |
| CXXSTD |
| |
| CXX11 |
| CXX11STD |
| CXX11FLAGS |
| CXX11PICFLAGS |
| |
| CXX14 |
| CXX14STD |
| CXX14FLAGS |
| CXX14PICFLAGS |
| |
| CXX17 |
| CXX17STD |
| CXX17FLAGS |
| CXX17PICFLAGS |
| |
| CXX20 |
| CXX20STD |
| CXX20FLAGS |
| CXX20PICFLAGS |
| @end example |
| @noindent |
| The macros @code{CXX} etc are those used by default for C++ code. |
| @command{configure} will attempt to set the rest suitably, choosing for |
| @code{CXXSTD} and @code{CXX11STD} a suitable flag such as |
| @option{-std=c++11} for C++11 support (which is required if C++ is to be |
| supported at all). Similarly, @command{configure} will if possible |
| choose for @code{CXX14STD} a flag@footnote{This was a valid option for |
| @command{g++} 5 and later and 2016 versions of the Intel and Solaris |
| compilers. For earlier versions of @command{g++} one could try |
| @option{-std=c++1y}.} such as @option{-std=c++14} for C++14 support, |
| @option{-std=c++17} or @option{-std=c++1z} for support for C++17 and |
| @option{-std=c++20} or @option{-std=c++2a} for support for C++20.. The |
| inferred values can be overridden in file @file{config.site} or on the |
| @command{configure} command line: user-supplied values will be tested by |
| compiling some C++11/14/17/20 code. |
| |
| It may be that there is no suitable flag for C++14/17/20 support with |
| the default compiler, in which case a different compiler could be |
| selected for @code{CXX14} or @code{CXX17} or @code{CXX20} with its |
| corresponding flags. |
| |
| The @option{-std} flag is supported by the GCC, @command{clang++} and |
| Intel compilers. Currently accepted values are (plus some synonyms) |
| @example |
| g++: c++11 gnu+11 c++14 gnu++14 c++17 gnu++17 c++2a gnu++2a (from 8) |
| c++20 gnu++20 (from 10) |
| Intel: c++11 c++14 (from 16.0) c++17 (from 17.0) c++20 (from 19.0?) |
| @end example |
| @noindent |
| (Those for @command{clang++} are documented at |
| @uref{https://clang.llvm.org/cxx_status.html}, and follow @code{g++}: |
| @code{-std=c++20} is supported from Clang 10.) |
| |
| @c c++1y does not pass the configure test in 4.9.3 |
| @c , with @option{-std=c++1y} (introduced@footnote{See |
| @c @uref{https://gcc.gnu.org/projects/cxx-status.html#cxx14} for which |
| @c C++14 features it supported.} in version 4.9.x) remaining as a deprecated |
| @c synonym. |
| |
| `Standards' for @command{g++} starting with @samp{gnu} enable `GNU |
| extensions': what those are is hard to track down. |
| |
| For the use of C++11 and later in @R{} packages see the `Writing R |
| Extensions' manual. Prior to @R{} 3.6.0 the default C++ standard was |
| that of the compiler used: currently it is C++14 (if available): this |
| can be overridden by setting @samp{CXXSTD} when @R{} is configured. |
| |
| @uref{https://en.cppreference.com/w/cpp/compiler_support} indicates |
| which versions of common compilers support (parts of) which C++ |
| standards. |
| |
| @node Link-Time Optimization, , C++ Support, Other Options |
| @subsection Link-Time Optimization |
| |
| There is support for using link-time optimization (LTO) if the toolchain |
| supports it: configure with flag @option{--enable-lto}. When LTO is |
| enabled it is used for compiled code in add-on packages unless the flag |
| @option{--enable-lto=R} is used@footnote{Then recommended packages |
| installed as part of the @R{} installation do use LTO, but not packages |
| installed later.}. |
| |
| The main benefit seen to date from LTO has been detecting long-standing |
| bugs in the ways packages pass arguments to compiled code and between |
| compilation units. Benchmarking in 2020 with |
| @command{gcc}/@command{gfortran}@tie{}10 showed gains of a few percent |
| in increased performance and reduction in installed size for builds |
| without debug symbols, but large size reductions for some |
| packages@footnote{A complete @acronym{CRAN} installation reduced from 50 |
| to 35GB.} with debug symbols. (Performance and size gains are said to be |
| most often seen in complex C++ builds.) |
| |
| Whether toolchains support LTO is often unclear: all of the C compiler, |
| the Fortran compiler@footnote{although there is the possibility to |
| exclude Fortran but that misses some of the benefits.} and linker have |
| to support it, and support it by the same mechanism (so mixing compiler |
| families may not work and a non-default linker may be needed). It has |
| been supported by the GCC and LLVM projects for some years with |
| diverging implementations. |
| |
| LTO support was added in 2011 for GCC@tie{}4.5 on Linux but was little |
| used before 2019: compiler support has steadily improved over those |
| years and @option{--enable-lto=R} is nowadays used for some routine |
| @acronym{CRAN} checking. |
| |
| Unfortunately @option{--enable-lto} may be accepted but silently do |
| nothing useful if some of the toolchain does not support LTO: this is |
| less common than it once was. |
| |
| Various macros can be set in file @file{config.site} to customize how |
| LTO is used. If the Fortran compiler is not of the same family as the |
| C/C++ compilers, set macro @samp{LTO_FC} (probably to empty). Macro |
| @samp{LTO_LD} can be used to select an alternative linker should that be |
| needed. |
| |
| |
| @menu |
| * LTO with GCC:: |
| * LTO with LLVM:: |
| * LTO for package checking:: |
| @end menu |
| |
| @node LTO with GCC, LTO with LLVM, Link-Time Optimization, Link-Time Optimization |
| @subsubsection LTO with GCC |
| |
| This has been tested on Linux with |
| @command{gcc}/@command{gfortran}@tie{}8 and later: that needed setting |
| (e.g.@: in @file{config.site}) |
| @example |
| AR=gcc-ar |
| RANLIB=gcc-ranlib |
| @end example |
| @noindent |
| For non-system compilers or if those wrappers have not been installed |
| one may need something like |
| @example |
| AR="ar --plugin=/path/to/liblto_plugin.so" |
| RANLIB="ranlib --plugin=/path/to/liblto_plugin.so" |
| @end example |
| @noindent |
| amd @code{NM} may be needed to be set analogously. (If using an |
| LTO-enabled build to check packages, set environment variable |
| @env{UserNM}@footnote{not @env{NM} as we found @command{make} |
| overriding that.} to @samp{gcc-nm}.) |
| |
| @c http://hubicka.blogspot.com/2019/05/gcc-9-link-time-and-inter-procedural.html |
| With GCC 5 and later it is possible to parallelize parts of the LTO |
| linking process: set the make macro @samp{LTO} to something like |
| @samp{LTO=-flto=8} (to use 8 threads), for example in file |
| @file{config.site}. |
| |
| Under some circumstances and for a few packages, the PIC flags have |
| needed overriding on Linux with GCC 9 and later: e.g@: use in |
| @file{config.site}: |
| @example |
| CPICFLAGS=-fPIC |
| CXXPICFLAGS=-fPIC |
| CXX11PICFLAGS=-fPIC |
| CXX14PICFLAGS=-fPIC |
| CXX17PICFLAGS=-fPIC |
| CXX20PICFLAGS=-fPIC |
| FPICFLAGS=-fPIC |
| @end example |
| @noindent |
| We suggest only using these if the problem is encountered (it was not |
| seen on @acronym{CRAN} with GCC 10 at the time of writing). |
| |
| Note that @R{} may need to be re-compiled after even a minor update to |
| the compiler (e.g.@: from 10.1 to 10.2) but this may not be clear from |
| confused compiler messages. |
| |
| @node LTO with LLVM, LTO for package checking, LTO with GCC, Link-Time Optimization |
| @subsubsection LTO with LLVM |
| |
| LLVM supports another type of LTO called `Thin LTO' as well as a similar |
| implementation to GCC, sometimes called `Full LTO'. (See |
| @uref{https://clang.llvm.org/docs/ThinLTO.html}.) Currently the only |
| LLVM compiler relevant to @R{} is @command{clang} for which this can be |
| selected by setting macro @samp{LTO=-flto=thin}. LLVM has |
| @example |
| AR=llvm-ar |
| RANLIB=llvm-ranlib |
| @end example |
| @noindent |
| (but macOS does not, and these are not needed there). Where the linker |
| supports a parallel backend for Thin LTO this can be specified @emph{via} |
| the macro @samp{LTO_LD}: see the URL above for per-linker settings and |
| further linking optimizations.) |
| |
| For example, on macOS one might use |
| @example |
| LTO=-flto=thin |
| LTO_FC= |
| LTO_LD=-Wl,-mllvm,-threads=4 |
| @end example |
| to use Thin LTO with 4 threads for C/C++ code, but skip LTO for Fortran |
| code compiled with @command{gfortran}. |
| |
| It is said to be particularly beneficial to use @option{-O3} for |
| @command{clang} in conjunction with LTO. |
| |
| @node LTO for package checking, , LTO with LLVM, Link-Time Optimization |
| @subsubsection LTO for package checking |
| |
| LTO effectively compiles all the source code in a package as a single |
| compilation unit and so allows the compiler (with sufficient diagnostic |
| flags such as @option{-Wall}) to check consistency between what are |
| normally separate compilation units. |
| |
| With @command{gcc}/@command{gfortran} 9.x and later@footnote{probably |
| also 8.4 and later.} LTO will flag inconsistencies in calls to Fortran |
| subroutines/functions, both between Fortran source files and between |
| Fortran and C/C++. @command{gfortran} 8.4, 9.2 and later can help |
| understanding these by extracting C prototypes from Fortran source files |
| with option @option{-fc-prototypes-external}, e.g.@: that (at the time |
| of writing) Fortran @code{LOGICAL} corresponds to @code{int_least32_t *} |
| in C. |
| |
| @c This worked in 2019 but with Fedora 32 did not export dpotrf from dlapack.o |
| On some systems it is possible to build the BLAS, LINPACK and LAPACK |
| support as static libraries containing intermediate-level code that LTO |
| will compile for all objects linked against these libraries, by |
| configuring @R{} with @option{--enable-lto=check}. This checks the |
| consistency of calls to BLAS/LINPACK/LAPACK in any packages installed |
| using the build. @strong{NB:} as its name suggests, this option is |
| intended only for checking installation of @R{} and packages: it |
| includes these library routines (those called directly and all they |
| depend on) in each package. This is unlikely to work in conjunction |
| with non-default options for BLAS and LAPACK, and `linking' against |
| these libraries may be very slow. |
| |
| @node Testing a Unix-alike Installation, , Other Options, Installing R under Unix-alikes |
| @section Testing an Installation |
| |
| Full post-installation testing is possible only if the test files have |
| been installed with |
| |
| @example |
| make install-tests |
| @end example |
| |
| @noindent |
| which populates a @file{tests} directory in the installation. |
| |
| If this has been done, two testing routes are available. The first is |
| to move to the home directory of the @R{} installation (as given by |
| @command{R RHOME} or from @R{} as @code{R.home()}) and run |
| |
| @example |
| cd tests |
| ## followed by one of |
| ../bin/R CMD make check |
| ../bin/R CMD make check-devel |
| ../bin/R CMD make check-all |
| @end example |
| |
| @noindent |
| and other useful targets are @code{test-BasePackages} and |
| @code{test-Recommended} to run tests of the standard and recommended |
| packages (if installed) respectively. |
| |
| This re-runs all the tests relevant to the installed @R{} (including for |
| example the code in the package vignettes), but not for example the ones |
| checking the example code in the manuals nor making the standalone Rmath |
| library. This can occasionally be useful when the operating environment |
| has been changed, for example by OS updates or by substituting the |
| @acronym{BLAS} (@pxref{Shared BLAS}). |
| |
| Parallel checking of packages may be possible: set the environment |
| variable @env{TEST_MC_CORES} to the maximum number of processes to be |
| run in parallel. This affects both checking the package examples (part |
| of @command{make check}) and package sources (part of @command{make |
| check-devel} and @command{make check-recommended}). It does require a |
| @command{make} command which supports the @command{make -j @var{n}} |
| option: most do. |
| |
| |
| Alternatively, the installed @R{} can be run, preferably with |
| @option{--vanilla}. Then |
| @enindex LC_COLLATE |
| |
| @example |
| pdf("tests.pdf") ## optional, but prevents flashing graphics windows |
| Sys.setenv(LC_COLLATE = "C", LC_TIME = "C", LANGUAGE = "en") |
| tools::testInstalledBasic("both") |
| tools::testInstalledPackages(scope = "base") |
| tools::testInstalledPackages(scope = "recommended") |
| @end example |
| |
| @noindent |
| runs the basic tests and then all the tests on the standard and |
| recommended packages. These tests can be run from anywhere: the basic |
| tests write their results in the @file{tests} folder of the @R{} home |
| directory and run fewer tests than the first approach: in particular |
| they do not test things which need Internet access---that can be tested |
| by |
| @example |
| tools::testInstalledBasic("internet") |
| @end example |
| |
| It is possible to test the installed packages (but not their |
| package-specific tests) by @code{testInstalledPackages} even if |
| @command{make install-tests} was not run. The outputs are written under the |
| current directory unless a different one is specified by @code{outDir}. |
| |
| Note that the results may depend on the language set for times and |
| messages: for maximal similarity to reference results you may want to |
| try setting (before starting the @R{} session) |
| |
| @example |
| LANGUAGE=en |
| @end example |
| |
| @noindent |
| and use a UTF-8 or Latin-1 locale. |
| |
| |
| @node Installing R under Windows, Installing R under macOS, Installing R under Unix-alikes, Top |
| @chapter Installing R under Windows |
| @cindex Installing under Windows |
| |
| [The rest of this paragraph is only relevant after release.] |
| The @file{bin/windows} directory of a @acronym{CRAN} site contains |
| binaries for a base distribution and a large number of add-on packages |
| from @acronym{CRAN} to run on 64-bit Windows. |
| |
| R is best tested on current versions of Windows 10 and Windows Server 2022 |
| with UTF-8 as the charset encoding. It runs on older versions of Windows, |
| but normally with other charset encoding and may require manual installation |
| of the Universal C Runtime (UCRT). |
| |
| Your file system must allow long file names (as is likely except |
| perhaps for some network-mounted systems). If it does not also support |
| conversion to short name equivalents (a.k.a. DOS 8.3 names), then @R{} |
| @emph{must} be installed in a path that does not contain spaces. |
| |
| Installation is @emph{via} the installer |
| @file{@value{RWVERSION}-win.exe}. Just double-click on the icon and |
| follow the instructions. You can uninstall @R{} from the Control Panel. |
| |
| You will be asked to choose a language for installation: that choice |
| applies to both installation and un-installation but not to running @R{} |
| itself. |
| |
| See the @uref{https://CRAN.R-project.org/bin/windows/base/rw-FAQ.html, R |
| Windows @acronym{FAQ}} for more details on the binary installer and for |
| information on use on older Windows systems. |
| |
| @menu |
| * Building from source:: |
| * Checking the build:: |
| * Testing a Windows Installation:: |
| @end menu |
| |
| @node Building from source, Checking the build, Installing R under Windows, Installing R under Windows |
| @section Building from source |
| |
| It is possible to use other 64-bit toolchains (including `MSYS2') with UCRT |
| support to build @R{}, but this manual only documents that used for binary |
| distributions of @R{} 4.2.x. When using other toolchains, makefiles of @R{} |
| and packages may need to be adapted. |
| |
| @menu |
| * The Windows toolset:: |
| * LaTeX on Windows:: |
| @end menu |
| |
| @node The Windows toolset, LaTeX on Windows, Building from source, Building from source |
| @subsection The Windows toolset |
| |
| The binary distribution of @R{} is currently built with tools |
| from |
| @uref{https://cran.r-project.org/bin/windows/Rtools/rtools42/rtools.html,Rtools42 |
| for Windows}. See |
| @uref{https://cran.r-project.org/bin/windows/base/howto-R-devel.html, Building |
| R and packages} for more details on how to use it. |
| |
| The toolset includes compilers (GCC version 10.3.0 with selected additional |
| patches) and runtime libraries from @uref{http://mingw-w64.org/,the |
| `MinGW-w64' project} and a number of pre-compiled static libraries and |
| headers used by @R{} and @R{} packages, compiled by |
| @uref{https://mxe.cc/,'MXE'} (M cross environment, with updates by Tomas |
| Kalibera). The toolset also includes build tools from the |
| @uref{https://www.msys2.org/, the 'MSYS2' project}. Additional build tools |
| packaged by 'MSYS2' may be installed via a package manager (@samp{pacman}). |
| |
| The toolsets used for 64-bit Windows from 2008--22 were based on |
| MinGW-w64. The assistance of Yu Gong at a crucial step in porting @R{} |
| to MinGW-w64 is gratefully acknowledged, as well as help from Kai Tietz, |
| the lead developer of the MinGW-w64 project and from Martin Storsjo. |
| |
| @node LaTeX on Windows, , The Windows toolset, Building from source |
| @subsection @LaTeX{} |
| |
| Both building @R{} and checking packages need a distribution of @LaTeX{} |
| installed, with the directory containing @command{pdflatex} on the path. |
| |
| The @samp{MiKTeX} (@uref{https://miktex.org/}) distribution of |
| @LaTeX{} is that used on @acronym{CRAN}. This can be set up to install |
| extra packages `on the fly' (without asking), which is the simplest way |
| to use it. The `basic' version of @samp{MiKTeX} will need to add some |
| packages.@footnote{There are reports of segfaults when @samp{MiKTeX} |
| installs additional packages when making @file{NEWS.pdf}: re-running |
| @command{make} seems to solve this.} In any case ensure that the |
| @pkg{inconsolata} package is installed---you can check with the |
| @samp{MiKTeX} Package Manager. |
| |
| It is also possible to use the TeX Live distribution from |
| @uref{https://www.tug.org/texlive/}. (The @acronym{CRAN} package |
| @CRANpkg{tinytex} can install and manage a subset of TeX Live.) |
| |
| @node Checking the build, Testing a Windows Installation, Building from source, Installing R under Windows |
| @section Checking the build |
| |
| You can test a build by running |
| |
| @example |
| make check |
| @end example |
| |
| @noindent |
| The recommended packages can be checked by |
| |
| @example |
| make check-recommended |
| @end example |
| |
| @noindent |
| Other levels of checking are |
| |
| @example |
| make check-devel |
| @end example |
| |
| @noindent |
| for a more thorough check of the @R{} functionality, and |
| |
| @example |
| make check-all |
| @end example |
| |
| @noindent |
| for both @code{check-devel} and @code{check-recommended}. |
| |
| If a test fails, there will almost always be a @file{.Rout.fail} file in |
| the directory being checked (often @file{tests/Examples} or |
| @file{tests}): examine the file to help pinpoint the problem. |
| |
| Parallel checking of package sources (part of @command{make check-devel} |
| and @command{make check-recommended}) is possible: see the environment |
| variable @env{TEST_MC_CORES} to the maximum number of processes to be |
| run in parallel. |
| |
| @node Testing a Windows Installation, , Checking the build, Installing R under Windows |
| @section Testing an Installation |
| |
| The Windows installer contains a set of test files used when building |
| @R{}. |
| |
| The toolset is not needed to run these tests, but more comprehensive |
| analysis of errors will be given if @command{diff} is in the path. |
| |
| Launch either @code{Rgui} or @code{Rterm} (preferred), preferably with |
| @option{--vanilla}. Then run |
| |
| @example |
| Sys.setenv(LC_COLLATE = "C", LC_TIME="C", LANGUAGE = "en") |
| tools::testInstalledBasic("both") |
| tools::testInstalledPackages(scope = "base") |
| tools::testInstalledPackages(scope = "recommended") |
| @end example |
| |
| @noindent |
| runs the basic tests and then all the tests on the standard and recommended |
| packages. These tests can be run from anywhere: @code{testInstalledBasic} |
| writes results in the @file{tests} folder of the @R{} home directory (as |
| given by @code{R.home()}) and @code{testInstalledPackages} under the current |
| directory unless a different one is specified by @code{outDir}. |
| |
| For the @file{tests} folder to be writeable, one normally needs to install |
| @R{} to a directory other than the default @file{C:\Program Files}. The |
| installer also allows to install @R{} without Administrator privileges, see |
| the @uref{https://CRAN.R-project.org/bin/windows/base/rw-FAQ.html, R Windows |
| @acronym{FAQ}} for more details. |
| |
| The results of @code{example(md5sums)} when testing @pkg{tools} may |
| differ from the reference output as some files are installed with |
| Windows' CRLF line endings. Also, expect differences in |
| @file{reg-plot-latin1.pdf}. |
| |
| One can also run tests from the toolset shell (e.g. @command{bash}) similarly |
| to a Unix-like installation. Move to the home directory of the @R{} |
| installation (as given by @command{R RHOME} or from @R{} as @code{R.home()}) |
| and run |
| |
| @example |
| cd tests |
| ## followed by one of |
| ../bin/R CMD make check |
| ../bin/R CMD make check-devel |
| ../bin/R CMD make check-all |
| @end example |
| |
| Remember that @LaTeX{} needs to be on the path. |
| |
| @node Installing R under macOS, Running R, Installing R under Windows, Top |
| @chapter Installing R under macOS |
| @cindex macOS |
| |
| @macro Rapp{} |
| @sc{R.app} |
| @end macro |
| |
| [The rest of this paragraph is only relevant after release.] |
| The front page of a @acronym{CRAN} site has a link `Download R for (Mac) |
| OS X' which takes you to a new page. Two files are offered for download, |
| @file{R-@value{VERSIONno}.pkg} and @file{R-@value{VERSIONno}-arm64.pkg}. |
| The first runs on macOS 10.13 and later on @cputype{x86_64} (Intel) CPU |
| (High Sierra, Mojave, Catalina, Big Sur, Monterey, @dots{}). It can |
| also be installed on @cputype{arm64} (aka `Apple Silicon' aka `M1') CPUs |
| running Big Sur or later using `Rosetta' emulation@footnote{You may be |
| asked to install Rosetta at first use -- |
| @url{https://support.apple.com/en-us/HT211861} -- which may need |
| administrator privileges.}, as can @acronym{CRAN} binary packages. |
| Package @file{R-@value{VERSIONno}-arm64.pkg} is a `native' build for |
| `Apple Silicon' Macs and runs @emph{only} on those (under macOS 11 or |
| later, Big Sur, Monterey, @dots{}). |
| |
| Installers for R-patched and R-devel are usually available from |
| @uref{https://mac.R-project.org}. (Some of these packages are |
| unsigned/not notarized: to install those Control/right/two-finger click, |
| select @samp{Open With} and @samp{Installer}.) |
| |
| For some older versions of the OS you can in principle (it is little |
| tested) install @R{} from the sources (see @ref{macOS}). |
| |
| Those with a @cputype{arm64} Mac have a choice of build. The |
| @cputype{x86_64} build is a little better supported (for example, more |
| binary packages are available from @acronym{CRAN} and only |
| @cputype{x86_64} from some other repositories). Rosetta emulation works |
| really well, with a very few reports of problems with binary packages |
| solved by re-compilation. The `native' build is a little faster (and |
| for some tasks, considerably so) but may give different numerical |
| results from the far more common @cputype{x86_64} platforms (on macOS |
| and other OSes) as ARM hardware lacks extended-precision floating-point |
| operations. |
| |
| It is important that if you use a binary installer package that your OS |
| is fully updated: look at `Software Update' in 'System Preferences' |
| (`Updates' from the `App Store' on Mojave and earlier) to be sure. |
| |
| To install, just double-click on the icon of the file you downloaded. |
| At the `Installation Type' stage, note the option to `Customize'. This |
| currently shows four components: everyone will need the `R Framework' |
| component: the remaining components are optional. (The `Tcl/Tk' |
| component is needed to use package @pkg{tcltk}. The `Texinfo' component |
| is only needed by those installing source packages or @R{} from its |
| sources.) |
| |
| These are Apple Installer packages. If you encounter any problem during |
| the installation, please check the Installer log by clicking on the |
| ``Window'' menu and item ``Installer Log''. The full output (select |
| ``Show All Log'') is useful for tracking down problems. Note the the |
| installer is clever enough to try to upgrade the last-installed version |
| of the application where you installed it (which may not be where you |
| want this time @dots{}). |
| |
| Various parts of the build require XQuartz to be installed: see |
| @uref{https://www.xquartz.org/releases/}.@footnote{At the time of |
| writing the Intel distribution was built/tested against 2.7.11 for |
| compatibility with @R{} 4.0.0: the @cputype{arm64} one against 2.8.1.} |
| These include the @pkg{tcltk} package and the @code{X11} graphics device: |
| attempting to use these without XQuartz will if possible remind |
| you.@footnote{If @command{otool} is installed: it is part of the macOS |
| Command Line Tools.} This is also needed for some |
| @cindex Cairo |
| builds of the cairographics-based devices (which are not often used on |
| macOS) such as @code{png(type = "cairo")} and @code{svg()} and some |
| third-party packages (e.g.@: @CRANpkg{rgl}). |
| |
| If you update your macOS version, you should re-install @R{} (and |
| perhaps XQuartz): the installer may tailor the installation to the |
| current version of the OS. |
| |
| For building @R{} from source, see @ref{macOS}. |
| |
| |
| @menu |
| * Running R under macOS:: |
| * Uninstalling under macOS:: |
| * Multiple versions:: |
| @end menu |
| |
| @node Running R under macOS, Uninstalling under macOS, Installing R under macOS, Installing R under macOS |
| @section Running R under macOS |
| |
| There are two ways to run @R{} on macOS from a @acronym{CRAN} binary |
| distribution. |
| |
| There is a GUI console normally installed with the @R{} icon in |
| @file{/Applications} which you can run by double-clicking (e.g.@: from |
| Launchpad or Finder). (If you cannot find it there it was possibly |
| installed elsewhere so try searching for it in Spotlight.) This is |
| usually referred to as @Rapp{} to distinguish it from command-line @R{}: |
| its user manual is currently part of the macOS FAQ at |
| @uref{https://cran.r-project.org/bin/macosx/RMacOSX-FAQ.html} and |
| can be viewed from @Rapp{}'s `Help' menu. |
| |
| |
| You can run command-line @R{} and @command{Rscript} from a |
| Terminal@footnote{The installer puts links to @command{R} and |
| @command{Rscript} in @file{/usr/local/bin}. If these are missing or |
| that is not on your path, you can run directly the copies in |
| @file{/Library/Frameworks/R.framework/Resources/bin} or link those |
| yourself to somewhere on your path.} so these can be typed as commands |
| as on any other Unix-alike: see the next chapter of this manual. There |
| are some small differences which may surprise users of @R{} on other |
| platforms, notably the default location of the personal library |
| directory (under @file{~/Library/R}, e.g.@: |
| @file{~/Library/R/x86_64/4.2/library}), and that warnings, messages and |
| other output to @file{stderr} are highlighted in bold. |
| |
| @c https://ryanhomer.github.io/posts/build-openmp-macos-catalina-complete |
| Those using the @command{zsh} shell (the default for new user accounts |
| as from Catalina) might find the command @command{R} being masked by the |
| @command{zsh} builtin @command{r} (which recalls commands). One can use |
| a full path to @R{} in an alias, or add @code{disable r} to |
| @file{~/.zshrc}. |
| |
| If you have installed both installer packages on an @code{arm64} Mac, |
| the last installed will be used. |
| |
| @c https://stat.ethz.ch/pipermail/r-sig-mac/2014-October/011131.html |
| It has been reported that running @Rapp{} may fail if no preferences are |
| stored, so if it fails when launched for the very first time, try it |
| again (the first attempt will store some preferences). |
| |
| Users of @Rapp{} need to be aware of the `App Nap' feature |
| (@uref{https://developer.apple.com/library/archive/releasenotes/MacOSX/WhatsNewInOSX/Articles/MacOSX10_9.html}) |
| which can cause @R{} tasks to appear to run very slowly when not |
| producing output in the console. Here are ways to avoid it: |
| |
| @itemize |
| @item |
| Ensure that the console is completely visible (or at least the activity |
| indicator at the top right corner is visible). |
| |
| @item |
| In a Terminal, run |
| @example |
| defaults write org.R-project.R NSAppSleepDisabled -bool YES |
| @end example |
| |
| @noindent |
| (see @uref{https://developer.apple.com/library/archive/releasenotes/MacOSX/WhatsNewInOSX/Articles/MacOSX10_9.html}). |
| @end itemize |
| |
| Using the @code{X11} graphics device or the X11-based versions of @code{View()} |
| and @code{edit()} for data frames and matrices (the latter are the |
| default for command-line @R{} but not @Rapp{}) requires |
| @uref{https://www.xquartz.org/, XQuartz} to be installed. |
| |
| Under some rather nebulous circumstances messages have been seen from |
| @code{fontconfig} about missing/unreadable configuration files when |
| using cairo-based devices, especially @code{X11(type = "cairo")}. With |
| XQuartz installed there are two @code{fontconfig} areas from different |
| versions and it can help to set |
| @example |
| setenv FONTCONFIG_PATH /opt/X11/lib/X11/fontconfig |
| @end example |
| @noindent |
| Another symptom has been that italic/oblique fonts are replaced by |
| upright ones. |
| |
| @node Uninstalling under macOS, Multiple versions, Running R under macOS, Installing R under macOS |
| @section Uninstalling under macOS |
| |
| @R{} for macOS consists of two parts: the GUI (@Rapp{}) and the R |
| framework. Un-installation is as simple as removing those folders |
| (e.g.@: by dragging them onto the Trash aka Bin). The typical installation will |
| install the GUI into the @file{/Applications/R.app} folder and the R |
| framework into the @file{/Library/Frameworks/R.framework} folder. The |
| links to @file{R} and @file{Rscript} in @file{/usr/local/bin} should |
| also be removed. |
| |
| If you want to get rid of @R{} more completely using a Terminal, simply |
| run: |
| |
| @example |
| sudo rm -Rf /Library/Frameworks/R.framework /Applications/R.app \ |
| /usr/local/bin/R /usr/local/bin/Rscript |
| @end example |
| |
| The installation consists of up to four Apple packages:@footnote{At the |
| time of writing: use @command{pkgutil --pkgs | grep -i org.r-project} to |
| check..} for the Intel build, @code{org.R-project.R.fw.pkg}, |
| @code{org.R-project.R.GUI.pkg}, @code{org.r-project.x86_64.tcltk.x11} |
| and @code{org.r-project.x86_64.texinfo}. You can use @code{sudo pkgutil |
| --forget} if you want the Apple Installer to forget about the package |
| without deleting its files (useful for the @R{} framework when |
| installing multiple @R{} versions in parallel), or after you have |
| deleted the files. @strong{NB:} the package names are case-sensitive and |
| the @R{} domain is given inconsistently. |
| |
| Uninstalling the Tcl/Tk and Texinfo components (which are installed under |
| @file{/usr/local} on a @cputype{x86_64} build and @file{/opt/R/arm64} |
| for an @cputype{arm64} one) is not as simple. You can list the files |
| they installed in a Terminal by e.g.@: |
| |
| @example |
| pkgutil --files org.r-project.x86_64.tcltk.x11 |
| pkgutil --files org.r-project.x86_64.texinfo |
| @end example |
| |
| @noindent |
| These are paths relative to @file{/}, the root of the file system. |
| @c Maybe too dangerous for naive users. |
| @c file.remove removes empty directories on Unix. |
| @c The second could be uninstalled by an @R{} script like |
| |
| @c @example |
| @c lis <- system2("pkgutil", "--files org.r-project.x86_64.texinfo", stdout = TRUE) |
| @c setwd("/") |
| @c file.remove(rev(lis)) |
| @c @end example |
| |
| @c @noindent |
| @c run as the owner of @file{/usr/local}. |
| |
| @node Multiple versions, , Uninstalling under macOS, Installing R under macOS |
| @section Multiple versions |
| |
| The installer will remove any previous version@footnote{More precisely, |
| of the Apple package of the same name: this means that installing a |
| package for 3.6.x does not remove an installation for 4.0 or later, and |
| that Intel and ARM versions can be installed together, apart from |
| @code{org.R-project.R.GUI.pkg}.} of the @R{} framework which it finds |
| installed. This can be avoided by using @command{pkgutil --forget} (see |
| the previous section). However, note that different versions are |
| installed under @file{/Library/Frameworks/R.framework/Versions} as |
| @file{4.2} (or @file{4.2-arm64}), @file{4.1} and so on, so it is not |
| possible to have different @samp{4.x.y} versions installed for the same |
| @samp{x} and CPU type. |
| |
| @Rapp{} will always run the `current' version, that is the last |
| installed version. |
| @c A small utility, @command{Rswitch.app} (available at |
| @c @url{https://mac.R-project.org/#other}: it is 32-bit so not usable on |
| @c Catalina), can be used to change the `current' version. This is of |
| @c limited use as @Rapp{} is compiled against a particular version of @R{} |
| @c and will likely crash if switched to an earlier version. This may allow |
| @c you to install a development version of @R{} (de-selecting @Rapp{}) and |
| @c then switch back to the release version. |
| |
| |
| @node Running R, Add-on packages, Installing R under macOS, Top |
| @chapter Running R |
| |
| How to start @R{} and what command-line options are available is discussed |
| in @ref{Invoking R, , Invoking R, R-intro, An Introduction to R}. |
| |
| You should ensure that the shell has set adequate resource limits: @R{} |
| expects a stack size of at least 8MB and to be able to open at least 256 |
| file descriptors. (Any modern OS should have default limits at least as |
| large as these, but apparently NetBSD may not. Use the shell command |
| @command{ulimit} (@command{sh}/@command{bash}) or @command{limit} |
| (@command{csh}/@command{tcsh}) to check.) For some |
| compilers@footnote{Including GCC 9 on Linux.} and packages a larger |
| stack size has been needed: 20-25MB has sufficed to date. |
| |
| @R{} makes use of a number of environment variables, the default values |
| of many of which are set in file @file{@var{R_HOME}/etc/Renviron} (there |
| are none set by default on Windows and hence no such file). These are |
| set at @command{configure} time, and you would not normally want to |
| @enindex R_PAPERSIZE |
| change them -- a possible exception is @env{R_PAPERSIZE} (@pxref{Setting |
| paper size}). The paper size will be deduced from the @samp{LC_PAPER} |
| locale category if it exists and @env{R_PAPERSIZE} is unset, and this |
| will normally produce the right choice from @samp{a4} and @samp{letter} |
| on modern Unix-alikes (but can always be overridden by setting |
| @env{R_PAPERSIZE}). |
| |
| Various environment variables can be set to determine where @R{} creates |
| its per-session temporary directory. The environment variables |
| @enindex TMPDIR |
| @enindex TMP |
| @enindex TEMP |
| @env{TMPDIR}, @env{TMP} and @env{TEMP} are searched in turn and the |
| first one which is set and points to a writable area is used. If none |
| do, the final default is @file{/tmp} on Unix-alikes and the value of |
| @enindex R_USER |
| @env{R_USER} on Windows. The path should be an absolute path not |
| containing spaces (and it is best to avoid non-alphanumeric characters |
| such as @code{+}). |
| |
| Some Unix-alike systems are set up to remove files and directories |
| periodically from @file{/tmp}, for example by a @command{cron} job |
| @enindex TMPDIR |
| running @command{tmpwatch}. Set @env{TMPDIR} to another directory |
| before starting long-running jobs on such a system. |
| |
| Note that @env{TMPDIR} will be used to execute @command{configure} |
| scripts when installing packages, so if @file{/tmp} has been mounted as |
| @samp{noexec}, @env{TMPDIR} needs to be set to a directory from which |
| execution is allowed. |
| |
| @node Add-on packages, Internationalization, Running R, Top |
| @chapter Add-on packages |
| @cindex Packages |
| @cindex Libraries |
| |
| @menu |
| * Default packages:: |
| * Managing libraries:: |
| * Installing packages:: |
| * Updating packages:: |
| * Removing packages:: |
| * Setting up a package repository:: |
| * Checking installed source packages:: |
| @end menu |
| |
| It is helpful to use the correct terminology. A @emph{package} is |
| loaded from a @emph{library} by the function @code{library()}. Thus a |
| library is a directory containing installed packages; the main library |
| is @file{@var{R_HOME}/library}, but others can be used, for example by |
| @enindex R_LIBS |
| setting the environment variable @env{R_LIBS} or using the @R{} function |
| @code{.libPaths()}. To avoid any confusion you will often see a library |
| directory referred to as a `library tree'. |
| |
| @node Default packages, Managing libraries, Add-on packages, Add-on packages |
| @section Default packages |
| @cindex Packages, default |
| |
| The set of packages loaded on startup is by default |
| |
| @example |
| > getOption("defaultPackages") |
| [1] "datasets" "utils" "grDevices" "graphics" "stats" "methods" |
| @end example |
| |
| @noindent |
| (plus, of course, @pkg{base}) and this can be changed by setting the |
| option in startup code (e.g.@: in @file{~/.Rprofile}). It is initially |
| @enindex R_DEFAULT_PACKAGES |
| set to the value of the environment variable @env{R_DEFAULT_PACKAGES} if |
| set (as a comma-separated list). Setting @env{R_DEFAULT_PACKAGES=NULL} |
| ensures that only package @pkg{base} is loaded. |
| |
| Changing the set of default packages is normally used to reduce the set |
| for speed when scripting: in particular not using @pkg{methods} will |
| reduce the start-up time by a factor of up to two. But it can also be |
| used to customize @R{}, e.g.@: for class use. @command{Rscript} |
| also checks the environment variable @env{R_SCRIPT_DEFAULT_PACKAGES}; |
| @enindex R_SCRIPT_DEFAULT_PACKAGES |
| if set, this takes precedence over @env{R_DEFAULT_PACKAGES}. |
| |
| |
| @node Managing libraries, Installing packages, Default packages, Add-on packages |
| @section Managing libraries |
| @cindex Libraries, managing |
| |
| @R{} packages are installed into @emph{libraries}, which are |
| directories in the file system containing a subdirectory for each |
| package installed there. |
| |
| @R{} comes with a single library, @file{@var{R_HOME}/library} which is |
| the value of the @R{} object @samp{.Library} containing the standard and |
| recommended@footnote{unless they were excluded in the build.} packages. |
| Both sites and users can create others and make use of them (or not) in |
| an @R{} session. At the lowest level @samp{.libPaths()} can be used to |
| add paths to the collection of libraries or to report the current |
| collection. |
| |
| @cindex Libraries, site |
| @cindex Site libraries |
| @R{} will automatically make use of a site-specific library |
| @file{@var{R_HOME}/site-library} if this exists (it does not in a |
| vanilla @R{} installation). This location can be overridden by |
| setting@footnote{its binding is locked once the startup files have been |
| read, so users cannot easily change it. See @code{?.libPaths} for how |
| to make use of the new value.} @samp{.Library.site} in |
| @file{@var{R_HOME}/etc/Rprofile.site}, or (not recommended) by setting |
| the |
| @enindex R_LIBS_SITE |
| environment variable @env{R_LIBS_SITE}. |
| |
| @cindex Libraries, user |
| @cindex User libraries |
| @enindex R_LIBS_USER |
| Users can have one or more libraries, normally specified by the |
| environment variable @env{R_LIBS_USER}. This has a default value (to |
| see it, use @samp{Sys.getenv("R_LIBS_USER")} within an @R{} session), |
| but that is only used if the corresponding directory actually exists |
| (which by default it will not). |
| |
| Both @env{R_LIBS_USER} and @env{R_LIBS_SITE} can specify multiple |
| library paths, separated by colons (semicolons on Windows). |
| |
| |
| @node Installing packages, Updating packages, Managing libraries, Add-on packages |
| @section Installing packages |
| @cindex Packages, installing |
| |
| @menu |
| * Windows packages:: |
| * macOS packages:: |
| * Customizing package compilation:: |
| * Multiple sub-architectures:: |
| * Byte-compilation:: |
| * External software:: |
| @end menu |
| |
| |
| Packages may be distributed in source form or compiled binary form. |
| Installing source packages which contain C/C++/Fortran code requires |
| that compilers and related tools be installed. Binary packages are |
| platform-specific and generally need no special tools to install, but |
| see the documentation for your platform for details. |
| |
| Note that you may need to specify implicitly or explicitly the library to |
| which the package is to be installed. This is only an issue if you have |
| more than one library, of course. |
| |
| @c If installing packages on a Unix-alike to be used by other users, ensure |
| @c that the system @code{umask} is set to give sufficient permissions (see |
| @c also @code{Sys.umask} in @R{}). (To a large extent this is unnecessary |
| @c in recent versions of @R{}, which install packages as if @code{umask = 022}.) |
| |
| @enindex TMPDIR |
| Ensure that the environment variable @env{TMPDIR} is either unset (and |
| @file{/tmp} exists and can be written in and executed from) or is the |
| absolute path to a valid temporary directory, not containing spaces. |
| |
| For most users it suffices to call |
| @samp{install.packages(@var{pkgname})} or its GUI equivalent if the |
| intention is to install a @acronym{CRAN} package and internet access is |
| available.@footnote{If a proxy needs to be set, see |
| @command{?download.file}.} On most systems @samp{install.packages()} |
| will allow packages to be selected from a list box (typically with |
| thousands of items). |
| |
| To install packages from source on a Unix-alike use in a terminal |
| |
| @example |
| R CMD INSTALL -l /path/to/library @var{pkg1} @var{pkg2} @dots{} |
| @end example |
| |
| @noindent |
| The part @samp{-l /path/to/library} can be omitted, in which case the |
| first library of a normal @R{} session is used (that shown by |
| @code{.libPaths()[1]}). |
| |
| There are a number of options available: use @code{R CMD INSTALL --help} |
| to see the current list. |
| |
| @findex install.packages |
| Alternatively, packages can be downloaded and installed from within |
| @R{}. First choose your nearest @acronym{CRAN} mirror using |
| @command{chooseCRANmirror()}. Then download and install packages |
| @pkg{pkg1} and @pkg{pkg2} by |
| |
| @example |
| > install.packages(c("pkg1", "pkg2")) |
| @end example |
| |
| @noindent |
| The essential dependencies of the specified packages will also be fetched. |
| Unless the library is specified (argument @code{lib}) the first library |
| in the library search path is used: if this is not writable, @R{} will |
| ask the user (in an interactive session) if the default personal library |
| should be created, and if allowed to will install the packages there. |
| |
| |
| If you want to fetch a package and all those it depends on (in any way) |
| that are not already installed, use e.g. |
| |
| @example |
| > install.packages("Rcmdr", dependencies = TRUE) |
| @end example |
| |
| @code{install.packages} can install a source package from a local |
| @file{.tar.gz} file (or a URL to such a file) by setting argument |
| @code{repos} to @code{NULL}: this will be selected automatically if the |
| name given is a single @file{.tar.gz} file. |
| |
| @code{install.packages} can look in several repositories, specified as a |
| character vector by the argument @code{repos}: these can include a |
| @acronym{CRAN} mirror, Bioconductor, R-forge, rforge.net, |
| local archives, local files, @dots{}). Function |
| @code{setRepositories()} can select amongst those repositories that the |
| @R{} installation is aware of. |
| |
| Something which sometimes puzzles users is that @code{install.packages()} |
| may report that a package which they believe should be available is not |
| found. Some possible reasons: |
| @itemize |
| @item |
| The package, such as @pkg{grid} or @pkg{tcltk}, is part of @R{} |
| itself and not otherwise available. |
| |
| @item |
| The package is not in the available repositories, so check which have been |
| selected by |
| @example |
| getOption("repos") |
| @end example |
| |
| @item |
| The package is available, but not for the current version of @R{} or for |
| the type of OS (Unix/Windows). To retrieve the information on available |
| versions of package @code{@var{pkg}}, use |
| |
| @example |
| av <- available.packages(filters=list()) |
| av[av[, "Package"] == @var{pkg}, ] |
| @end example |
| |
| @noindent |
| in your @R{} session, and look at the @samp{Depends} and @samp{OS_type} |
| fields (there may be more than one matching entry). If the package |
| depends on a version of @R{} later than the one in use, it is possible |
| that an earlier version is available which will work with your version |
| of @R{}: for @acronym{CRAN} look for `Old sources' on the package's |
| @acronym{CRAN} landing page and manually retrieve an appropriate version (of |
| comparable age to your version of @R{}). |
| @end itemize |
| |
| Naive users sometimes forget that as well as installing a package, they |
| have to use @code{library} to make its functionality available. |
| |
| @node Windows packages, macOS packages, Installing packages, Installing packages |
| @subsection Windows |
| |
| What @code{install.packages} does by default is different on Unix-alikes |
| (except macOS) and Windows. On Unix-alikes it consults the list of |
| available @emph{source} packages on @acronym{CRAN} (or other |
| repository/ies), downloads the latest version of the package sources, |
| and installs them (via @code{R CMD INSTALL}). On Windows it looks (by |
| default) first at the list of @emph{binary} versions of packages |
| available for your version of @R{} and downloads the latest versions (if |
| any). If no binary version is available or the source version is newer, |
| it will install the source versions of packages without compiled |
| C/C++/Fortran code, and offer to do so for those with, if @command{make} |
| is available (and this can be tuned by option |
| @code{"install.packages.compile.from.source"}). |
| |
| On Windows @code{install.packages} can also install a binary package |
| from a local @file{zip} file (or the URL of such a file) by setting |
| argument @code{repos} to @code{NULL}. @code{Rgui.exe} has a menu |
| @code{Packages} with a GUI interface to @code{install.packages}, |
| @code{update.packages} and @code{library}. |
| |
| Windows binary packages for @R{} are distributed as a single binary |
| containing either or both architectures (32- and 64-bit). From @R{} 4.2.0, |
| they always contain only the 64-bit architecture. |
| |
| @c A few of the binary packages need other software to be installed on your |
| @c system. |
| @c Packages using Gtk+ (@CRANpkg{Cairo}, @CRANpkg{RGtk2}, |
| @c @CRANpkg{cairoDevice} and those that depend on them) need the @file{bin} |
| @c directory of a bundled distribution of Gtk2 from |
| @c @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+} or |
| @c @uref{http://ftp.gnome.org/pub/gnome/binaries/win64/gtk+} in |
| @c the path: it should work to have both 32- and 64-bit Gtk+ @file{bin} |
| @c directories in the path on a 64-bit version of @R{}. |
| |
| @command{R CMD INSTALL} works in Windows to install source packages. No |
| additional tools are needed if the package does not contain compiled |
| code, and @code{install.packages(type="source")} will work for such |
| packages. Those with compiled code need the tools (see @ref{The Windows |
| toolset}). The tools are found automatically by @R{} when installed by |
| the toolset installer. See |
| @uref{https://cran.r-project.org/bin/windows/base/howto-R-devel.html,Building |
| R and packages} for more details. |
| |
| Occasional permission problems after unpacking source packages have been |
| seen on some systems: these have been circumvented by setting the |
| environment variable @env{R_INSTALL_TAR} to @samp{tar.exe}. |
| @enindex R_INSTALL_TAR |
| |
| If you have only a source package that is known to work with current |
| @R{} and just want a binary Windows build of it, you could make use of |
| the building service offered at |
| @uref{https://win-builder.r-project.org/}. |
| |
| For almost all packages @command{R CMD INSTALL} will attempt to install |
| both 32- and 64-bit builds of a package if run from a 32/64-bit install |
| of @R{} (only 64-bit builds and installs are supported since @R{} 4.2.0). |
| It will report success if the installation of the architecture |
| of the running @command{R} succeeded, whether or not the other |
| architecture was successfully installed. The exceptions are packages |
| with a non-empty @file{configure.win} script or which make use of |
| @file{src/Makefile.win}. If @file{configure.win} does something |
| appropriate to both architectures use@footnote{for a small number of |
| @acronym{CRAN} packages where this is known to be safe and is needed by |
| the autobuilder this is the default. Look at the source of |
| @file{tools:::.install_packages} for the list. It can also be specified |
| in the package's @file{DESCRIPTION} file.} option |
| @option{--force-biarch}: otherwise @command{R CMD INSTALL |
| --merge-multiarch} can be applied to a source tarball to merge separate |
| 32- and 64-bit installs. (This can only be applied to a tarball, and |
| will only succeed if both installs succeed.) |
| |
| If you have a package without compiled code and no Windows-specific |
| help, you can zip up an installation on another OS and install from that |
| zip file on Windows. However, such a package can be installed from the |
| sources on Windows without any additional tools. |
| |
| |
| @node macOS packages, Customizing package compilation, Windows packages, Installing packages |
| @subsection macOS |
| |
| On macOS @code{install.packages} works as it does on other Unix-alike |
| systems, but there is an additional type @code{mac.binary} (available |
| for the @acronym{CRAN} distribution but not when compiling @R{} from |
| source) which can be passed to @code{install.packages} in order to |
| download and install binary packages from a suitable repository. These |
| binary package files for macOS have the extension @samp{.tgz}. The |
| @Rapp{} GUI provides menus for installation of either binary or source |
| packages, from @acronym{CRAN}, other repositories or local files. |
| |
| On @R{} builds using binary packages, the default is type @code{both}: |
| this looks first at the list of binary packages available for your |
| version of @R{} and installs the latest versions (if any). If no binary |
| version is available or the source version is newer, it will install the |
| source versions of packages without compiled C/C++/Fortran code and offer |
| to do so for those with, if @command{make} is available. |
| |
| Note that most binary packages which include compiled code are tied to a |
| particular series (e.g.@: @R{} 4.1.x or 4.2.x) of @R{}. |
| |
| Installing source packages which do not contain compiled code should |
| work with no additional tools. For others you will need the |
| `Command Line Tools' for @command{Xcode} and compilers which match those |
| used to build @R{}: see @ref{macOS}. |
| |
| Package @CRANpkg{rJava} and those which depend on it need a Java runtime |
| installed and several packages need X11 installed, including those using |
| Tk. See @ref{macOS} and @ref{Java (macOS)}. Package @CRANpkg{rjags} |
| needs a build of JAGS installed under @file{/usr/local}, such as those |
| at |
| @uref{https://sourceforge.net/projects/mcmc-jags/files/JAGS/4.x/Mac%20OS%20X/}. |
| |
| Tcl/Tk extension @code{BWidget} used to be |
| distributed with @R{} but no longer is; @code{Tktable} has been |
| distributed with most versions of @R{} (but not 4.0.0 and not |
| @cputype{arm64} builds of 4.1.0 or 4.1.1). |
| |
| A few of the binary packages need other software to be installed on your |
| system. In particular packages using Gtk+ (@CRANpkg{RGtk2}, |
| @CRANpkg{cairoDevice} and those that depend on them) need the GTK |
| framework installed from @uref{https://mac.R-project.org/libs/}: the |
| appropriate version at the time of writing was |
| @uref{https://mac.R-project.org/libs/GTK_2.24.17-X11.pkg}. |
| |
| The same instructions apply when installing binary packages into the |
| @acronym{CRAN} distribution of @R{} running on an @cputype{arm64} (aka |
| `Apple Silicon' aka `M1') Mac. |
| |
| The default compilers specified are shown in file |
| @file{/Library/Frameworks/@/R.framework/@/Resources/etc/Makeconf}. At |
| the time of writing those settings assumed that the C, Fortran and C++ |
| compilers were on the path, using @command{gfortran} 8.2.0 (see |
| @ref{macOS}). The settings can be changed, either by editing that file |
| or in a file such as @file{~/.R/Makevars} (see the next section). |
| Entries which may need to be changed include @samp{CC}, @samp{CXX}, |
| @samp{FC}, @samp{FLIBS} and the corresponding flags, and perhaps |
| @samp{CXXCPP}, @samp{DYLIB_LD}, @samp{MAIN_LD}, @samp{SHLIB_CXXLD} and |
| @samp{SHLIB_LD}, as well as the @samp{CXX11}, @samp{CXX14}, |
| @samp{CXX17} and @samp{CXX20} variants |
| |
| So for example on Mojave or later you could select a specific |
| non-Apple build of @command{clang} for both C and C++ with extensive |
| checking by having in @file{~/.R/Makevars} |
| @example |
| CC = /usr/local/clang/bin/clang -isysroot |
| /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk |
| CXX = /usr/local/clang/bin/clang++ -isysroot |
| /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk |
| CXX11 = $CXX |
| CXX14 = $CXX |
| CXX17 = $CXX |
| CXX20 = $CXX |
| CFLAGS = -g -O2 -Wall -pedantic -Wconversion -Wno-sign-conversion |
| CXXFLAGS = -g -O2 -Wall -pedantic -Wconversion -Wno-sign-conversion |
| CXX11FLAGS = $CXXFLAGS |
| CXX14FLAGS = $CXXFLAGS |
| CXX17FLAGS = $CXXFLAGS |
| CXX20FLAGS = $CXXFLAGS |
| @end example |
| @noindent |
| (long lines split for the manual only) and @command{gfortran} by |
| @example |
| FC = /usr/local/gfortran/bin/gfortran |
| FLIBS = -L/usr/local/gfortran/lib/gcc/x86_64-apple-darwin18/8.2.0 |
| -L/usr/local/gfortran/lib -lgfortran -lquadmath -lm |
| @end example |
| @noindent |
| (with lines broken here for legibility). If that @command{clang} build |
| supports OpenMP, you can add |
| @example |
| SHLIB_OPENMP_CFLAGS = -fopenmp |
| SHLIB_OPENMP_CXXFLAGS = -fopenmp |
| @end example |
| @noindent |
| to compile OpenMP-using packages. It will also be necessary to arrange |
| for the @code{libomp.dylib} library to be found at both install time and run |
| time, for example by copying/linking it somewhere that is searched such |
| as @file{/usr/local/lib}. |
| |
| @c Seems unneeded as running from the R executable forces x86_64 compiles. |
| @c |
| @c Installing a source package containing C/C++ code into @acronym{CRAN} |
| @c distribution of @R{} running on an @cputype{arm64} Mac requires telling |
| @c the compiler(s) to generate Intel code. For example, for Command Line |
| @c Tools / Xcode 12.x one could have in @file{~/.R/Makevars} |
| |
| @c @example |
| @c CC = clang -target x86_64-apple-macos10.15 |
| @c CXX = clang++ -target x86_64-apple-macos10.15 |
| @c @end example |
| |
| @c @noindent |
| @c (Using @code{-arch x86_64} also works.) |
| |
| Apple includes many Open Source libraries in macOS but increasingly |
| without the corresponding headers (not even in Xcode nor the Command |
| Line Tools): they are often rather old versions. If installing packages |
| from source using them it is usually easiest to install a |
| statically-linked up-to-date copy of the Open Source package from its |
| sources or from @uref{https://mac.r-project.org/bin/darwin17/x86_64/}. |
| But sometimes it is desirable/necessary to use Apple's dynamically |
| linked library, in which case appropriate headers could be extracted |
| from the sources@footnote{Note that capitalization and versioning may |
| differ from the Open Source project.} available @emph{via} |
| @uref{https://opensource.apple.com} -- this has been used for |
| @code{OpenSSL}@footnote{no longer a system library in macOS 11.} and |
| @code{iodbc}. |
| |
| Those using Command Line Tools / Xcode 12 or later (as released for |
| macOS 11 `Big Sur') probably want to arrange that the flag |
| |
| @example |
| -Wno-implicit-function-declaration |
| @end example |
| |
| @noindent |
| is part of @code{CFLAGS}. Apple has changed the default to make |
| implicit declarations a compilation error (something seen in no other |
| compiler) and understandably authors of packages and external software |
| have been unaware that this might be done --- most issues seen were in |
| @command{configure} scripts. |
| |
| Some care may be needed with selecting compilers when installing external |
| software for use with packages. The `system' compilers as used when |
| building @R{} are @command{clang} and @command{clang++}, but the Apple |
| toolchain also provides compilers called @command{gcc} and @command{g++} |
| which despite their names are based on LLVM and @code{libc++} like the |
| system ones and which behave in almost the same way as the system ones. |
| Most Open Source software has a @command{configure} script developed |
| using GNU @command{autoconf} and hence will select @command{gcc} and |
| @command{g++} as the default compilers: this usually works fine. For |
| consistency one can use |
| |
| @example |
| ./configure CC=clang CFLAGS=-O2 CXX=clang++ CXXFLAGS=-O2 |
| @end example |
| |
| @noindent |
| (avoiding @command{autoconf}'s default @option{-g}). Be careful if you |
| put the @file{/usr/local/gfortran/bin} directory on your path as that |
| contains (real) @command{gcc} and @command{g++} which may be found |
| rather the Apple-provided commands, and may not be able to find the |
| headers and libraries@footnote{From Big Sur those libraries are not |
| publicly visible: rather the system compilers link to `text-based |
| definition' (@file{.tbd}) files.} of the SDK. |
| |
| For @cputype{arm64}, not all configure scripts have been updated to |
| recognize the platform and so might need the flag |
| @option{--build=aarch64-apple-darwin20.1.0}. Also, be aware that |
| running the compilers from a @cputype{x86_64} application switches them |
| to generating code for that CPU: this applies to a Terminal, a shell, |
| older @command{cmake} or (non-system) @command{make}, and from |
| @command{R CMD INSTALL} or @code{install.packages()}. One can use |
| |
| @example |
| ./configure CC="clang -arch arm64" CFLAGS=-O2 CXX="clang++ -arch arm64" CXXFLAGS=-O2 |
| @end example |
| |
| @noindent |
| to force @cputype{arm64} code. |
| |
| |
| @node Customizing package compilation, Multiple sub-architectures, macOS packages, Installing packages |
| @subsection Customizing package compilation |
| |
| The @R{} system and package-specific compilation flags can be overridden |
| or added to by setting the appropriate Make variables in the personal |
| file @file{@var{HOME}/.R/Makevars-@var{R_PLATFORM}} (but |
| @file{@var{HOME}/.R/Makevars.win} or @file{@var{HOME}/.R/Makevars.win64} |
| on Windows), or if that does not exist, @file{@var{HOME}/.R/Makevars}, |
| where @samp{R_PLATFORM} is the platform for which @R{} was built, as |
| available in the @code{platform} component of the @R{} variable |
| @code{R.version}. The full path to an alternative personal |
| file@footnote{using a path containing spaces is likely to cause |
| problems} can be specified @emph{via} the environment variable |
| @env{R_MAKEVARS_USER}. |
| |
| Package developers are encouraged to use this mechanism to enable a |
| reasonable amount of diagnostic messaging (``warnings'') when compiling, |
| such as e.g.@: @option{-Wall -pedantic} for tools from GCC, the GNU |
| Compiler Collection, or for @command{clang}. |
| |
| Note that this mechanism can also be used when it necessary to change |
| the optimization level whilst installing a particular package. For |
| example |
| |
| @example |
| ## @r{for C code} |
| CFLAGS = -g -O -mtune=native |
| ## @r{for C++ code} |
| CXXFLAGS = -g -O -mtune=native |
| ## @r{for fixed-form Fortran code} |
| FFLAGS = -g -O -mtune=native |
| @end example |
| |
| Another use is to override the settings in a binary installation of R. |
| For example, to use a different Fortran compiler on macOS |
| |
| @example |
| FC = /usr/local/gfortran/bin/gfortran |
| FLIBS = -L/usr/local/gfortran/lib/gcc/x86_64-apple-darwin16/6.3.0 |
| -L/usr/local/gfortran/lib -lgfortran -lquadmath -lm |
| @end example |
| |
| @noindent |
| (line split for legibility here). |
| |
| There is also provision for a site-wide @file{Makevars.site} file under |
| @file{@var{R_HOME}/etc} (in a sub-architecture-specific directory if |
| appropriate). This is read immediately after @file{Makeconf}, and the |
| path to an alternative file can be specified by environment variable |
| @env{R_MAKEVARS_SITE}. |
| |
| Note that these mechanisms do not work with packages which fail to pass |
| settings down to sub-makes, perhaps reading @file{etc/Makeconf} in |
| makefiles in subdirectories. Fortunately such packages are unusual. |
| |
| @node Multiple sub-architectures, Byte-compilation, Customizing package compilation, Installing packages |
| @subsection Multiple sub-architectures |
| |
| When installing packages from their sources, there are some extra |
| considerations on installations which use sub-architectures. These are |
| commonly used on Windows but can in principle be used on other |
| platforms. |
| |
| When a source package is installed by a build of @R{} which supports |
| multiple sub-architectures, the normal installation process installs the |
| packages for all sub-architectures. The exceptions are |
| |
| @table @emph |
| @item Unix-alikes |
| |
| where there is an @file{configure} script, or a file @file{src/Makefile}. |
| |
| @item Windows |
| |
| where there is a non-empty @file{configure.win} script, or a file |
| @file{src/Makefile.win} (with some exceptions where the package is known |
| to have an architecture-independent @file{configure.win}, or if |
| @option{--force-biarch} or field @samp{Biarch} in the @file{DESCRIPTION} |
| file is used to assert so). |
| |
| @end table |
| |
| @noindent |
| In those cases only the current architecture is installed. Further |
| sub-architectures can be installed by |
| |
| @example |
| R CMD INSTALL --libs-only @var{pkg} |
| @end example |
| |
| @noindent |
| using the path to @command{R} or @command{R --arch} to select the |
| additional sub-architecture. There is also @command{R CMD INSTALL |
| --merge-multiarch} to build and merge the two architectures, starting |
| with a source tarball. |
| |
| @node Byte-compilation, External software, Multiple sub-architectures, Installing packages |
| @subsection Byte-compilation |
| |
| As from @R{} 3.6.0, all packages are by default byte-compiled. |
| |
| Byte-compilation can be controlled on a per-package basis by the |
| @samp{ByteCompile} field in the @file{DESCRIPTION} file. |
| |
| @node External software, , Byte-compilation, Installing packages |
| @subsection External software |
| |
| Some @R{} packages contain compiled code which links to external |
| software libraries. Unless the external library is statically linked |
| (which is done as much as possible for binary packages on Windows and |
| macOS), the libraries have to be found when the package is loaded and |
| not just when it is installed. How this should be done depends on the |
| OS (and in some cases the version). |
| |
| For Unix-alikes except macOS the primary mechanism is the @code{ld.so} |
| cache controlled by @command{ldconfig}: external dynamic libraries |
| recorded in that cache will be found. Standard library locations will |
| be covered by the cache, and well-designed software will add its |
| locations (as for example @pkg{openmpi} does on Fedora). The secondary |
| mechanism is to consult the environment variable @env{LD_LIBRARY_PATH}. |
| The @R{} script controls that variable, and sets it to the concatenation |
| of @env{R_LD_LIBRARY_PATH}, @env{R_JAVA_LD_LIBRARY_PATH} and the |
| environment value of @env{LD_LIBRARY_PATH}. The first two have defaults |
| which are normally set when @R{} is installed (but can be overridden in |
| the environment) so @env{LD_LIBRARY_PATH} is the best choice for a user |
| to set. |
| |
| On macOS the primary mechanism is to embed the absolute path to |
| dependent dynamic libraries into an object when it is compiled. Few |
| @R{} packages arrange to do so, but it can be edited@footnote{They need |
| to have been created using @option{-headerpad_max_install_names}, which |
| is the default for an @R{} package.} @emph{via} |
| @command{install_name_tool} --- that only deals with direct dependencies |
| and those would also need to be compiled to include the absolute paths |
| of their dependencies. If the choice of absolute path is to be deferred |
| to load time, how they are resolved is described in @command{man dyld}: |
| the role of @env{LD_LIBRARY_PATH} is replaced on macOS by |
| @env{DYLD_LIBRARY_PATH} and @env{DYLD_FALLBACK_LIBRARY_PATH}. Running |
| @command{R CMD otool -L} on the package shared object will show where |
| (if anywhere) its dependencies are |
| resolved. @env{DYLD_FALLBACK_LIBRARY_PATH} is preferred (and it is that |
| which is manipulated by the @R{} script), but as from 10.11 (`El |
| Capitan') the default behaviour had been changed for security reasons to |
| discard these environment variables when invoking a shell script (and |
| @file{R} is a shell script). That makes the only portable option to set |
| @env{R_LD_LIBRARY_PATH} in the environment, something like |
| |
| @example |
| export R_LD_LIBRARY_PATH="`R RHOME`/lib:/opt/local/lib" |
| @end example |
| |
| The precise rules for where Windows looks for DLLs are complex and |
| depend on the version of Windows. But for present purposes the main |
| solution is to put the directories containing the DLLs the package |
| links to (and any those DLLs link to) on the @env{PATH}. 64-bit |
| versions of Windows will ignore 32-bit DLLs from 64-bit @R{} and |
| @emph{vice versa}. |
| |
| The danger with any of the methods which involve setting environment |
| variables is of inadvertently masking a system library. This is less |
| for @env{DYLD_FALLBACK_LIBRARY_PATH} and for @emph{appending} to |
| @env{PATH} on Windows (as it should already contain the system library |
| paths). |
| |
| @node Updating packages, Removing packages, Installing packages, Add-on packages |
| @section Updating packages |
| @findex update.packages |
| @cindex Packages, updating |
| |
| The command @code{update.packages()} is the simplest way to ensure that |
| all the packages on your system are up to date. It downloads the list |
| of available packages and their current versions, compares it with those |
| installed and offers to fetch and install any that have later versions |
| on the repositories. |
| |
| An alternative interface to keeping packages up-to-date is provided by |
| the command @code{packageStatus()}, which returns an object with |
| information on all installed packages and packages available at multiple |
| repositories. The @code{print} and @code{summary} methods give an |
| overview of installed and available packages, the @code{upgrade} method |
| offers to fetch and install the latest versions of outdated packages. |
| |
| One sometimes-useful additional piece of information that |
| @code{packageStatus()} returns is the status of a package, as |
| @code{"ok"}, @code{"upgrade"} or @code{"unavailable"} (in the currently |
| selected repositories). For example |
| |
| @example |
| > inst <- packageStatus()$inst |
| > inst[inst$Status != "ok", c("Package", "Version", "Status")] |
| Package Version Status |
| Biobase Biobase 2.8.0 unavailable |
| RCurl RCurl 1.4-2 upgrade |
| Rgraphviz Rgraphviz 1.26.0 unavailable |
| rgdal rgdal 0.6-27 upgrade |
| @end example |
| |
| |
| @node Removing packages, Setting up a package repository, Updating packages, Add-on packages |
| @section Removing packages |
| @findex remove.packages |
| @cindex Packages, removing |
| |
| Packages can be removed in a number of ways. From a command prompt they |
| can be removed by |
| |
| @example |
| R CMD REMOVE -l /path/to/library @var{pkg1} @var{pkg2} @dots{} |
| @end example |
| |
| From a running @R{} process they can be removed by |
| |
| @example |
| > remove.packages(c("pkg1", "pkg2"), |
| lib = file.path("path", "to", "library")) |
| @end example |
| |
| Finally, one can just remove the package directory from the library. |
| |
| |
| @node Setting up a package repository, Checking installed source packages, Removing packages, Add-on packages |
| @section Setting up a package repository |
| @cindex Repositories |
| |
| Utilities such as @code{install.packages} can be pointed at any |
| @acronym{CRAN}-style repository, and @R{} users may want to set up their |
| own. The `base' of a repository is a URL such as |
| @uref{https://www.stats.ox.ac.uk/pub/RWin/}: this must be an URL scheme |
| that @code{download.packages} supports (which also includes |
| @samp{https://}, @samp{ftp://} and @samp{file://}). Under that base URL |
| there should be directory trees for one or more of the following types |
| of package distributions: |
| |
| @itemize |
| @item |
| @code{"source"}: located at @file{src/contrib} and containing |
| @file{.tar.gz} files. Other forms of compression can be used, e.g.@: |
| @file{.tar.bz2} or @file{.tar.xz} files. Complete repositories contain |
| the sources corresponding to any binary packages, and in any case it is |
| wise to have a @file{src/contrib} area with a possibly empty |
| @file{PACKAGES} file. |
| |
| @item |
| @code{"win.binary"}: located at @file{bin/windows/contrib/@var{x.y}} for |
| @R{} versions @var{x.y.z} and containing @file{.zip} files for Windows. |
| |
| @item |
| @code{"mac.binary"}: located at |
| @file{bin/macosx/contrib/@var{4.y}} for the @acronym{CRAN} builds for |
| macOS for @R{} versions @var{4.y.z}, containing |
| @file{.tgz} files. |
| |
| @item |
| @code{"mac.binary.el-capitan"}: located at |
| @file{bin/macosx/el-capitan/contrib/@var{3.y}} for the @acronym{CRAN} |
| builds for @R{} versions @var{3.y.z}, containing @file{.tgz} files. |
| @end itemize |
| |
| Each terminal directory must also contain a @file{PACKAGES} file. This |
| can be a concatenation of the @file{DESCRIPTION} files of the packages |
| separated by blank lines, but only a few of the fields are needed. The |
| simplest way to set up such a file is to use function |
| @code{write_PACKAGES} in the @pkg{tools} package, and its help explains |
| which fields are needed. Optionally there can also be |
| @file{PACKAGES.rds} and @file{PACKAGES.gz} files, downloaded in |
| preference to @file{PACKAGES}. (If you have a mis-configured server |
| that does not report correctly non-existent files you may need these |
| files.) |
| |
| To add your repository to the list offered by @code{setRepositories()}, |
| see the help file for that function. |
| |
| Incomplete repositories are better specified @emph{via} a |
| @code{contriburl} argument than @emph{via} being set as a repository. |
| |
| A repository can contain subdirectories, when the descriptions in the |
| @file{PACKAGES} file of packages in subdirectories must include a line |
| of the form |
| |
| @example |
| Path: @var{path/to/subdirectory} |
| @end example |
| |
| @noindent |
| ---once again @code{write_PACKAGES} is the simplest way to set this up. |
| |
| @node Checking installed source packages, , Setting up a package repository, Add-on packages |
| @section Checking installed source packages |
| |
| It can be convenient to run @command{R CMD check} on an installed |
| package, particularly on a platform which uses sub-architectures. The |
| outline of how to do this is, with the source package in directory |
| @file{@var{pkg}} (or a tarball filename): |
| |
| @example |
| R CMD INSTALL -l @var{libdir} @var{pkg} > @var{pkg}.log 2>&1 |
| R CMD check -l @var{libdir} --install=check:@var{pkg}.log @var{pkg} |
| @end example |
| |
| @noindent |
| Where sub-architectures are in use the @command{R CMD check} line can be |
| repeated with additional architectures by |
| |
| @example |
| R --arch @var{arch} CMD check -l @var{libdir} --extra-arch --install=check:@var{pkg}.log @var{pkg} |
| @end example |
| |
| @noindent |
| where @option{--extra-arch} selects only those checks which depend on |
| the installed code and not those which analyse the sources. (If |
| multiple sub-architectures fail only because they need different |
| settings, e.g.@: environment variables, @option{--no-multiarch} may need |
| to be added to the @code{INSTALL} lines.) On Unix-alikes the |
| architecture to run is selected by @option{--arch}: this can also be |
| used on Windows with @file{@var{R_HOME}/bin/R.exe}, but it is more usual |
| to select the path to the @command{Rcmd.exe} of the desired |
| architecture. |
| |
| So on Windows to install, check and package for distribution a source |
| package from a tarball which has been tested on another platform one |
| might use |
| |
| @example |
| .../bin/i386/Rcmd INSTALL -l @var{libdir} @var{tarball} --build > @var{pkg}.log 2>&1 |
| .../bin/i386/Rcmd check -l @var{libdir} --extra-arch --install=check:@var{pkg}.log @var{pkg} |
| .../bin/x64/Rcmd check -l @var{libdir} --extra-arch --install=check:@var{pkg}.log @var{pkg} |
| @end example |
| |
| @noindent |
| where one might want to run the second and third lines in a different |
| shell with different settings for environment variables and the path (to |
| find external software, notably for Gtk+). |
| |
| @command{R CMD INSTALL} can do a @code{i386} install and then add the |
| @code{x64} DLL from a single command by |
| |
| @example |
| R CMD INSTALL --merge-multiarch -l @var{libdir} @var{tarball} |
| @end example |
| |
| @noindent |
| and @option{--build} can be added to zip up the installation. |
| |
| @node Internationalization, Choosing between 32- and 64-bit builds, Add-on packages, Top |
| @chapter Internationalization and Localization |
| @cindex Internationalization |
| @cindex Localization |
| |
| @emph{Internationalization} refers to the process of enabling support |
| for many human languages, and @emph{localization} to adapting to a |
| specific country and language. |
| |
| Current builds of @R{} support all the character sets that the |
| underlying OS can handle. These are interpreted according to the |
| @cindex Locale |
| current @code{locale}, a sufficiently complicated topic to merit a |
| separate section. Note though that @R{} has no built-in support for |
| right-to-left languages and bidirectional output, relying on the OS |
| services. For example, how character vectors in UTF-8 containing both |
| English digits and Hebrew characters are printed is OS-dependent (and |
| perhaps locale-dependent). |
| |
| The other aspect of the internationalization is support for the |
| translation of messages. This is enabled in almost all builds of @R{}. |
| |
| @menu |
| * Locales:: |
| * Localization of messages:: |
| @end menu |
| |
| @node Locales, Localization of messages, Internationalization, Internationalization |
| @section Locales |
| @cindex Locale |
| |
| A @emph{locale} is a description of the local environment of the user, |
| including the preferred language, the encoding of characters, the |
| currency used and its conventions, and so on. Aspects of the locale are |
| accessed by the @R{} functions @code{Sys.getlocale} and |
| @code{Sys.localeconv}. |
| |
| The system of naming locales is OS-specific. There is quite wide |
| agreement on schemes, but not on the details of their implementation. A |
| locale needs to specify |
| @itemize |
| @item |
| A human language. These are generally specified by a lower-case |
| two-character abbreviation following ISO 639 (see e.g.@: |
| @uref{https://en.wikipedia.org/wiki/ISO_639-1}). |
| |
| @item |
| A `territory', used mainly to specify the currency. These are generally |
| specified by an upper-case two-character abbreviation following ISO 3166 |
| (see e.g.@: @uref{https://en.wikipedia.org/wiki/ISO_3166}). |
| |
| @item |
| A charset encoding, which determines both how a byte stream should be |
| divided into characters, and which characters the subsequences of bytes |
| represent. Sometimes the combination of language and territory is used |
| to specify the encoding, for example to distinguish between traditional |
| and simplified Chinese. |
| |
| @item |
| Optionally, a modifier, for example to indicate that Austria is to be |
| considered pre- or post-Euro. The modifier is also used to indicate the |
| script (@code{@@latin}, @code{@@cyrillic} for Serbian, @code{@@iqtelif}) |
| or language dialect (e.g.@: @code{@@saaho}, a dialect of Afar, and |
| @code{@@bokmal} and @code{@@nynorsk}, dialects of Norwegian regarded by |
| some OSes as separate languages, @code{no} and @code{nn}). |
| @end itemize |
| |
| @R{} is principally concerned with the first (for translations) and |
| third. Note that the charset may be deducible from the language, as |
| some OSes offer only one charset per language. |
| |
| @menu |
| * Locales under Unix-alikes:: |
| * Locales under Windows:: |
| * Locales under macOS:: |
| @end menu |
| |
| @node Locales under Unix-alikes, Locales under Windows, Locales, Locales |
| @subsection Locales under Unix-alikes |
| |
| Modern Linux uses the XPG@footnote{`X/Open Portability Guide', which has |
| had several versions.} locale specifications which have the form |
| @samp{en_GB}, @samp{en_GB.UTF-8}, @samp{aa_ER.UTF-8@@saaho}, |
| @samp{de_AT.iso885915@@euro}, the components being in the order listed |
| above. (See @command{man locale} and @command{locale -a} for more |
| details.) Similar schemes are used by most Unix-alikes: some (including |
| some distributions of Linux) use @samp{.utf8} rather than @samp{.UTF-8}. |
| |
| Note that whereas UTF-8 locales are nowadays almost universally used, |
| locales such as @samp{en_GB} use 8-bit encodings for backwards |
| compatibility. |
| |
| @node Locales under Windows, Locales under macOS, Locales under Unix-alikes, Locales |
| @subsection Locales under Windows |
| |
| Windows also uses locales, but specified in a rather less concise way. |
| Most users will encounter locales only via drop-down menus, but more |
| information and lists can be found by searching for @samp{Windows |
| language country strings}). |
| |
| It offers only one encoding per language. |
| |
| Some care is needed with Windows' locale names. For example, |
| @code{chinese} is Traditional Chinese and not Simplified Chinese as used |
| in most of the Chinese-speaking world. |
| |
| @node Locales under macOS, , Locales under Windows, Locales |
| @subsection Locales under macOS |
| |
| macOS supports locales in its own particular way, but the @R{} GUI tries to |
| make this easier for users. See |
| @uref{https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPInternational/} |
| for how users can set their locales. As with Windows, end users will |
| generally only see lists of languages/territories. Users of @R{} in a |
| terminal may need to set the locale to something like @samp{en_GB.UTF-8} |
| if it defaults to @samp{C} (as it sometimes does when logging in |
| remotely and for batch jobs: note whether @command{Terminal} sets the |
| @env{LANG} environment variable is an (advanced) preference, but does so |
| by default). |
| |
| Internally macOS uses a form similar to Linux: the main difference from |
| other Unix-alikes is that where a character set is not specified it is |
| assumed to be @code{UTF-8}. |
| |
| |
| @node Localization of messages, , Locales, Internationalization |
| @section Localization of messages |
| |
| The preferred language for messages is by default taken from the locale. |
| This can be overridden first by the setting of the environment variable |
| @enindex LANGUAGE |
| @enindex LC_ALL |
| @enindex LC_MESSAGES |
| @enindex LANG |
| @env{LANGUAGE} and then@footnote{On some systems setting |
| @env{LC_ALL} or @env{LC_MESSAGES} to @samp{C} disables @env{LANGUAGE}.} |
| by the environment variables @env{LC_ALL}, @env{LC_MESSAGES} and |
| @env{LANG}. (The last three are normally used to set the locale and so |
| should not be needed, but the first is only used to select the language |
| for messages.) The code tries hard to map locales to languages, but on |
| some systems (notably Windows) the locale names needed for the |
| environment variable @env{LC_ALL} do not all correspond to XPG language |
| names and so @env{LANGUAGE} may need to be set. (One example is |
| @samp{LC_ALL=es} on Windows which sets the locale to Estonian and the |
| language to Spanish.) |
| |
| It is usually possible to change the language once @R{} is running |
| @emph{via} (not Windows) @code{Sys.setlocale("LC_MESSAGES", |
| "new_locale")}, or by setting an environment variable such as |
| @env{LANGUAGE}, @emph{provided}@footnote{If you try changing from French |
| to Russian except in a UTF-8 locale, you may find messages change to |
| English.} the language you are changing to can be output in the current |
| character set. But this is OS-specific, and has been known to stop |
| working on an OS upgrade. Note that translated messages may be cached, |
| so attempting to change the language of an error that has already been |
| output in another language may not work. |
| |
| Messages are divided into @emph{domains}, and translations may be |
| available for some or all messages in a domain. @R{} makes use of the |
| following domains. |
| |
| @itemize |
| @item |
| Domain @code{R} for the C-level error and warning messages from the @R{} |
| interpreter. |
| |
| @item |
| Domain @code{R-@var{pkg}} for the @R{} @code{stop}, @code{warning} and |
| @code{message} messages in each package, including @code{R-base} for the |
| @pkg{base} package. |
| |
| @item |
| Domain @code{@var{pkg}} for the C-level messages in each package. |
| |
| @item |
| Domain @code{RGui} for the menus etc of the @R{} for Windows GUI front-end. |
| |
| @end itemize |
| |
| Dividing up the messages in this way allows @R{} to be extensible: as |
| packages are loaded, their message translation catalogues can be loaded |
| too. |
| |
| @R{} can be built without support for translations, but it is enabled by |
| default. |
| |
| R-level and C-level domains are subtly different, for example in the way |
| strings are canonicalized before being passed for translation. |
| |
| Translations are looked for by domain according to the currently |
| specified language, as specifically as possible, so for example an |
| Austrian (@samp{de_AT}) translation catalogue will be used in preference |
| to a generic German one (@samp{de}) for an Austrian user. However, if a |
| specific translation catalogue exists but does not contain a |
| translation, the less specific catalogues are consulted. For example, |
| @R{} has catalogues for @samp{en_GB} that translate the Americanisms |
| (e.g., @samp{gray}) in the standard messages into English.@footnote{the |
| language written in England: some people living in the USA appropriate |
| this name for their language.} Two other examples: there are catalogues |
| for @samp{es}, which is Spanish as written in Spain and these will by |
| default also be used in Spanish-speaking Latin American countries, and |
| also for @samp{pt_BR}, which are used for Brazilian locales but not for |
| locales specifying Portugal. |
| |
| Translations in the right language but the wrong charset are made use of |
| @enindex LANGUAGE |
| by on-the-fly re-encoding. The @env{LANGUAGE} variable (only) can be a |
| colon-separated list, for example @samp{se:de}, giving a set of |
| languages in decreasing order of preference. One special value is |
| @samp{en@@quot}, which can be used in a UTF-8 locale to have American |
| error messages with pairs of single quotes translated to Unicode directional |
| quotes. |
| |
| If no suitable translation catalogue is found or a particular message is |
| not translated in any suitable catalogue, `English'@footnote{with |
| Americanisms.} is used. |
| |
| See @uref{https://developer.r-project.org/Translations30.html} for how to |
| prepare and install translation catalogues. |
| |
| @node Choosing between 32- and 64-bit builds, The standalone Rmath library, Internationalization, Top |
| @chapter Choosing between 32- and 64-bit builds |
| |
| Almost all current @acronym{CPU}s have both 32- and 64-bit sets of |
| instructions. Most OSes running on such @acronym{CPU}s offer the choice |
| of building a 32-bit or a 64-bit version of @R{} (and details are given |
| below under specific OSes). For most a 32-bit version is the default, |
| but for some (e.g., @cputype{x86_64} Linux and macOS @geq{} 10.6) |
| 64-bit is. |
| |
| All current versions of @R{} use 32-bit integers (this is enforced in |
| the build) and @acronym{ISO}/@acronym{IEC}@tie{}60559@footnote{also |
| known as @acronym{IEEE}@tie{}754} double-precision reals, and so compute |
| to the same precision@footnote{at least when storing quantities: the |
| on-FPU precision is allowed to vary} and with the same limits on the |
| sizes of numerical quantities. The principal difference is in the size |
| of the pointers. |
| |
| 64-bit builds have both advantages and disadvantages: |
| @itemize |
| @item |
| The total virtual memory space made available to a 32-bit process is |
| limited by the pointer size to 4GB, and on most OSes to 3GB (or even |
| 2GB). The limits for 64-bit processes are much larger (e.g.@: |
| 8--128TB). |
| |
| @R{} allocates memory for large objects as needed, and removes any |
| unused ones at garbage collection. When the sizes of objects become an |
| appreciable fraction of the address limit, fragmentation of the address |
| space becomes an issue and there may be no hole available that is the |
| size requested. This can cause more frequent garbage collection or the |
| inability to allocate large objects. As a guide, this will become an |
| issue for 32-bit builds with objects more than 10% of the size of the |
| address space (around 300Mb) or when the total size of objects in use is |
| around one third (around 1Gb). |
| |
| @item |
| Only 64-bit builds support `long vectors', those with @math{2^{31}} or |
| more elements (which needs at least 16GB of storage for each numeric |
| vector). |
| |
| @item |
| Most 32-bit OSes by default limit file sizes to 2GB (and this may also |
| apply to 32-bit builds on 64-bit OSes). This can often be worked |
| around: @command{configure} selects suitable defines if this is |
| possible. (We have also largely worked around that limit on 32-bit |
| Windows.) 64-bit builds have much larger limits. |
| |
| @item |
| Because the pointers are larger, @R{}'s basic structures are larger. |
| This means that @R{} objects take more space and (usually) more time to |
| manipulate. So 64-bit builds of @R{} will, all other things being |
| equal, run slower than 32-bit builds. |
| |
| @item |
| However, `other things' may not be equal. In the specific case of |
| @cputype{x86_64} @emph{vs} @cputype{ix86}, the 64-bit CPU has features |
| (such as SSE2 instructions) which are guaranteed to be present but are |
| optional on the 32-bit CPU, and also has more general-purpose registers. |
| This means that on chips like a desktop Intel i7 the vanilla 64-bit |
| version of @R{} has been around 10% faster on both Linux and macOS. |
| (Laptop CPUs are usually relatively slower in 64-bit mode.) |
| @end itemize |
| |
| So, for speed you may want to use a 32-bit build (especially on a |
| laptop), but to handle large datasets (and perhaps large files) a 64-bit |
| build. You can often build both and install them in the same place: |
| @xref{Sub-architectures}. (This is done for the Windows binary |
| distributions.) |
| |
| Even on 64-bit builds of @R{} there are limits on the size of @R{} |
| objects (see @code{help("Memory-limits")}), some of which stem from the |
| use of 32-bit integers (especially in Fortran code). For example, each |
| dimension of an array is limited to @math{2^{31} - 1}. |
| |
| @node The standalone Rmath library, Essential and useful other programs under a Unix-alike, Choosing between 32- and 64-bit builds, Top |
| @chapter The standalone Rmath library |
| |
| The routines supporting the distribution and |
| special@footnote{e.g.@: Bessel, beta and gamma functions} functions in @R{} |
| and a few others are declared in C header file @file{Rmath.h}. These |
| can be compiled into a standalone library for linking to other |
| applications. (Note that they are not a separate library when @R{} is |
| built, and the standalone version differs in several ways.) |
| |
| The makefiles and other sources needed are in directory |
| @file{src/nmath/standalone}, so the following instructions assume that |
| is the current working directory (in the build directory tree on a |
| Unix-alike if that is separate from the sources). |
| |
| @file{Rmath.h} contains @samp{R_VERSION_STRING}, which is a character |
| string containing the current @R{} version, for example @code{"4.0.0"}. |
| |
| There is full access to @R{}'s handling of @code{NaN}, @code{Inf} and |
| @code{-Inf} via special versions of the macros and functions |
| |
| @example |
| ISNAN, R_FINITE, R_log, R_pow and R_pow_di |
| @end example |
| |
| @noindent |
| and (extern) constants @code{R_PosInf}, @code{R_NegInf} and @code{NA_REAL}. |
| |
| There is no support for @R{}'s notion of missing values, in particular |
| not for @code{NA_INTEGER} nor the distinction between @code{NA} and |
| @code{NaN} for doubles. |
| |
| A little care is needed to use the random-number routines. You will |
| need to supply the uniform random number generator |
| |
| @example |
| double unif_rand(void) |
| @end example |
| |
| @noindent |
| or use the one supplied (and with a shared library or DLL you may |
| have to use the one supplied, which is the Marsaglia-multicarry with |
| an entry point |
| |
| @example |
| set_seed(unsigned int, unsigned int) |
| @end example |
| |
| @noindent |
| to set its seeds). |
| |
| The facilities to change the normal random number generator are |
| available through the constant @code{N01_kind}. This takes values |
| from the enumeration type |
| |
| @example |
| typedef enum @{ |
| BUGGY_KINDERMAN_RAMAGE, |
| AHRENS_DIETER, |
| BOX_MULLER, |
| USER_NORM, |
| INVERSION, |
| KINDERMAN_RAMAGE |
| @} N01type; |
| @end example |
| |
| @noindent |
| (and @samp{USER_NORM} is not available). |
| |
| |
| @menu |
| * Unix-alike standalone:: |
| * Windows standalone:: |
| @end menu |
| |
| @node Unix-alike standalone, Windows standalone, The standalone Rmath library, The standalone Rmath library |
| @section Unix-alikes |
| |
| If @R{} has not already been made in the directory tree, |
| @command{configure} must be run as described in the main build |
| instructions. |
| |
| Then (in @file{src/nmath/standalone}) |
| |
| @example |
| make |
| @end example |
| |
| @noindent |
| will make standalone libraries @file{libRmath.a} and @file{libRmath.so} |
| (@file{libRmath.dylib} on macOS): @samp{make static} and @samp{make |
| shared} will create just one of them. |
| |
| To use the routines in your own C or C++ programs, include |
| |
| @example |
| #define MATHLIB_STANDALONE |
| #include <Rmath.h> |
| @end example |
| |
| @noindent |
| and link against @samp{-lRmath} (and @samp{-lm} if needed on your OS). |
| The example file @file{test.c} does nothing useful, but is provided to |
| test the process (via @command{make test}). Note that you will probably |
| not be able to run it unless you add the directory containing |
| @enindex LD_LIBRARY_PATH |
| @file{libRmath.so} to the @env{LD_LIBRARY_PATH} environment variable |
| (@file{libRmath.dylib}, @env{DYLD_FALLBACK_LIBRARY_PATH} on macOS). |
| |
| The targets |
| |
| @example |
| make install |
| make uninstall |
| @end example |
| |
| @noindent |
| will (un)install the header @file{Rmath.h} and shared and static |
| @enindex DESTDIR |
| libraries (if built). Both @code{prefix=} and @env{DESTDIR} are |
| supported, together with more precise control as described for the main |
| build. |
| |
| @samp{make install} installs a file for @command{pkg-config} to use by |
| e.g. |
| |
| @example |
| $(CC) `pkg-config --cflags libRmath` -c test.c |
| $(CC) `pkg-config --libs libRmath` test.o -o test |
| @end example |
| |
| On some systems @samp{make install-strip} will install a stripped shared |
| library. |
| |
| |
| |
| @node Windows standalone, , Unix-alike standalone, The standalone Rmath library |
| @section Windows |
| |
| You need to set up@footnote{including copying @file{MkRules.dist} to |
| @file{MkRule.local} and selecting the architecture.} almost all the |
| tools to make @R{} and then run (in a Unix-like shell) |
| |
| @example |
| (cd ../../gnuwin32; make MkRules) |
| (cd ../../include; make -f Makefile.win config.h Rconfig.h Rmath.h) |
| make -f Makefile.win |
| @end example |
| |
| @noindent |
| Alternatively, in a @file{cmd.exe} shell use |
| |
| @example |
| cd ../../include |
| make -f Makefile.win config.h Rconfig.h Rmath.h |
| cd ../nmath/standalone |
| make -f Makefile.win |
| @end example |
| |
| |
| This creates a static library @file{libRmath.a} and a DLL |
| @file{Rmath.dll}. If you want an import library @file{libRmath.dll.a} |
| (you don't need one), use |
| |
| @example |
| make -f Makefile.win shared implib |
| @end example |
| |
| To use the routines in your own C or C++ programs using MinGW-w64, include |
| |
| @example |
| #define MATHLIB_STANDALONE |
| #include <Rmath.h> |
| @end example |
| |
| @noindent |
| and link against @samp{-lRmath}. This will use the first found of |
| @file{libRmath.dll.a}, @file{libRmath.a} and @file{Rmath.dll} in that |
| order, so the result depends on which files are present. You should be |
| able to force static or dynamic linking @emph{via} |
| |
| @example |
| -Wl,-Bstatic -lRmath -Wl,Bdynamic |
| -Wl,-Bdynamic -lRmath |
| @end example |
| |
| @noindent |
| or by linking to explicit files (as in the @samp{test} target in |
| @file{Makefile.win}: this makes two executables, @file{test.exe} which |
| is dynamically linked, and @file{test-static.exe}, which is statically |
| linked). |
| |
| It is possible to link to @file{Rmath.dll} using other compilers, either |
| directly or via an import library: if you make a MinGW-w64 import library as |
| above, you will create a file @file{Rmath.def} which can be used |
| (possibly after editing) to create an import library for other systems |
| such as Visual C++. |
| |
| If you make use of dynamic linking you should use |
| |
| @example |
| #define MATHLIB_STANDALONE |
| #define RMATH_DLL |
| #include <Rmath.h> |
| @end example |
| |
| @noindent |
| to ensure that the constants like @code{NA_REAL} are linked correctly. |
| (Auto-import will probably work with MinGW-w64, but it is better to be |
| sure. This is likely to also work with VC++, Borland and similar |
| compilers.) |
| |
| |
| @node Essential and useful other programs under a Unix-alike, Configuration on a Unix-alike, The standalone Rmath library, Top |
| @appendix Essential and useful other programs under a Unix-alike |
| |
| This appendix gives details of programs you will need to build @R{} on |
| Unix-like platforms, or which will be used by @R{} if found by |
| @command{configure}. |
| |
| Remember that some package management systems (such as @acronym{RPM} and |
| Debian/Ubuntu's) make a distinction between the user version of a |
| package and the development version. The latter usually has the same |
| name but with the extension @samp{-devel} or @samp{-dev}: you need both |
| versions installed. |
| |
| @menu |
| * Essential programs and libraries:: |
| * Useful libraries and programs:: |
| * Linear algebra:: |
| @end menu |
| |
| @node Essential programs and libraries, Useful libraries and programs, Essential and useful other programs under a Unix-alike, Essential and useful other programs under a Unix-alike |
| @section Essential programs and libraries |
| |
| You need a means of compiling C and Fortran 90 (see @ref{Using |
| Fortran}). Your C compiler should be |
| @acronym{ISO}/@acronym{IEC}@tie{}60059@footnote{also known as |
| @acronym{IEEE}@tie{}754}, POSIX 1003.1 and C99-compliant.@footnote{Note |
| that C11 compilers need not be C99-compliant: @R{} requires support for |
| @code{double complex} and variable-length arrays which are optional in |
| C11 but are mandatory in C99. C18 (also known as C17) is a `bugfix |
| release' of C11, clarifying the standard.} @R{} tries to choose suitable |
| flags@footnote{Examples are @option{-std=gnu99}, @option{-std=c99} and |
| @option{-c99}.} for the C compilers it knows about, but you may have to |
| set @code{CC} or @code{CFLAGS} suitably. For versions of @command{gcc} |
| prior to 5.1 with @code{glibc}-based Linux this means including |
| @option{-std=gnu99}@footnote{@option{-std=c99} excludes POSIX |
| functionality, but @file{config.h} will turn on all @acronym{GNU} |
| extensions to include the POSIX functionality for @R{} itself: this does |
| not apply to badly-written packages. The default mode for GCC 5.1 and |
| later is @option{-std=gnu11}, which currently includes the optional |
| features @R{} needs.}. (Note that options essential to run the compiler |
| even for linking, such as those to set the architecture, should be |
| specified as part of @code{CC} rather than in @code{CFLAGS}.) |
| |
| Unless you do not want to view graphs on-screen (or use macOS) you need |
| @samp{X11} installed, including its headers and client libraries. For |
| recent Fedora/RedHat distributions it means (at least) RPMs |
| @samp{libX11}, @samp{libX11-devel}, @samp{libXt} and @samp{libXt-devel}. |
| On Debian/Ubuntu we recommend the meta-package @samp{xorg-dev}. If you |
| really do not want these you will need to explicitly configure @R{} |
| without X11, using @option{--with-x=no}. |
| |
| The command-line editing (and command completion) depends on the |
| @acronym{GNU} @code{readline} library (including its headers): version |
| 6.0 or later is needed for all the features to be enabled. Otherwise |
| you will need to configure with @option{--with-readline=no} (or |
| equivalent). |
| |
| A suitably comprehensive @code{iconv} function is essential. The @R{} |
| usage requires @code{iconv} to be able to translate between |
| @code{"latin1"} and @code{"UTF-8"}, to recognize @code{""} (as the |
| current encoding) and @code{"ASCII"}, and to translate to and from the |
| Unicode wide-character formats @code{"UCS-[24][BL]E"} --- this is true |
| by default for @code{glibc}@footnote{However, it is possible to break |
| the default behaviour of @code{glibc} by re-specifying the @code{gconv} |
| modules to be loaded.} but not of most commercial Unixes. However, you |
| can make use of @acronym{GNU} @code{libiconv} (as used on macOS: see |
| @uref{https://www.gnu.org/software/libiconv/}). |
| |
| The OS needs to have enough support@footnote{specifically, the C99 |
| functionality of headers @file{wchar.h} and @file{wctype.h}, types |
| @code{wctans_t} and @code{mbstate_t} and functions @code{mbrtowc}, |
| @code{mbstowcs}, @code{wcrtomb}, @code{wcscoll}, @code{wcstombs}, |
| @code{wctrans}, @code{wctype}, and @code{iswctype}.} for wide-character |
| types: this is checked at configuration. Some C99 |
| functions@footnote{including @code{expm1}, @code{hypot}, @code{log1p}, |
| @code{nearbyint} and @code{va_copy}.} are required and checked for at |
| configuration. A small number of POSIX functions@footnote{including |
| @code{opendir}, @code{readdir}, @code{closedir}, @code{popen}, |
| @code{stat}, @code{glob}, @code{access}, @code{getcwd} and @code{chdir} |
| system calls, @code{select} on a Unix-alike, and either @code{putenv} or |
| @code{setenv}.} are essential, and others@footnote{such as |
| @code{realpath}, @code{symlink}.} will be used if available. |
| |
| @c zlib 1.2.5 is from July 2010, bzip2 1.0.6 from Sept 2010 |
| @c xz 5.0.3 is from May 2011 |
| Installations of @code{zlib} (version 1.2.5 or later), @code{libbz2} |
| (version 1.0.6 or later: called @pkg{bzip2-libs}/@pkg{bzip2-devel} or |
| @pkg{libbz2-1.0}/@pkg{libbz2-dev} by some Linux distributions) and |
| @code{liblzma}@footnote{most often distributed as part of @code{xz}: |
| possible names in Linux distributions include |
| @code{xz-devel}/@code{xz-libs} and @code{liblzma-dev}.} version 5.0.3 or |
| later are required. |
| |
| @c PCRE[1] 8.32 is from Nov 2012. |
| @c Debian Wheezy had 8.30, Ubuntu 14.04LTS had 8.31 but both are EOL. |
| @c PCRE2: Ubuntu 16.04LTS (EOL Apr 2021) and RHEL/Centos 6 have 10.21, |
| @c OpenCSW has 10.20. |
| @c PCRE2 10.30 is from Aug 2017. Ubuntu 18.04LTS has 10.31. |
| Either PCRE1 (version 8.32 or later, formerly known as just PCRE) or |
| PCRE2 is required: PCRE2 is preferred and using PCRE1 requires |
| @command{configure} option @option{--with-pcre1}. Only the 8-bit |
| library and headers are needed if these are packaged separately. JIT |
| support (optional) is desirable for the best performance. For PCRE2 >= |
| 10.30 (which is desirable as matching has been re-written not to use |
| recursion and the Unicode tables were updated to version 10) |
| @example |
| ./configure --enable-jit |
| @end example |
| @noindent |
| suffices. If building PCRE1 for use with @R{} a suitable |
| @command{configure} command might be |
| @example |
| ./configure --enable-utf --enable-unicode-properties --enable-jit --disable-cpp |
| @end example |
| @noindent |
| The @option{--enable-jit} flag is supported for most common CPUs but |
| does not work (well or at all) for @cputype{arm64} macOS. |
| |
| Some packages require the `Unicode properties' which are |
| optional for PCRE1: support for this and JIT can be checked at run-time |
| by calling @code{pcre_config()}. |
| |
| @c libcurl 7.22.0 was released in Sep 2011, in Ubuntu 12.04 LTS, |
| @c end-of-life Apr 2017 |
| @c libcurl 7.26.0 was released in May 2012, still in Debian 7 Wheezy LTS, |
| @c end-of-life May 2018. |
| @c libcurl 7.28.0 was released in Oct 2012 |
| @c Ubuntu 16.04LTS has 7.47.0 |
| Library @code{libcurl} (version 7.28.0 or later@footnote{but not a major |
| version greater than 7 should there ever be one: the major version has |
| been 7 since 2000.}) is required. Information on @code{libcurl} is |
| found from the @command{curl-config} script: if that is missing or needs |
| to be overridden@footnote{for example to specify static linking with a |
| build which has both shared and static libraries.} there are macros to |
| do so described in file @file{config.site}. |
| |
| A @command{tar} program is needed to unpack the sources and packages |
| (including the recommended packages). A version@footnote{Such as |
| @acronym{GNU} @command{tar} 1.15 or later, @command{bsdtar} (from |
| @uref{https://github.com/libarchive/libarchive/}, used as |
| @command{tar} by FreeBSD and macOS 10.6 and later) or @command{tar} from |
| the Heirloom Toolchest |
| (@uref{http://heirloom.sourceforge.net/tools.html}), although the |
| latter does not support @command{xz} compression.} that can |
| automagically detect compressed archives is preferred for use with |
| @code{untar()}: the configure script looks for @command{gtar} and |
| @command{gnutar} before |
| @enindex TAR |
| @command{tar} -- use environment variable @env{TAR} to override this. |
| (On NetBSD/OpenBSD systems set this to @command{bsdtar} if that is |
| installed.) |
| |
| There need to be suitable versions of the tools @command{grep} and |
| @command{sed}: the problems are usually with old AT&T and BSD variants. |
| @command{configure} will try to find suitable versions (including |
| looking in @file{/usr/xpg4/bin} which is used on some commercial |
| Unixes). |
| |
| You will not be able to build most of the manuals unless you have |
| @command{texi2any} version 5.1 or later installed (which requires |
| @command{perl}), and if not most of the @HTML{} manuals will be linked |
| to a version on @acronym{CRAN}. To make PDF versions of the manuals you |
| will also need file @file{texinfo.tex} installed (which is part of the |
| @acronym{GNU} @pkg{texinfo} distribution but is often made part of the |
| @TeX{} package in re-distributions) as well as |
| @command{texi2dvi}.@footnote{@command{texi2dvi} is normally a shell |
| script. Some of the issues which have been observed with broken |
| versions of @command{texi2dvi} can be circumvented by setting the |
| environment variable @env{R_TEXI2DVICMD} to the value @code{emulation}.} |
| Further, the versions of @command{texi2dvi} and @file{texinfo.tex} need |
| to be compatible: we have seen problems with older @TeX{} distributions. |
| |
| @cindex Subversion |
| If you want to build from the @R{} Subversion repository then |
| @command{texi2any} is highly recommended as it is used to create files |
| which are in the tarball but not stored in the Subversion repository. |
| |
| @cindex Vignettes |
| The PDF documentation (including @file{doc/NEWS.pdf}) and building |
| vignettes needs @command{pdftex} and @command{pdflatex}. We require |
| @LaTeX{} version @code{2005/12/01} or later (for UTF-8 support). |
| Building PDF package manuals (including the @R{} reference manual) and |
| vignettes is sensitive to the version of the @LaTeX{} package |
| @pkg{hyperref} and we recommend that the @TeX{} distribution used is |
| kept up-to-date. A number of standard @LaTeX{} packages are required |
| (including @pkg{url} and some of the font packages such as @pkg{times} |
| and @pkg{helvetic} for the manuals, as well as @pkg{fancyvrb}, |
| @pkg{natbib} and @pkg{parskip} for the base vignettes) and others such |
| as @pkg{hyperref} and @pkg{inconsolata} are desirable (and without them |
| you may need to change @R{}'s defaults: @pxref{Making the manuals}). |
| Note that package @pkg{hyperref} (currently) requires packages |
| @pkg{kvoptions}, @pkg{ltxcmds} and @pkg{refcount}. For distributions |
| based on TeX Live the simplest approach may be to install collections |
| @pkg{collection-latex}, @pkg{collection-fontsrecommended}, |
| @pkg{collection-latexrecommended}, @pkg{collection-fontsextra} and |
| @pkg{collection-latexextra} (assuming they are not installed by |
| default): Fedora uses names like @pkg{texlive-collection-fontsextra} and |
| Debian/Ubuntu like @pkg{texlive-fonts-extra}. |
| |
| @enindex PATH |
| The essential programs should be in your @env{PATH} at the time |
| @command{configure} is run: this will capture the full paths. |
| |
| Those distributing binary versions of @R{} may need to be aware of the |
| licences of the external libraries it is linked to (including `useful' |
| libraries from the next section). The @code{liblzma} library is in the |
| public domain and X11, @code{libbzip2}, @code{libcurl} and @code{zlib} |
| have MIT-style licences. PCRE and PCRE2 have a BSD-style licence which |
| requires distribution of the licence (included in @R{}'s |
| @file{COPYRIGHTS} file) in binary distributions. GNU @code{readline} is |
| licensed under GPL (which version(s) of GPL depends on the |
| @code{readline} version). |
| |
| @node Useful libraries and programs, Linear algebra, Essential programs and libraries, Essential and useful other programs under a Unix-alike |
| @section Useful libraries and programs |
| |
| The ability to use translated messages makes use of @code{gettext} and |
| most likely needs @acronym{GNU} @code{gettext}: you do need this to work |
| with new translations, but otherwise the version of the @code{gettext} |
| runtime contained in the R sources will be used if no suitable external |
| @code{gettext} is found. |
| |
| @cindex Cairo |
| @cindex Pango |
| The `modern' version of the @code{X11()}, @code{jpeg()}, @code{png()} |
| and @code{tiff()} graphics devices uses the Cairo and Pango libraries. |
| Cairo version 1.2.0 or later and Pango version 1.10 or later are |
| required (but much later versions are current). @R{} checks for |
| @command{pkg-config}, and uses that to check first that the |
| @samp{pangocairo} package is installed (and if not, @samp{cairo}) then |
| if suitable code can be compiled. These tests will fail if |
| @command{pkg-config} is not installed@footnote{If necessary the path to |
| @command{pkg-config} can be specified by setting @env{PKG_CONFIG} in |
| @file{config.site}, on the @command{configure} command line or in the |
| environment. There is a compatible re-implementation of |
| @command{pkg-config} called @command{pkgconf} which can be used in the |
| unlikely event that is installed but not linked to |
| @command{pkg-config}.}, and might fail if @code{cairo} was built |
| statically unless @command{configure} option |
| @option{--with-static-cairo} is used. Most systems with @code{Gtk+} 2.8 |
| or later installed will have suitable libraries: for Fedora users the |
| @code{pango-devel} RPM and its dependencies suffice. |
| @c arm64 Homebrew did in early 2021. |
| It is possible (but very unusual on a platform with X11) to build Cairo |
| without its @code{cairo-xlib} module in which case @code{X11(type = |
| "cairo")} will not be available. Pango is optional but highly desirable |
| as it is likely to give much better text rendering, including kerning. |
| |
| For the best font experience with these devices you need suitable fonts |
| installed: Linux users will want the @code{urw-fonts} package. On |
| platforms which have it available, the @code{msttcorefonts} |
| package@footnote{also known as @code{ttf-mscorefonts-installer} in the |
| Debian/Ubuntu world: see also |
| @uref{https://en.wikipedia.org/wiki/Core_fonts_for_the_Web}.} provides |
| TrueType versions of Monotype fonts such as Arial and Times New Roman. |
| Another useful set of fonts is the `liberation' TrueType fonts available |
| at |
| @uref{https://pagure.io/liberation-fonts},@footnote{@code{ttf-liberation} |
| in Debian/Ubuntu.} which cover the Latin, Greek and Cyrillic alphabets |
| plus a fair range of signs. These share metrics with Arial, Times New |
| Roman and Courier New, and contain fonts rather similar to the first two |
| (@uref{https://en.wikipedia.org/wiki/Liberation_fonts}). Then there |
| is the `Free UCS Outline Fonts' project |
| (@uref{https://www.gnu.org/software/freefont/}) which are |
| OpenType/TrueType fonts based on the URW fonts but with extended Unicode |
| coverage. See the @R{} help on @code{X11} on selecting such fonts. |
| |
| The bitmapped graphics devices @code{jpeg()}, @code{png()} and |
| @code{tiff()} need the appropriate headers and libraries installed: |
| @code{jpeg} (version 6b or later, or @code{libjpeg-turbo}) or |
| @code{libpng} (version 1.2.7 or later) and @code{zlib} or @code{libtiff} |
| (versions 4.0.[5-10] and 4.[123].0 have been tested) respectively. |
| @command{pkg-config} is used if available and so needs the appropriate |
| @file{.pc} file (which requires @code{libtiff} version 4.x and is not |
| available on all platforms for @code{jpeg} before version 9c). They |
| also need support for either @code{X11} or @code{cairo} (see above). |
| Should support for these devices @strong{not} be required or broken |
| system libraries need to be avoided there are @command{configure} |
| options @option{--without-libpng}, @option{--without-jpeglib} and |
| @option{--without-libtiff}. The TIFF library has many optional features |
| such as @code{jpeg}, @code{libz}, @code{zstd}, @code{lzma}, @code{webp}, |
| @code{jbig} and @code{jpeg12}, none of which is required for the |
| @code{tiff()} devices but may need to be present to link the library |
| (usually only an issue for static linking). @command{pkg-config} can |
| tell you what other libraries are required for linking, for example by |
| @code{pkg-config libtiff-4 --static --libs}. |
| @c --print-requires and --print-requires-private are not recursive. |
| |
| Option @option{--with-system-tre} is also available: it needs a recent |
| version of TRE. (The latest sources are in the @command{git} repository |
| at @url{https://github.com/laurikari/tre/}, but at the time of writing |
| (2016) the resulting build did not pass its checks.). |
| |
| An implementation of @acronym{XDR} is required, and the @R{} sources |
| contain one which is likely to suffice (although a system version may |
| have higher performance). @acronym{XDR} is part of @acronym{RPC} and |
| historically has been part of @file{libc} on a Unix-alike. (In |
| principle @command{man xdr_string} should tell you which library is |
| needed, but it often does not: on some OSes it is provided by |
| @code{libnsl}.) However some builds@footnote{Including that used by |
| Fedora.} of @code{glibc} omit or hide it with the intention that the |
| @acronym{TI-RPC} library be used, in which case @code{libtirpc} (and its |
| development version) should be installed, and its headers@footnote{@R{} |
| uses @file{rpc/xdr.h} but that includes @file{netconfig.h} from the top |
| @file{tirpc} directory.} need to be on the C include path or under |
| @file{/usr/include/tirpc}. |
| |
| Use of the X11 clipboard selection requires the @code{Xmu} headers and |
| libraries. These are normally part of an X11 installation (e.g.@: the |
| Debian meta-package @samp{xorg-dev}), but some distributions have split |
| this into smaller parts, so for example recent versions of Fedora |
| require the @samp{libXmu} and @samp{libXmu-devel} RPMs. |
| |
| Some systems (notably macOS and at least some FreeBSD systems) have |
| inadequate support for collation in multibyte locales. It is possible |
| to replace the OS's collation support by that from ICU (International |
| Components for Unicode, @uref{https://icu.unicode.org/}), and this |
| provides much more precise control over collation on all systems. ICU |
| is available as sources and as binary distributions for (at least) most |
| Linux distributions, FreeBSD, macOS and AIX, usually as @code{libicu} or |
| @code{icu4c}. It will be used by default where available: should a very |
| old or broken version of ICU be found this can be suppressed by |
| @option{--without-ICU}. |
| |
| The @code{bitmap} and @code{dev2bitmap} devices and function |
| @code{embedFonts()} use ghostscript |
| (@uref{https://www.ghostscript.com/}). This should either be in your |
| path when the command is run, or its full path specified by the |
| environment variable @env{R_GSCMD} at that time. |
| @enindex R_GSCMD |
| |
| At the time of writing a full installation on Fedora Linux used the |
| following packages and their development versions, and this may provide |
| a useful checklist for other systems: |
| @example |
| bzip2 cairo fontconfig freetype fribidi glib2 harfbuzz libX11 libXext |
| libXt libcurl libicu libjpeg libpng libtiff libtirpc libxcrypt ncurses |
| pango pkgconf-pkg-config pcre2 readline tcl tk xz zlib |
| @end example |
| |
| |
| @menu |
| * Tcl/Tk:: |
| * Java support:: |
| * Other compiled languages:: |
| @end menu |
| |
| @node Tcl/Tk, Java support, Useful libraries and programs, Useful libraries and programs |
| @subsection Tcl/Tk |
| |
| The @pkg{tcltk} package needs Tcl/Tk @geq{} 8.4 installed: the sources are |
| available at @uref{https://www.tcl.tk/}. To specify the locations of the |
| Tcl/Tk files you may need the configuration options |
| |
| @table @option |
| @item --with-tcltk |
| use Tcl/Tk, or specify its library directory |
| @item --with-tcl-config=@var{TCL_CONFIG} |
| specify location of @file{tclConfig.sh} |
| @item --with-tk-config=@var{TK_CONFIG} |
| specify location of @file{tkConfig.sh} |
| @end table |
| |
| @noindent |
| or use the configure variables @code{TCLTK_LIBS} and |
| @code{TCLTK_CPPFLAGS} to specify the flags needed for linking against |
| the Tcl and Tk libraries and for finding the @file{tcl.h} and |
| @file{tk.h} headers, respectively. If you have both 32- and 64-bit |
| versions of Tcl/Tk installed, specifying the paths to the correct config |
| files may be necessary to avoid confusion between them. |
| |
| Versions of Tcl/Tk up to 8.5.19 and 8.6.11 have been tested (including |
| most versions of 8.4.x, but not recently). |
| |
| Note that the @file{tk.h} header includes@footnote{This is true even for |
| the `Aqua' version of Tk on macOS, but distributions of that include a |
| copy of the X11 files needed.} X11 headers, so you will need X11 and its |
| development files installed. |
| |
| @node Java support, Other compiled languages, Tcl/Tk, Useful libraries and programs |
| @subsection Java support |
| |
| The build process looks for Java support on the host system, and if it |
| finds it sets some settings which are useful for Java-using packages |
| (such as @CRANpkg{rJava} and @CRANpkg{JavaGD}: these require a full |
| JDK). This check can be suppressed by configure option |
| @option{--disable-java}. |
| @enindex JAVA_HOME |
| Configure variable @env{JAVA_HOME} can be set to point to a specific |
| JRE/JDK, on the @command{configure} command line or in the environment. |
| |
| Principal amongst these settings are some paths to the Java |
| libraries and JVM, which are stored in environment variable |
| @enindex R_JAVA_LD_LIBRARY_PATH |
| @env{R_JAVA_LD_LIBRARY_PATH} in file @file{@var{R_HOME}/etc/ldpaths} (or |
| a sub-architecture-specific version). A typical setting for |
| @cputype{x86_64} Linux is |
| |
| @example |
| JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.322.b06-6.fc34.x86_64/jre |
| R_JAVA_LD_LIBRARY_PATH=$@{JAVA_HOME@}/lib/amd64/server |
| @end example |
| |
| Unfortunately this depends on the exact version of the JRE/JDK |
| installed, and so may need updating if the Java installation is updated. |
| This can be done by running @code{R CMD javareconf} which updates |
| settings in both @file{@var{R_HOME}/etc/Makeconf} and |
| @file{@var{R_HOME}/etc/ldpaths}. See @code{R CMD javareconf --help} for |
| details: note that this needs to be done by the account owning the @R{} |
| installation. |
| |
| Another way of overriding those settings is to set the environment variable |
| @enindex R_JAVA_LD_LIBRARY_PATH |
| @env{R_JAVA_LD_LIBRARY_PATH} (before @R{} is started, hence not in |
| @file{~/.Renviron}), which suffices to run already-installed |
| Java-using packages. For example |
| |
| @example |
| R_JAVA_LD_LIBRARY_PATH=/usr/lib/jvm/java-1.8.0/jre/lib/amd64/server |
| @end example |
| |
| It may be possible to avoid this by specifying an invariant link as the |
| path when configuring. For example, on that system any of |
| |
| @example |
| JAVA_HOME=/usr/lib/jvm/java |
| JAVA_HOME=/usr/lib/jvm/java-1.8.0 |
| JAVA_HOME=/usr/lib/jvm/java-1.8.0/jre |
| JAVA_HOME=/usr/lib/jvm/jre-1.8.0 |
| @end example |
| |
| @noindent |
| worked (since the `auto' setting of @command{/etc/alternatives} chose |
| Java 8 aka 1.8.0). |
| |
| `Non-server' Oracle distributions of Java as from version 11 are of a |
| full JDK. However, Linux distributions can be confusing: for example |
| Fedora 34 had |
| @example |
| java-1.8.0-openjdk |
| java-1.8.0-openjdk-devel |
| java-openjdk |
| java-openjdk-devel |
| java-11-openjdk |
| java-11-openjdk-devel |
| java-17-openjdk |
| java-17-openjdk-devel |
| java-latest-openjdk |
| java-latest-openjdk-devel |
| @end example |
| @noindent |
| where the @code{-devel} RPMs are needed to complete the JDK. Debian/Ubuntu use |
| @samp{-jre} and @samp{-jdk}, e.g. |
| @example |
| sudo apt install default-jdk |
| @end example |
| @c https://www.digitalocean.com/community/tutorials/how-to-install-java-with-apt-on-ubuntu-18-04 |
| |
| @node Other compiled languages, , Java support, Useful libraries and programs |
| @subsection Other compiled languages |
| |
| Some add-on packages need a C++ compiler. This is specified by the |
| configure variables @code{CXX}, @code{CXXFLAGS} and similar. |
| @command{configure} will normally find a suitable compiler. It is |
| possible to specify an alternative C++17 compiler by the configure |
| variables @code{CXX17}, @code{CXX17STD}, @code{CXX17FLAGS} and similar |
| (@pxref{C++ Support}). Again, @command{configure} will normally find a |
| suitable value for @code{CXX17STD} if the compiler given by @code{CXX} |
| is capable of compiling C++17 code, but it is possible that a completely |
| different compiler will be needed. (Similar macros are provided for |
| C++20.) |
| |
| For source files with extension @file{.f90} or @file{.f95} containing |
| free-form Fortran, the compiler defined by the macro @code{FC} is used |
| by @command{R CMD INSTALL}. Note that it is detected by the name of the |
| command without a test that it can actually compile Fortran 90 code. |
| Set the configure variable @code{FC} to override this if necessary: |
| variables @code{FCFLAGS} and @code{FCLIBS_XTRA} might also need to be |
| set. |
| |
| See file @file{config.site} in the @R{} source for more details about |
| these variables. |
| |
| @node Linear algebra, , Useful libraries and programs, Essential and useful other programs under a Unix-alike |
| @section Linear algebra |
| @cindex BLAS library |
| |
| @menu |
| * BLAS:: |
| * LAPACK:: |
| * Caveats:: |
| @end menu |
| |
| @node BLAS, LAPACK, Linear algebra, Linear algebra |
| @subsection BLAS |
| |
| The linear algebra routines in @R{} can make use of enhanced |
| @acronym{BLAS} (Basic Linear Algebra Subprograms, |
| @uref{https://www.netlib.org/blas/faq.html}) routines. However, |
| these have to be explicitly requested at configure time: @R{} provides |
| an internal @acronym{BLAS} which is well-tested and will be adequate for |
| most uses of @R{}. |
| |
| You can specify a particular @acronym{BLAS} library @emph{via} a value |
| for the configuration option @option{--with-blas} and not to use an |
| external @acronym{BLAS} library by @option{--without-blas} (the |
| default). If @option{--with-blas} is given with no @code{=}, its value |
| is taken from the |
| @enindex BLAS_LIBS |
| environment variable @env{BLAS_LIBS}, set for example in |
| @file{config.site}. If neither the option nor the environment variable |
| supply a value, a search is made for a suitable@footnote{The search |
| includes OpenBLAS, ATLAS and a generic @file{libblas}, plus some |
| platform-specific choices (see below).} @acronym{BLAS}. If the value is |
| not obviously a linker command (starting with a dash or giving the path |
| to a library), it is prefixed by @samp{-l}, so |
| |
| @example |
| --with-blas="foo" |
| @end example |
| |
| @noindent |
| is an instruction to link against @samp{-lfoo} to find an external |
| @acronym{BLAS} (which needs to be found both at link time and run time). |
| |
| The configure code checks that the external @acronym{BLAS} is complete |
| (it must include all double precision and double complex routines, as |
| well as @code{LSAME}), and appears to be usable. However, an external |
| @acronym{BLAS} has to be usable from a shared object (so must contain |
| position-independent code), and that is not checked. |
| |
| Some enhanced @acronym{BLAS}es are compiler-system-specific |
| (@code{sunperf} on Solaris@footnote{Using the Oracle Developer Studio |
| @command{cc} and @command{f95} compilers}, @code{libessl} on IBM, |
| @code{Accelerate} on macOS). The correct incantation for these is often |
| found @emph{via} @option{--with-blas} with no value on the appropriate |
| platforms. |
| |
| Some of the external @acronym{BLAS}es are multi-threaded. One issue is |
| that @R{} profiling (which uses the @code{SIGPROF} signal) may cause |
| problems, and you may want to disable profiling if you use a |
| multi-threaded @acronym{BLAS}. Note that using a multi-threaded |
| @acronym{BLAS} can result in taking more @acronym{CPU} time and even |
| more elapsed time (occasionally dramatically so) than using a similar |
| single-threaded @acronym{BLAS}. On a machine running other tasks, there |
| can be contention for CPU caches that reduces the effectiveness of the |
| optimization of cache use by a @acronym{BLAS} implementation: some |
| people warn that this is especially problematic for hyperthreaded CPUs. |
| |
| Note that under Unix (but not under Windows) if @R{} is compiled against |
| a non-default @acronym{BLAS} and @option{--enable-BLAS-shlib} is |
| @strong{not} used (it is the default on all platforms except AIX), then |
| all @acronym{BLAS}-using packages must also be. So if @R{} is re-built |
| to use an enhanced @acronym{BLAS} then packages such as |
| @CRANpkg{quantreg} will need to be re-installed; they may be under other |
| circumstances. |
| |
| @R{} relies on @acronym{ISO}/@acronym{IEC}@tie{}60559 compliance of an |
| external @acronym{BLAS}. This can be broken if for example the code |
| assumes that terms with a zero factor are always zero and do not need to |
| be computed---whereas @code{x*0} can be @code{NaN}. This is checked in |
| the test suite. |
| |
| External @acronym{BLAS} implementations often make less use of |
| extended-precision floating-point registers (where available) and will |
| almost certainly re-order computations. This can result in less |
| accuracy than using a reference @acronym{BLAS}, and may result in |
| different solutions, e.g.@: different signs in SVD and |
| eigendecompositions. |
| |
| Debian/Ubuntu systems provide a system-specific way to switch the BLAS |
| in use. Build @R{} with @option{-with-blas} to select the OS version |
| of the reference BLAS, and then use @command{update-alternatives} to |
| switch between the available BLAS libraries. See |
| @uref{https://wiki.debian.org/DebianScience/LinearAlgebraLibraries}. |
| |
| Fedora 33 and later offer `FlexiBLAS', a similar mechanism for switching |
| the BLAS (and LAPACK) in use |
| (@uref{https://www.mpi-magdeburg.mpg.de/projects/flexiblas}). However, |
| rather than overriding @code{libblas}, this requires option |
| @option{--with-blas=flexiblas}. If installed, there are `backends' for |
| the reference BLAS, ATLAS and serial, threaded and OpenMP builds of |
| OpenBLAS and BLIS. |
| |
| The URIs for several of these BLAS have been subject to frequent |
| gratuitous changes, so you will need to search for their current |
| locations. |
| |
| BLAS (and LAPACK) routines may be used inside threaded code, for example |
| in OpenMP sections in packages such as @pkg{mgcv}. The reference |
| implementations are thread-safe but external ones may not be (even |
| single-threaded ones): this can lead to hard-to-track-down incorrect |
| results or segfaults. |
| @c Seen for OpenBLAS 0.3.2 in 2018. |
| |
| @strong{NOTE:} BLAS libraries built with @command{gfortran}@tie{}9 (and |
| later and versions 8.4, 7.5 and later in those series) require calls |
| from C/C++ to handle `hidden' character lengths --- @R{} itself does so |
| but many packages do not and some segfault. (This applies also to |
| external LAPACK libraries.) |
| |
| @menu |
| * ATLAS:: |
| * OpenBLAS:: |
| * MKL:: |
| * Shared BLAS:: |
| @end menu |
| |
| @node ATLAS, OpenBLAS, BLAS, BLAS |
| @subsubsection ATLAS |
| |
| ATLAS (@uref{http://math-atlas.sourceforge.net/}) is a ``tuned'' |
| @acronym{BLAS} that runs on a wide range of Unix-alike platforms. |
| Unfortunately it is built by default as a static library that on some |
| platforms may not be able to be used with shared objects such as are |
| used in @R{} packages. Be careful when using pre-built versions of |
| ATLAS static libraries (they seem to work on @cputype{ix86} platforms, |
| but not always on @cputype{x86_64} ones). |
| |
| ATLAS contains replacements for a small number of LAPACK routines, but |
| can be built to merge these with LAPACK sources to include a full LAPACK |
| library. |
| |
| Recent versions of ATLAS can be built as a single shared library, either |
| @code{libsatlas} or @code{libtatlas} (serial or threaded respectively): |
| these may even contain a full LAPACK. Such builds can be used by one of |
| @example |
| --with-blas=satlas |
| --with-blas=tatlas |
| @end example |
| @noindent |
| or, as on @cputype{x86_64} Fedora where a path needs to be specified, |
| @example |
| --with-blas="-L/usr/lib64/atlas -lsatlas" |
| --with-blas="-L/usr/lib64/atlas -ltatlas" |
| @end example |
| @noindent |
| Distributed ATLAS libraries cannot be tuned to your machine and so are a |
| compromise: for example Fedora tunes@footnote{The only way to see |
| exactly which CPUs the distributed libraries have been tuned for is to |
| read the @file{atlas.spec} file.} @cputype{x86_64} RPMs for CPUs with |
| SSE3 extensions, and separate RPMs may be available for specific CPU |
| families. |
| |
| Note that building @R{} on Linux against distributed shared libraries |
| may need @samp{-devel} or @samp{-dev} packages installed. |
| |
| Linking against multiple static libraries requires one of |
| @example |
| --with-blas="-lf77blas -latlas" |
| --with-blas="-lptf77blas -lpthread -latlas" |
| --with-blas="-L/path/to/ATLAS/libs -lf77blas -latlas" |
| --with-blas="-L/path/to/ATLAS/libs -lptf77blas -lpthread -latlas" |
| @end example |
| |
| Consult its installation |
| guide@footnote{@uref{http://math-atlas.sourceforge.net/atlas_install/}} |
| for how to build ATLAS as a shared library or as a static library with |
| position-independent code (on platforms where that matters). |
| |
| According to the ATLAS |
| FAQ@footnote{@uref{http://math-atlas.sourceforge.net/faq.html#tnum}} the |
| maximum number of threads used by multi-threaded ATLAS is set at compile |
| time. Also, the author advises against using multi-threaded ATLAS on |
| hyperthreaded CPUs without restricting affinities at compile-time to one |
| virtual core per physical CPU. (For the Fedora libraries the |
| compile-time flag specifies 4 threads.) |
| @c http://math-atlas.sourceforge.net/atlas_install/node21.html |
| |
| |
| @node OpenBLAS, MKL, ATLAS, BLAS |
| @subsubsection OpenBLAS and BLIS |
| |
| Dr Kazushige Goto wrote a tuned @acronym{BLAS} for several processors |
| and OSes, which was frozen in mid-2010. OpenBLAS |
| (@uref{https://www.openblas.net/}) is a descendant project with support |
| for some later CPUs. |
| |
| This can be used by configuring @R{} with something like |
| |
| @example |
| --with-blas="openblas" |
| @end example |
| |
| @noindent |
| See @pxref{Shared BLAS} for an alternative (and in many ways preferable) |
| way to use them. |
| |
| Some platforms provide multiple builds of OpenBLAS: for example Fedora 34 |
| has RPMs@footnote{(and more, e.g.@: for 64-bit ints and static versions).} |
| @example |
| openblas |
| openblas-threads |
| openblas-openmp |
| @end example |
| @noindent |
| providing shared libraries |
| @example |
| libopenblas.so |
| libopenblasp.so |
| libopenblaso.so |
| @end example |
| @noindent |
| respectively, each of which can be used as a shared BLAS. For the |
| second and third the number of threads is controlled by |
| @env{OPENBLAS_NUM_THREADS} and @env{OMP_NUM_THREADS} (as usual for |
| OpenMP) respectively. |
| |
| Note that building @R{} on Linux against distributed libraries may need |
| @samp{-devel} or @samp{-dev} packages installed. |
| |
| @c https://wiki.debian.org/DebianScience/LinearAlgebraLibraries |
| For @cputype{ix86} and @cputype{x86_64} most distributed libraries |
| contain several alternatives for different CPU microarchitectures with |
| the choice being made at run time. |
| |
| Another descendant project is BLIS |
| (@uref{https://github.com/flame/blis}). This has (in Fedora) shared |
| libraries |
| @example |
| libblis.so |
| libblisp.so |
| libbliso.so |
| @end example |
| @noindent |
| (@code{p} for `threads', @code{o} for OpenMP as for OpenBLAS) which can |
| also be used as a shared BLAS. The Fedora builds do not include LAPACK |
| in the BLIS libraries. |
| |
| @node MKL, Shared BLAS, OpenBLAS, BLAS |
| @subsubsection Intel MKL |
| For Intel processors (and perhaps others) and some distributions of |
| Linux, there is Intel's Math Kernel Library@footnote{Sometimes known as |
| `Intel oneAPI Math Kernel Library' or even `oneMKL'.}. You are |
| encouraged to read the documentation which is installed with the |
| library, before attempting to link to MKL. This includes a `link line |
| advisor' which will suggest appropriate incantations: its use is |
| recommended. Or see |
| @uref{https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl-link-line-advisor.html#gs.vpt6qp}. |
| |
| There are also versions of MKL for macOS@footnote{The issue for macOS |
| has been the use of double-complex routines.} and Windows, but when |
| these have been tried they did not work with the default compilers used |
| for @R{} on those platforms. |
| |
| The MKL interface has changed several times but has been stable in |
| recent years: the following examples have been used with versions 10.3 |
| to 2022.0.2, for GCC compilers on @cputype{x86_64}. |
| |
| To use a sequential version of MKL we used |
| |
| @example |
| MKL_LIB_PATH=/path/to/intel_mkl/mkl/lib/intel64 |
| export LD_LIBRARY_PATH=$MKL_LIB_PATH |
| MKL="-L$@{MKL_LIB_PATH@} -lmkl_gf_lp64 -lmkl_core -lmkl_sequential" |
| ./configure --with-blas="$MKL" --with-lapack |
| @end example |
| |
| @noindent |
| The option @option{--with-lapack} is used since MKL contains a tuned |
| copy of LAPACK (often older than the current version) as well as the |
| @acronym{BLAS} (@pxref{LAPACK}), although this can be omitted. |
| |
| Threaded MKL may be used by replacing the line defining the variable |
| @code{MKL} by |
| |
| @example |
| MKL="-L$@{MKL_LIB_PATH@} -lmkl_gf_lp64 -lmkl_core \ |
| -lmkl_gnu_thread -dl -fopenmp" |
| @end example |
| |
| @R{} can also be linked against a single shared library, |
| @code{libmkl_rt.so}, for both BLAS and LAPACK, but the correct OpenMP and |
| MKL interface layer then has to be selected via environment variables. With |
| 64-bit builds and the GCC compilers, we used |
| |
| @example |
| export MKL_INTERFACE_LAYER=GNU,LP64 |
| export MKL_THREADING_LAYER=GNU |
| @end example |
| |
| On Debian/Ubuntu, MKL is provided by package @code{intel-mkl-full} and one |
| can set @code{libmkl_rt.so} as the system-wide implementation of both BLAS |
| and LAPACK during installation of the package, so that also @R{} installed |
| from Debian/Ubuntu package @code{r-base} would use it. It is, however, |
| still essential to set @code{MKL_INTERFACE_LAYER} and |
| @code{MKL_THREADING_LAYER} before running @R{}, otherwise MKL computations |
| will produce incorrect results. @R{} does not have to be rebuilt to use MKL, |
| but @code{configure} include tests which may discover some errors such as a |
| failure to set the correct OpenMP and MKL interface layer. |
| |
| @noindent |
| The default number of threads will be chosen by the OpenMP software, but |
| can be controlled by setting @code{OMP_NUM_THREADS} or |
| @code{MKL_NUM_THREADS}, and in recent versions seems to default to a |
| sensible value for sole use of the machine. (Parallel MKL has not |
| always passed @command{make check-all}, but did with MKL 2019.4 and later.) |
| |
| MKL includes a partial implementation of FFTW3, which causes trouble for |
| applications that require some of the FFTW3 functionality unsupported in |
| MKL. Please see the MKL manuals for description of these limitations and |
| for instructions on how to create a custom version of MKL which excludes the |
| FFTW3 wrappers. |
| |
| @c https://stat.ethz.ch/pipermail/r-devel/2015-September/071717.html |
| @c It was reported in 2015 that |
| |
| @c @example |
| @c --with-blas='-mkl=parallel' --with-lapack |
| @c @end example |
| |
| @c @noindent |
| @c worked with the Intel 2015.3 compilers on Centos 6. |
| |
| @node Shared BLAS, , MKL, BLAS |
| @subsubsection Shared BLAS |
| |
| The @acronym{BLAS} library will be used for many of the add-on packages |
| as well as for @R{} itself. This means that it is better to use a |
| shared/dynamic @acronym{BLAS} library, as most of a static library will |
| be compiled into the @R{} executable and each @acronym{BLAS}-using |
| package. |
| |
| @R{} offers the option of compiling the @acronym{BLAS} into a dynamic |
| library @code{libRblas} stored in @file{@var{R_HOME}/lib} and linking |
| both @R{} itself and all the add-on packages against that library. |
| |
| This is the default on all platforms except AIX unless an external |
| @acronym{BLAS} is specified and found: for the latter it can be used by |
| specifying the option @option{--enable-BLAS-shlib}, and it can always be |
| disabled via @option{--disable-BLAS-shlib}. |
| |
| This has both advantages and disadvantages. |
| |
| @itemize |
| @item |
| It saves space by having only a single copy of the @acronym{BLAS} |
| routines, which is helpful if there is an external static @acronym{BLAS} |
| (as used to be standard for ATLAS). |
| |
| @item |
| There may be performance disadvantages in using a shared @acronym{BLAS}. |
| Probably the most likely is when @R{}'s internal @acronym{BLAS} is used |
| and @R{} is @emph{not} built as a shared library, when it is possible to |
| build the @acronym{BLAS} into @file{R.bin} (and @file{libR.a}) without |
| using position-independent code. However, experiments showed that in |
| many cases using a shared @acronym{BLAS} was as fast, provided high |
| levels of compiler optimization are used. |
| |
| @item |
| It is easy to change the @acronym{BLAS} without needing to re-install |
| @R{} and all the add-on packages, since all references to the |
| @acronym{BLAS} go through @code{libRblas}, and that can be replaced. |
| Note though that any dynamic libraries the replacement links to will |
| need to be found by the linker: this may need the library path to be |
| changed in @file{@var{R_HOME}/etc/ldpaths}. |
| @end itemize |
| |
| Another option to change the @acronym{BLAS} in use is to symlink a |
| single dynamic @acronym{BLAS} library to |
| @file{@var{R_HOME}/lib/libRblas.so}. For example, just |
| |
| @example |
| mv @var{R_HOME}/lib/libRblas.so @var{R_HOME}/lib/libRblas.so.keep |
| ln -s /usr/lib64/libopenblasp.so.0 @var{R_HOME}/lib/libRblas.so |
| @end example |
| |
| @noindent |
| on @cputype{x86_64} Fedora will change the @acronym{BLAS} used to |
| multithreaded OpenBLAS. A similar link works for most versions of the |
| OpenBLAS (provided the appropriate @file{lib} directory is in the |
| run-time library path or @command{ld.so} cache). It can also be used |
| for a single-library ATLAS, so on @cputype{x86_64} Fedora |
| |
| @example |
| ln -s /usr/lib64/atlas/libsatlas.so.3 @var{R_HOME}/lib/libRblas.so |
| ln -s /usr/lib64/atlas/libtatlas.so.3 @var{R_HOME}/lib/libRblas.so |
| @end example |
| |
| @noindent |
| can be used with its distributed ATLAS libraries. (If you have the |
| @samp{-devel} RPMS installed you can omit the @code{.0}/@code{.3}.) |
| |
| Note that rebuilding or symlinking @file{libRblas.so} may not suffice |
| if the intention is to use a modified LAPACK contained in an external |
| BLAS: the latter could even cause conflicts. However, on Fedora where |
| the OpenBLAS distribution contains a copy of LAPACK, it is the latter |
| which is used. |
| |
| |
| @node LAPACK, Caveats, BLAS, Linear algebra |
| @subsection LAPACK |
| |
| @cindex LAPACK library |
| |
| If when configuring @R{} a system LAPACK library is found of version |
| 3.10.0 or later (and not does contain BLAS routines) it will be used |
| instead of compiling the LAPACK code in the package sources. This can |
| be prevented by configuring @R{} with @option{--without-lapack}. |
| Using a static @file{liblapack.a} is not supported. |
| |
| It is assumed that @code{-llapack} is the reference LAPACK library but |
| on Debian/Ubuntu it can be switched, including after @R{} is installed. |
| On such a platform it is better to use @option{--without-lapack} or |
| @option{---with-blas--with-lapack} (see below) explicitly. The known |
| examples@footnote{ATLAS, OpenBLAS and Accelerate.} of a |
| non-reference LAPACK library found at installation all contain BLAS |
| routines so are excluded. |
| |
| Provision is made for specifying an external LAPACK library, principally |
| to cope with @acronym{BLAS} libraries which contain a copy of LAPACK |
| (such as @code{Accelerate} on macOS and some builds of ATLAS, MKL and |
| OpenBLAS on @cputype{ix86}/@cputype{x86_64} Linux). At least LAPACK |
| version 3.2 is required. This can only be done if @option{--with-blas} |
| has been used. |
| |
| However, the likely performance gains are thought to be small (and may |
| be negative). The default is not to search for a suitable LAPACK |
| library, and this is definitely @strong{not} recommended. You can |
| specify a specific LAPACK library or a search for a generic library by |
| the configuration option @option{--with-lapack}. The default for |
| @option{--with-lapack} is to check the @acronym{BLAS} library and then |
| look for an external library @samp{-llapack}. Sites searching for the |
| fastest possible linear algebra may want to build a LAPACK library using |
| the ATLAS-optimized subset of LAPACK. Similarly, OpenBLAS can be built |
| to contain an optimized subset of LAPACK or a full LAPACK (the latter |
| seeming to be the default). |
| |
| A value for @option{--with-lapack} can be set @emph{via} the environment |
| variable |
| @enindex LAPACK_LIBS |
| @env{LAPACK_LIBS}, but this will only be used if @option{--with-lapack} |
| is specified and the @acronym{BLAS} library does not contain LAPACK. |
| |
| If you do use @option{--with-lapack}, be aware of potential problems |
| with bugs in the LAPACK sources (or in the posted corrections to those |
| sources), seen several times in Linux distributions over the years. |
| |
| Please @strong{do} bear in mind that using @option{--with-lapack} is |
| `definitely @strong{not} recommended': it is provided @strong{only} |
| because it is necessary on some platforms and because some users want to |
| experiment with claimed performance improvements. |
| |
| Note too the comments about @acronym{ISO}/@acronym{IEC}@tie{}60559 |
| compliance in the section of external @acronym{BLAS}: these apply |
| equally to an external LAPACK, and for example the Intel MKL |
| documentation has said |
| @quotation |
| LAPACK routines assume that input matrices do not contain IEEE 754 |
| special values such as INF or NaN values. Using these special values may |
| cause LAPACK to return unexpected results or become unstable. |
| @end quotation |
| |
| We rely on limited support in LAPACK for matrices with @math{2^{31}} or |
| more elements: it is possible that an external LAPACK will not have that |
| support. |
| |
| |
| @node Caveats, , LAPACK, Linear algebra |
| @subsection Caveats |
| |
| As with all libraries, you need to ensure that they and @R{} were |
| compiled with compatible compilers and flags. For example, this has |
| meant that on Sun Sparc using the Oracle compilers the flag |
| @option{-dalign} is needed if @code{sunperf} is to be used. |
| |
| On some systems it has been necessary that an external |
| @acronym{BLAS}/LAPACK was built with the same Fortran compiler used to |
| build @R{}. |
| |
| LAPACK 3.9.0 (and probably earlier) had a bug in which the DCOMBSSQ |
| subroutine may cause NA to be interpreted as zero. This is fixed in the |
| @R{} 3.6.3 and later sources, but if you use an external LAPACK, you may |
| need to fix it there. (The bug was corrected in 3.9.1.) |
| |
| The code (in @code{dlapack.f}) should read |
| @example |
| * .. |
| * .. Executable Statements .. |
| * |
| IF( V1( 1 ).GE.V2( 1 ) ) THEN |
| IF( V1( 1 ).NE.ZERO ) THEN |
| V1( 2 ) = V1( 2 ) + ( V2( 1 ) / V1( 1 ) )**2 * V2( 2 ) |
| ELSE |
| V1( 2 ) = V1( 2 ) + V2( 2 ) |
| END IF |
| ELSE |
| V1( 2 ) = V2( 2 ) + ( V1( 1 ) / V2( 1 ) )**2 * V1( 2 ) |
| V1( 1 ) = V2( 1 ) |
| END IF |
| RETURN |
| @end example |
| (The inner ELSE clause was missing in LAPACK 3.9.0.) |
| |
| @node Configuration on a Unix-alike, Platform notes, Essential and useful other programs under a Unix-alike, Top |
| @appendix Configuration on a Unix-alike |
| |
| @menu |
| * Configuration options:: |
| * Internationalization support:: |
| * Configuration variables:: |
| * Setting the shell:: |
| * Using make:: |
| * Using Fortran:: |
| * Compile and load flags:: |
| * Maintainer mode:: |
| @end menu |
| |
| @node Configuration options, Internationalization support, Configuration on a Unix-alike, Configuration on a Unix-alike |
| @section Configuration options |
| |
| @command{configure} has many options: running |
| |
| @example |
| ./configure --help |
| @end example |
| |
| @noindent |
| will give a list. Probably the most important ones not covered |
| elsewhere are (defaults in brackets) |
| |
| @table @option |
| @item --with-x |
| use the X Window System [yes] |
| @item --x-includes=@var{DIR} |
| X include files are in @var{DIR} |
| @item --x-libraries=@var{DIR} |
| X library files are in @var{DIR} |
| @item --with-readline |
| use readline library (if available) [yes] |
| @item --enable-R-profiling |
| attempt to compile support for @code{Rprof()} [yes] |
| @item --enable-memory-profiling |
| attempt to compile support for @code{Rprofmem()} and @code{tracemem()} [no] |
| @item --enable-R-shlib |
| build @R{} as a shared/dynamic library [no] |
| @item --enable-BLAS-shlib |
| build the @acronym{BLAS} as a shared/dynamic library [yes, except on AIX] |
| @end table |
| |
| @noindent |
| You can use @option{--without-foo} or @option{--disable-foo} for the |
| negatives. |
| |
| You will want to use @option{--disable-R-profiling} if you are building |
| a profiled executable of @R{} (e.g.@: with @samp{-pg)}. Support for @R{} |
| profiling requires OS support for POSIX threads (@emph{aka} |
| @samp{pthreads}), which are available on all mainstream Unix-alike |
| platforms. |
| |
| Flag @option{--enable-R-shlib} causes the make process to build @R{} as |
| a dynamic (shared) library, typically called @file{libR.so}, and link |
| the main @R{} executable @file{R.bin} against that library. This can |
| only be done if all the code (including system libraries) can be |
| compiled into a dynamic library, and there may be a |
| performance@footnote{We have measured 15--20% on @cputype{i686} Linux |
| and around 10% on @cputype{x86_64} Linux.} penalty. So you probably |
| only want this if you will be using an application which embeds @R{}. |
| Note that C code in packages installed on an @R{} system linked with |
| @option{--enable-R-shlib} is linked against the dynamic library and so |
| such packages cannot be used from an @R{} system built in the default |
| way. Also, because packages are linked against @R{} they are on some |
| OSes also linked against the dynamic libraries @R{} itself is linked |
| against, and this can lead to symbol conflicts. |
| |
| For maximally effective use of @command{valgrind}, @R{} should be |
| compiled with valgrind instrumentation. The @command{configure} option |
| is @option{--with-valgrind-instrumentation=@var{level}}, where |
| @var{level} is 0, 1 or 2. (Level 0 is the default and does not add |
| anything.) The system headers for @command{valgrind} can be requested |
| by option @option{--with-system-valgrind-headers}: they will be used if |
| present (on Linux they may be in a separate package such as |
| @pkg{valgrind-devel}). Note though that there is no guarantee that the |
| code in @R{} will be compatible with very old@footnote{We believe that |
| versions 3.4.0 to 3.15.0 are compatible.} or future @command{valgrind} |
| headers. |
| |
| If you need to re-configure @R{} with different options you may need to run |
| @code{make clean} or even @code{make distclean} before doing so. |
| |
| The @file{configure} script has other generic options added by |
| @command{autoconf} and which are not supported for @R{}: in particular |
| building for one architecture on a different host is not possible. |
| |
| @node Internationalization support, Configuration variables, Configuration options, Configuration on a Unix-alike |
| @section Internationalization support |
| |
| Translation of messages is supported via @acronym{GNU} @code{gettext} |
| unless disabled by the configure option @option{--disable-nls}. |
| The @code{configure} report will show @code{NLS} as one of the |
| `Additional capabilities' if support has been compiled in, and running |
| in an English locale (but not the @code{C} locale) will include |
| |
| @example |
| Natural language support but running in an English locale |
| @end example |
| |
| @noindent |
| in the greeting on starting R. |
| |
| |
| @node Configuration variables, Setting the shell, Internationalization support, Configuration on a Unix-alike |
| @section Configuration variables |
| |
| @findex configure |
| If you need or want to set certain configure variables to something |
| other than their default, you can do that by either editing the file |
| @file{config.site} (which documents many of the variables you might want |
| to set: others can be seen in file @file{etc/Renviron.in}) or on the |
| command line as |
| |
| @example |
| ./configure @var{VAR}=@var{value} |
| @end example |
| |
| @noindent |
| If you are building in a directory different from the sources, there can |
| be copies of @file{config.site} in the source and the build directories, |
| and both will be read (in that order). In addition, if there is a file |
| @file{~/.R/config}, it is read between the @file{config.site} files in |
| the source and the build directories. |
| |
| There is also a general @command{autoconf} mechanism for |
| @file{config.site} files, which are read before any of those mentioned |
| in the previous paragraph. This looks first at a file specified by the |
| @enindex CONFIG_SITE |
| environment variable @env{CONFIG_SITE}, and if not is set at files such |
| as @file{/usr/local/share/config.site} and |
| @file{/usr/local/etc/config.site} in the area (exemplified by |
| @file{/usr/local}) where @R{} would be installed. |
| |
| These variables are @emph{precious}, implying that they do not have to |
| be exported to the environment, are kept in the cache even if not |
| specified on the command line, checked for consistency between two |
| configure runs (provided that caching is used), and are kept during |
| automatic reconfiguration as if having been passed as command line |
| arguments, even if no cache is used. |
| |
| See the variable output section of @code{configure --help} for a list of |
| all these variables. |
| |
| If you find you need to alter configure variables, it is worth noting |
| that some settings may be cached in the file @file{config.cache}, and it |
| is a good idea to remove that file (if it exists) before re-configuring. |
| Note that caching is turned @emph{off} by default: use the command line |
| option @option{--config-cache} (or @option{-C}) to enable caching. |
| |
| @menu |
| * Setting paper size:: |
| * Setting the browsers:: |
| * Compilation flags:: |
| * Making manuals:: |
| @end menu |
| |
| @node Setting paper size, Setting the browsers, Configuration variables, Configuration variables |
| @subsection Setting paper size |
| @enindex R_PAPERSIZE |
| One common variable to change is @env{R_PAPERSIZE}, which defaults to |
| @samp{a4}, not @samp{letter}. (Valid values are @samp{a4}, |
| @samp{letter}, @samp{legal} and @samp{executive}.) |
| |
| This is used both when configuring @R{} to set the default, and when |
| running @R{} to override the default. It is also used to set the |
| paper size when making PDF manuals. |
| |
| The configure default will most often be @samp{a4} if @env{R_PAPERSIZE} |
| is unset. (If the program @command{paperconf} is found, present in many |
| Linux distributions, |
| @enindex PAPERSIZE |
| or the environment variable @env{PAPERSIZE} is set, these are used to |
| produce the default.) |
| |
| @node Setting the browsers, Compilation flags, Setting paper size, Configuration variables |
| @subsection Setting the browsers |
| |
| @enindex R_BROWSER |
| Another precious variable is @env{R_BROWSER}, the default @HTML{} |
| browser, which should take a value of an executable in the user's path |
| or specify a full path. |
| |
| @enindex R_PDFVIEWER |
| Its counterpart for PDF files is @env{R_PDFVIEWER}. |
| |
| @node Compilation flags, Making manuals, Setting the browsers, Configuration variables |
| @subsection Compilation flags |
| |
| If you have libraries and header files, e.g., for @acronym{GNU} |
| readline, in non-system directories, use the variables @code{LDFLAGS} |
| (for libraries, using @samp{-L} flags to be passed to the linker) and |
| @code{CPPFLAGS} (for header files, using @samp{-I} flags to be passed to |
| the C/C++ preprocessors), respectively, to specify these locations. |
| These default to @samp{-L/usr/local/lib} (@code{LDFLAGS}, |
| @samp{-L/usr/local/lib64} on most 64-bit Linux OSes) and |
| @samp{-I/usr/local/include} (@code{CPPFLAGS}, but note that on most |
| systems @file{/usr/local/include} is regarded as a system include |
| directory and so instances in that macro will be skipped) to catch the |
| most common cases. If libraries are still not found, then maybe your |
| compiler/linker does not support re-ordering of @option{-L} and |
| @option{-l} flags. |
| @c (years ago this was reported to be a problem on HP-UX with the native |
| @c @command{cc}). |
| In this case, use a different compiler (or a front-end shell script |
| which does the re-ordering). |
| |
| These flags can also be used to build a faster-running version of @R{}. |
| On most platforms using @command{gcc}, having @samp{-O3} in |
| @code{CFLAGS} and @code{FFLAGS} produces worthwhile |
| performance gains with @command{gcc} and @command{gfortran}, but may |
| result in a less reliable build (both segfaults and incorrect numeric |
| computations have been seen). On systems using the @acronym{GNU} linker |
| (especially those using @R{} as a shared library), it is likely that |
| including @samp{-Wl,-O1} in @code{LDFLAGS} is worthwhile, and |
| @samp{'-Bdirect,--hash-style=both,-Wl,-O1'} is recommended at |
| @uref{https://lwn.net/Articles/192624/}. Tuning compilation to a |
| specific @acronym{CPU} family (e.g.@: @samp{-mtune=native} for |
| @command{gcc}) can give worthwhile performance gains, especially on |
| older architectures such as @cputype{ix86}. |
| |
| @node Making manuals, , Compilation flags, Configuration variables |
| @subsection Making manuals |
| |
| @enindex R_RD4PDF |
| @enindex R_PAPERSIZE |
| The default settings for making the manuals are controlled by |
| @env{R_RD4PDF} and @env{R_PAPERSIZE}. |
| |
| @node Setting the shell, Using make, Configuration variables, Configuration on a Unix-alike |
| @section Setting the shell |
| |
| By default the shell scripts such as @file{R} will be @samp{#!/bin/sh} |
| scripts (or using the @env{SHELL} chosen by @file{configure}). This is |
| almost always satisfactory, but on a few systems @file{/bin/sh} is not a |
| Bourne shell or clone, and the shell to be used can be changed by |
| setting the configure variable @env{R_SHELL} to a suitable value (a full |
| path to a shell, e.g.@: @file{/usr/local/bin/bash}). |
| |
| @node Using make, Using Fortran, Setting the shell, Configuration on a Unix-alike |
| @section Using make |
| @findex make |
| |
| To build in a separate directory you need a @command{make} that supports |
| the @code{VPATH} variable, for example @acronym{GNU} @command{make} and |
| @command{dmake}. |
| |
| If you want to use a @command{make} by another name, for example if your |
| @acronym{GNU} @command{make} is called @samp{gmake}, you need to set the |
| variable @code{MAKE} at configure time, for example |
| |
| @findex configure |
| @example |
| ./configure MAKE=gmake |
| @end example |
| |
| @node Using Fortran, Compile and load flags, Using make, Configuration on a Unix-alike |
| @section Using Fortran |
| @cindex Fortran |
| |
| To compile @R{}, you need a Fortran 90 compiler. The current default |
| is to search for |
| @c From AC_PROG_FC |
| @command{gfortran}, @command{g95}, @command{xlf95} @command{f95}, |
| @command{fort}, @command{ifort}, @command{ifc}, @command{efc}, |
| @command{pgfortran}, @command{pgf95} @command{lf95}, @command{ftn}, |
| @command{nagfor}, @command{xlf90}, @command{f90}, @command{pgf90}, |
| @command{pghpf}, @command{epcf90}. (Note that these are searched for by |
| name, without checking the standard of Fortran they support.) The |
| command and flags used should support fixed-form Fortran with extension |
| @file{.f}: in the unusual case that a specific flag is needed for |
| free-form Fortran with extension @file{.f90} or @file{.f95}, this can be |
| specified as part of @code{FCFLAGS}. |
| |
| The search mechanism can be changed using the configure variable |
| @code{FC} which specifies the command that runs the Fortran compiler. |
| If your Fortran compiler is in a non-standard location, you |
| @enindex PATH |
| should set the environment variable @env{PATH} accordingly before |
| running @command{configure}, or use the configure variable @code{FC} to |
| specify its full path. |
| |
| If your Fortran libraries are in slightly peculiar places, you should |
| @enindex LD_LIBRARY_PATH |
| also look at @env{LD_LIBRARY_PATH} (or your system's equivalent) to make |
| sure that all libraries are on this path. |
| |
| Note that only Fortran compilers which convert identifiers to lower case |
| are supported. |
| |
| You must set whatever compilation flags (if any) are needed to ensure |
| that Fortran @code{integer} is equivalent to a C @code{int} pointer and |
| Fortran @code{double precision} is equivalent to a C @code{double} |
| pointer. This is checked during the configuration process. |
| |
| Some of the Fortran code makes use of @code{DOUBLE COMPLEX} and |
| @code{COMPLEX*16} variables. This is checked for at configure time, as |
| well as its equivalence to the @code{Rcomplex} C structure defined in |
| @file{R_ext/Complex.h}. |
| |
| @command{gfortran}@tie{}10 by default gives a compilation error for the |
| previously widespread practice of passing a Fortran array element where |
| an array is expected, or a scalar instead of a length-one array. See |
| @uref{https://gcc.gnu.org/gcc-10/porting_to.html}. @command{gfortran}@tie{}12 |
| errors in more cases of this. |
| |
| @node Compile and load flags, Maintainer mode, Using Fortran, Configuration on a Unix-alike |
| @section Compile and load flags |
| |
| A wide range of flags can be set in the file @file{config.site} or as |
| configure variables on the command line. We have already mentioned |
| |
| @table @code |
| @item CPPFLAGS |
| header file search directory (@option{-I}) and any other miscellaneous |
| options for the C and C++ preprocessors and compilers |
| @item LDFLAGS |
| path (@option{-L}), stripping (@option{-s}) and any other miscellaneous |
| options for the linker |
| @end table |
| |
| @noindent |
| and others include |
| |
| @table @code |
| @item CFLAGS |
| debugging and optimization flags, C |
| @item MAIN_CFLAGS |
| ditto, for compiling the main program (e.g.@: when profiling) |
| @item SHLIB_CFLAGS |
| for shared objects (no known examples) |
| @item FFLAGS |
| debugging and optimization flags, fixed-form Fortran |
| @item FCFLAGS |
| debugging and optimization flags, free-form Fortran |
| @item SAFE_FFLAGS |
| ditto for source files which need exact floating point behaviour |
| @item MAIN_FFLAGS |
| ditto, for compiling the main program (e.g.@: when profiling) |
| @item SHLIB_FFLAGS |
| for shared objects (no known examples) |
| @item MAIN_LDFLAGS |
| additional flags for the main link |
| @item SHLIB_LDFLAGS |
| additional flags for linking the shared objects |
| @item LIBnn |
| the primary library directory, @file{lib} or @file{lib64} |
| @item CPICFLAGS |
| special flags for compiling C code to be turned into a shared object |
| @item FPICFLAGS |
| special flags for compiling Fortran code to be turned into a shared object |
| @item CXXPICFLAGS |
| special flags for compiling C++ code to be turned into a shared object |
| @item DEFS |
| defines to be used when compiling C code in @R{} itself |
| @end table |
| |
| @noindent |
| Library paths specified as @option{-L/lib/path} in @code{LDFLAGS} are |
| @enindex LD_LIBRARY_PATH |
| collected together and prepended to @env{LD_LIBRARY_PATH} (or your |
| system's equivalent), so there should be no need for @option{-R} or |
| @option{-rpath} flags. |
| |
| Variables such as @env{CPICFLAGS} are determined where possible by |
| @command{configure}. Some systems allows two types of PIC flags, for |
| example @samp{-fpic} and @samp{-fPIC}, and if they differ the first |
| allows only a limited number of symbols in a shared object. Since @R{} |
| as a shared library has about 6200 symbols, if in doubt use the larger |
| version. |
| |
| Other variables often set by @command{configure} include |
| @samp{MAIN_LDFLAGS}, @samp{SAFE_FFLAGS}, @samp{SHLIB_LDFLAGS} and |
| @samp{SHLIB_CXXLDFLAGS}: see file @file{config.site} in the sources for |
| more documentation on these and others. |
| |
| To compile a profiling version of @R{}, one might for example want to |
| use @samp{MAIN_CFLAGS=-pg}, @samp{MAIN_FFLAGS=-pg}, |
| @samp{MAIN_LDFLAGS=-pg} on platforms where @samp{-pg} cannot be used |
| with position-independent code. |
| |
| @strong{Beware}: it may be necessary to set @code{CFLAGS} and |
| @code{FFLAGS} in ways compatible with the libraries to be used: one |
| possible issue is the alignment of doubles, another is the way |
| structures are passed. |
| |
| On some platforms @command{configure} will select additional flags for |
| @code{CFLAGS}, @code{CPPFLAGS} and @code{LIBS} in @code{R_XTRA_CFLAGS} |
| (and so on). These are for options which are always required, for |
| example to force @acronym{IEC}@tie{}60559 compliance. |
| |
| @node Maintainer mode, , Compile and load flags, Configuration on a Unix-alike |
| @section Maintainer mode |
| |
| There are several files that are part of the @R{} sources but can be |
| re-generated from their own sources by configuring with option |
| @option{--enable-maintainer-mode} and then running @command{make} in the |
| build directory. This requires other tools to be installed, discussed |
| in the rest of this section. |
| |
| File @file{configure} is created from @file{configure.ac} and the files |
| under @file{m4} by @command{autoconf} and @command{aclocal} (part of the |
| @pkg{automake} package). There is a formal version requirement on |
| @command{autoconf} of 2.69 or later, but it is unlikely that anything |
| other than the most recent versions@footnote{at the time of revision of |
| this para in late 2021, @pkg{autoconf-2.71} and @pkg{automake-1.16.5}.} |
| have been thoroughly tested. |
| |
| File @file{src/include/config.h} is created by @command{autoheader} |
| (part of @pkg{autoconf}). |
| |
| Grammar files @file{*.y} are converted to C sources by an implementation |
| of @command{yacc}, usually @command{bison -y}: these are found in |
| @file{src/main} and @file{src/library/tools/src}. It is known that |
| earlier versions of @command{bison} generate code which reads (and in |
| some cases writes) outside array bounds: @command{bison} 2.6.1 was found |
| to be satisfactory. |
| |
| The ultimate sources for package @pkg{compiler} are in its @file{noweb} |
| directory. To re-create the sources from |
| @file{src/library/compiler/noweb/compiler.nw}, the command |
| @command{notangle} is required. Some Linux distributions include this |
| command in package @pkg{noweb}. It can also be installed from the |
| sources at @url{https://www.cs.tufts.edu/~nr/noweb/}@footnote{The links |
| there have proved difficult to access, in which case grab the copy |
| made available at |
| @uref{https://developer.r-project.org/noweb-2.11b.tgz}.}. The package |
| sources are only re-created even in maintainer mode if |
| @file{src/library/compiler/noweb/compiler.nw} has been updated. |
| |
| @c It is likely that in future creating @code{configure} will need the GNU |
| @c `autoconf archive' installed. This can be found at |
| @c @c and it has moved to github! |
| @c @url{https://www.gnu.org/software/autoconf-archive/} and as a package |
| @c (usually called @pkg{autoconf-archive}) in most packaged distributions, |
| @c for example Debian, Fedora, OpenCSW, Homebrew and MacPorts. |
| |
| @node Platform notes, Function and variable index, Configuration on a Unix-alike, Top |
| @appendix Platform notes |
| |
| This section provides some notes on building @R{} on different Unix-alike |
| platforms. These notes are based on tests run on one or two systems in |
| each case with particular sets of compilers and support libraries. |
| Success in building @R{} depends on the proper installation and functioning |
| of support software; your results may differ if you have other versions |
| of compilers and support libraries. |
| |
| Older versions of this manual contain notes on platforms such as HP-UX, |
| IRIX, Alpha/OSF1 (for @R{} < 2.10.0, and support has since been removed |
| for all of these) and AIX (for @R{} < = 3.5.x) for which we have had no |
| recent reports. |
| |
| C macros to select particular platforms can be tricky to track down |
| (there is a fair amount of misinformation on the Web). The Wiki |
| (currently) at @uref{https://sourceforge.net/p/predef/wiki/Home/} |
| can be helpful. The @R{} sources have used (often in included software |
| under @file{src/extra}) |
| @example |
| AIX: _AIX |
| Cygwin: __CYGWIN__ |
| FreeBSD: __FreeBSD__ |
| HP-UX: __hpux__, __hpux |
| IRIX: sgi, __sgi |
| Linux: __linux__ |
| macOS: __APPLE__ |
| NetBSD: __NetBSD__ |
| OpenBSD: __OpenBSD__ |
| Windows: _WIN32, _WIN64 |
| @end example |
| |
| @menu |
| * X11 issues:: |
| * Linux:: |
| * macOS:: |
| * FreeBSD:: |
| * OpenBSD:: |
| * Cygwin:: |
| * New platforms:: |
| @end menu |
| |
| @node X11 issues, Linux, Platform notes, Platform notes |
| @section X11 issues |
| |
| The @samp{X11()} graphics device is the one started automatically on |
| Unix-alikes (except most macOS builds) when plotting. As its name |
| implies, it displays on a (local or remote) X server, and relies on the |
| services provided by the X server. |
| |
| @cindex Cairo |
| The `modern' version of the @samp{X11()} device is based on @samp{cairo} |
| graphics and (in most implementations) uses @samp{fontconfig} to pick and |
| render fonts. This is done on the server, and although there can be |
| selection issues, they are more amenable than the issues with |
| @samp{X11()} discussed in the rest of this section. |
| |
| When X11 was designed, most displays were around 75dpi, whereas today |
| they are of the order of 100dpi or more. If you find that X11() |
| is reporting@footnote{for example, @code{X11 font at size 14 could not |
| be loaded}.} missing font sizes, especially larger ones, it is likely |
| that you are not using scalable fonts and have not installed the 100dpi |
| versions of the X11 fonts. The names and details differ by system, but |
| will likely have something like Fedora's |
| @example |
| xorg-x11-fonts-75dpi |
| xorg-x11-fonts-100dpi |
| xorg-x11-fonts-ISO8859-2-75dpi |
| xorg-x11-fonts-Type1 |
| xorg-x11-fonts-cyrillic |
| @end example |
| |
| @noindent |
| and you need to ensure that the @samp{-100dpi} versions are installed |
| and on the X11 font path (check via @command{xset -q}). The |
| @samp{X11()} device does try to set a pointsize and not a pixel size: |
| laptop users may find the default setting of 12 too large (although very |
| frequently laptop screens are set to a fictitious dpi to appear like a |
| scaled-down desktop screen). |
| |
| More complicated problems can occur in non-Western-European locales, so |
| if you are using one, the first thing to check is that things work in |
| the @code{C} locale. The likely issues are a failure to find any fonts |
| or glyphs being rendered incorrectly (often as a pair of @acronym{ASCII} |
| characters). X11 works by being asked for a font specification and |
| coming up with its idea of a close match. For text (as distinct from |
| the symbols used by plotmath), the specification is the first element of |
| the option @code{"X11fonts"} which defaults to |
| |
| @example |
| "-adobe-helvetica-%s-%s-*-*-%d-*-*-*-*-*-*-*" |
| @end example |
| |
| If you are using a single-byte encoding, for example ISO 8859-2 in |
| Eastern Europe or KOI8-R in Russian, use @command{xlsfonts} to find an |
| appropriate family of fonts in your encoding (the last field in the |
| listing). If you find none, it is likely that you need to install |
| further font packages, such as @samp{xorg-x11-fonts-ISO8859-2-75dpi} and |
| @samp{xorg-x11-fonts-cyrillic} shown in the listing above. |
| |
| Multi-byte encodings (most commonly UTF-8) are even more complicated. |
| There are few fonts in @samp{iso10646-1}, the Unicode encoding, and they |
| only contain a subset of the available glyphs (and are often fixed-width |
| designed for use in terminals). In such locales @emph{fontsets} are |
| used, made up of fonts encoded in other encodings. If the locale you |
| are using has an entry in the @samp{XLC_LOCALE} directory (typically |
| @file{/usr/share/X11/locale}), it is likely that all you need to do is to |
| pick a suitable font specification that has fonts in the encodings |
| specified there. If not, you may have to get hold of a suitable locale |
| entry for X11. This may mean that, for example, Japanese text can be |
| displayed when running in @samp{ja_JP.UTF-8} but not when running in |
| @samp{en_GB.UTF-8} on the same machine (although on some systems many |
| UTF-8 X11 locales are aliased to @samp{en_US.UTF-8} which covers several |
| character sets, e.g.@: ISO 8859-1 (Western European), JISX0208 (Kanji), |
| KSC5601 (Korean), GB2312 (Chinese Han) and JISX0201 (Kana)). |
| |
| On some systems scalable fonts are available covering a wide range of |
| glyphs. One source is TrueType/OpenType fonts, and these can provide |
| high coverage. Another is Type 1 fonts: the URW set of Type 1 fonts |
| provides standard typefaces such as Helvetica with a larger coverage of |
| Unicode glyphs than the standard X11 bitmaps, including Cyrillic. These |
| are generally not part of the default install, and the X server may need |
| to be configured to use them. They might be under the X11 @file{fonts} |
| directory or elsewhere, for example, |
| |
| @example |
| /usr/share/fonts/default/Type1 |
| /usr/share/fonts/ja/TrueType |
| @end example |
| |
| |
| @node Linux, macOS, X11 issues, Platform notes |
| @section Linux |
| @cindex Linux |
| |
| Linux is the main development platform for @R{}, so compilation from the |
| sources is normally straightforward with the most common compilers and |
| libraries.@footnote{For example, @code{glibc}: other C libraries such as |
| @code{musl} have been used but are not routinely tested.} |
| |
| Recall that some package management systems (such as @acronym{RPM} and |
| deb) make a distinction between the user version of a package and the |
| developer version. The latter usually has the same name but with the |
| extension @samp{-devel} or @samp{-dev}: you need both versions |
| installed. So please check the @code{configure} output to see if the |
| expected features are detected: if for example @samp{readline} is |
| missing add the developer package. (On most systems you will also need |
| @samp{ncurses} and its developer package, although these should be |
| dependencies of the @samp{readline} package(s).) You should expect to |
| see in the @command{configure} summary |
| |
| @example |
| Interfaces supported: X11, tcltk |
| External libraries: pcre2, readline, curl |
| Additional capabilities: PNG, JPEG, TIFF, NLS, cairo, ICU |
| @end example |
| |
| When @R{} has been installed from a binary distribution there are |
| sometimes problems with missing components such as the Fortran |
| compiler. Searching the @samp{R-help} archives will normally reveal |
| what is needed. |
| |
| It seems that @cputype{ix86} Linux accepts non-PIC code in shared |
| libraries, but this is not necessarily so on other platforms, in |
| particular on 64-bit @acronym{CPU}s such as @cputype{x86_64}. So care |
| can be needed with @acronym{BLAS} libraries and when building @R{} as a |
| shared library to ensure that position-independent code is used in any |
| static libraries (such as the Tcl/Tk libraries, @code{libpng}, |
| @code{libjpeg} and @code{zlib}) which might be linked against. |
| Fortunately these are normally built as shared libraries with the |
| exception of the ATLAS @acronym{BLAS} libraries. |
| |
| The default optimization settings chosen for @code{CFLAGS} etc are |
| conservative. It is likely that using @option{-mtune} will result in |
| significant performance improvements on recent CPUs: one possibility is |
| to add @option{-mtune=native} for the best possible performance on the |
| machine on which @R{} is being installed. It is also possible to |
| increase the optimization levels to @option{-O3}: however for many |
| versions of the compilers this has caused problems in at least one |
| @acronym{CRAN} package. |
| |
| Do not use @option{-O3} with @command{gcc} 11.0 or 11.1: it mis-compiles |
| code including in package @CRANpkg{MASS} resulting in plausible but |
| incorrect results. |
| |
| For platforms with both 64- and 32-bit support, it is likely that |
| |
| @example |
| LDFLAGS="-L/usr/local/lib64 -L/usr/local/lib" |
| @end example |
| |
| @noindent |
| is appropriate since most (but not all) software installs its 64-bit |
| libraries in @file{/usr/local/lib64}. To build a 32-bit version of @R{} |
| on @cputype{x86_64} with Fedora 34 we used |
| |
| @example |
| CC="gcc -m32" |
| CXX="g++ -m32" |
| FC="gfortran -m32" |
| OBJC=$@{CC@} |
| LDFLAGS="-L/usr/local/lib" |
| LIBnn=lib |
| @end example |
| |
| @noindent |
| Note the use of @samp{LIBnn}: @cputype{x86_64} Fedora installs its |
| 64-bit software in @file{/usr/lib64} and 32-bit software in |
| @file{/usr/lib}. Linking will skip over inappropriate binaries, but for |
| example the 32-bit Tcl/Tk configure scripts are in @file{/usr/lib}. It |
| may also be necessary to set the @command{pkg-config} path, e.g.@: by |
| |
| @example |
| export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig |
| @end example |
| @noindent |
| The 32-bit system @code{libcurl} did not work with the system CA |
| certificates: this is worked around in @R{}'s test suite. |
| |
| 64-bit versions on Linux are built with support for files > 2Gb, and |
| 32-bit versions will be if possible unless @option{--disable-largefile} |
| is specified. |
| |
| Note that 32-bit @code{glibc} before version 2.29 uses a 32-bit |
| @code{time_t} type, so to pass all the date-time checks needs @R{} built |
| with flag @option{--with-internal-tzcode}. |
| |
| Users of @cputype{ix86} CPUs with SSE2 support@footnote{Likely all since |
| 2005, including Pentium 4 and all @cputype{x86_64} CPUs with 32-bit |
| compilers.} may prefer to use the C/C++/Fortran flags |
| |
| @example |
| -mfpmath=sse -msse2 |
| @end example |
| |
| @noindent |
| to force floating-point to use the same instructions as @cputype{x86_64} |
| builds and hence not make use of 80-bit `extended precision' |
| intermediate results. (NB: this affects more than floating-point |
| operations. For some OSes and versions of @command{gcc} it might be |
| necessary to add @option{-mstackrealign}.) |
| |
| To build a 64-bit version of @R{} on @cputype{ppc64} (also known as |
| @cputype{powerpc64}) with @command{gcc}@tie{}4.1.1, Ei-ji Nakama used |
| |
| @example |
| CC="gcc -m64" |
| CXX="gxx -m64" |
| FC="gfortran -m64" |
| CFLAGS="-mminimal-toc -fno-optimize-sibling-calls -g -O2" |
| FFLAGS="-mminimal-toc -fno-optimize-sibling-calls -g -O2" |
| @end example |
| |
| @noindent |
| the additional flags being needed to resolve problems linking against |
| @file{libnmath.a} and when linking @R{} as a shared library. |
| |
| @c suggestion of https://gcc.gnu.org/wiki/FloatingPointMath |
| The setting of the macro @samp{SAFE_FFLAGS} may need some help. It |
| should not need additional flags on platforms other than @cputype{68000} |
| (not likely to be encountered) and @cputype{ix86}. For the latter, if |
| the Fortran compiler is GNU (@command{gfortran} or possibly |
| @command{g77}) the flags |
| @example |
| -msse2 -mfpmath=sse |
| @end example |
| @noindent |
| are added: earlier versions of @R{} added @option{-ffloat-store} and |
| this might still be needed if a @cputype{ix86} CPU is encountered |
| without SSE2 support. Note that it is a @emph{replacement} for |
| @samp{FFLAGS}, so should include all the flags in that macro (except |
| perhaps the optimization level). |
| |
| Additional compilation flags can be specified for added safety/security |
| checks. For example Fedora adds |
| |
| @example |
| -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2 -Wp,-D_GLIBCXX_ASSERTIONS |
| -Fexceptions -fstack-protector-strong -fasynchronous-unwind-tables |
| -fstack-clash-protection -fcf-protection |
| @end example |
| |
| @noindent |
| to all the C, C++ and Fortran compiler flags (even though |
| @code{_GLIBCXX_ASSERTIONS} is only for C++ in current GCC and |
| @code{glibc} and none of these are documented for @code{gfortran}). |
| Use of @code{_GLIBCXX_ASSERTIONS} will link @code{abort} and |
| @code{printf} into almost all C++ code, and @command{R CMD check |
| --as-cran} will warn. |
| |
| @menu |
| * Clang:: |
| * Intel compilers:: |
| @end menu |
| |
| @node Clang, Intel compilers, Linux, Linux |
| @subsection Clang |
| |
| @R{} has been built with Linux @cputype{ix86} and @cputype{x86_64} C and |
| C++ compilers (@uref{https://clang.llvm.org}) based on the Clang |
| front-ends, invoked by @code{CC=clang CXX=clang++}, together with |
| @command{gfortran}. These take very similar options to the |
| corresponding GCC compilers. |
| |
| This has to be used in conjunction with a Fortran compiler: the |
| @command{configure} code will remove @option{-lgcc} from @env{FLIBS}, |
| which is needed for some versions of @command{gfortran}. |
| |
| The current out-of-the-box default for @command{clang++} is to use the |
| C++ runtime from the installed @command{g++}. Using the runtime from |
| the @url{https://libcxx.llvm.org/, @code{libc++}} project (Fedora RPM |
| @code{libcxx-devel}) @emph{via} @option{-stdlib=libc++} has also been |
| tested. |
| |
| Recent versions have (optional when built) OpenMP support.@footnote{This |
| also needs the OpenMP runtime which has sometimes been distributed |
| separately.} |
| |
| @c This was about 'Classic Flang'. The newer version is not |
| @c yet able to compile Fortran. |
| @c There is a project called @command{flang} |
| @c (@uref{https://github.com/flang-compiler/flang})) to develop a |
| @c Fortran compiler similar to clang but based on the Portland Group's front |
| @c end. This needs something like |
| @c @example |
| @c FC=/usr/local/flang/bin/flang |
| @c LDFLAGS="-L/usr/local/flang/lib -L/usr/local/lib64" |
| @c @end example |
| |
| @c Note that @command{flang} accepts all the flags which @command{clang} |
| @c does (the driver is a modified version of @command{clang}, and |
| @c @command{flang} is a symbolic link to @command{clang}), but does not |
| @c implement all of them for Fortran compilation: it also accepts most |
| @c PGI-style flags such as @option{-mp} for OpenMP. It currently produces |
| @c few diagnostics even with @option{-Wall -pedantic}. |
| |
| @c @command{flang}'s Fortran runtime is compiled against OpenMP and it |
| @c seems this conflicts with using OpenMP in @R{}. So it may be necessary |
| @c to disable the latter by configuring @R{} using @option{--disable-openmp}. |
| |
| @c It is not clear what architectures @command{flang} intends to support: |
| @c our experiments were done on @cputype{x86_64}. At the time of writing |
| @c binary `releases' were available for that platform (called by them |
| @c @cputype{x86}) and @cputype{ppc64le}. |
| |
| |
| @node Intel compilers, , Clang, Linux |
| @subsection Intel compilers |
| |
| Intel compilers have been used under @cputype{ix86} and @cputype{x86_64} |
| Linux. Brian Ripley used version 9.0 of the compilers for |
| @cputype{x86_64} on Fedora Core 5 with |
| |
| @example |
| CC=icc |
| CFLAGS="-g -O3 -wd188 -ip -mp" |
| FC=ifort |
| FLAGS="-g -O3 -mp" |
| CXX=icpc |
| CXXFLAGS="-g -O3 -mp" |
| ICC_LIBS=/opt/compilers/intel/cce/9.1.039/lib |
| IFC_LIBS=/opt/compilers/intel/fce/9.1.033/lib |
| LDFLAGS="-L$ICC_LIBS -L$IFC_LIBS -L/usr/local/lib64" |
| SHLIB_CXXLD=icpc |
| @end example |
| |
| @noindent |
| It may be necessary to use @code{CC="icc -std=c99"} or @code{CC="icc |
| -c99"} for C99-compliance. The flag @option{-wd188} suppresses a large |
| number of warnings about the enumeration type @samp{Rboolean}. Because |
| the Intel C compiler sets @samp{__GNUC__} without complete emulation of |
| @command{gcc}, we suggest adding @code{CPPFLAGS=-no-gcc}. |
| |
| To maintain correct @acronym{IEC}@tie{}60559 arithmetic you most likely |
| need add flags to @code{CFLAGS}, @code{FFLAGS} and |
| @code{CXXFLAGS} such as @option{-mp} (shown above) or @option{-fp-model |
| precise -fp-model source}, depending on the compiler version. |
| |
| Others have reported success with versions 10.x and 11.x. |
| @c https://stat.ethz.ch/pipermail/r-devel/2015-September/071717.html |
| Bjørn-Helge Mevik reported success with version 2015.3 of the compilers, |
| using (for a SandyBridge CPU on Centos 6.x) |
| |
| @example |
| fast="-fp-model precise -ip -O3 -opt-mem-layout-trans=3 -xHost -mavx" |
| CC=icc |
| CFLAGS="$fast -wd188" |
| FC=ifort |
| FFLAGS="$fast" |
| CXX=icpc |
| CXXFLAGS="$fast" |
| @end example |
| |
| It is possible that 32-builds need to force the use of SSE2 instructions |
| in @code{SAFE_FFLAGS}, e.g.@: by |
| @example |
| SAFE_FFLAGS=-axsse2 |
| @end example |
| |
| @c What this architecture is known as varies. The kernel is called |
| @c 'Darwin' and so autoconf uses 'apple-darwin<kernel version>' with |
| @c current architectures x86_64 and aarch64. |
| @c OTOH, 'file' reports architectures x86_64, arm64 and arm64e and |
| @c Apple's clang has a -target flag with values like |
| @c x86_64-apple-macos10.12 and arm64-apple-macos11 |
| @c 'Activity monitor' reports the architectures as 'Intel' and 'Apple' |
| |
| @node macOS, FreeBSD, Linux, Platform notes |
| @section macOS |
| @cindex macOS |
| |
| The main instructions here are for Intel 64-bit (@cputype{x86_64}) |
| builds on 10.13--10.15 (High Sierra, Mojave and Catalina), 11 (Big |
| Sur) and 12 (Monterey). |
| @c @R{} can in principle be built for 10.6--10.12, although this is little |
| @c tested and it may be necessary to install later versions of software |
| @c such as @code{libcurl} and an older version@footnote{For example, from |
| @c @uref{https://github.com/fxcoudert/gfortran-for-macOS/releases}.} of |
| @c @command{gfortran}. |
| |
| @menu |
| * Prerequisites:: |
| * Cairo graphics:: |
| * Other C/C++ compilers:: |
| * Other libraries:: |
| * Tcl/Tk headers and libraries:: |
| * Java (macOS):: |
| * Frameworks:: |
| * Building R.app:: |
| * Building binary packages:: |
| * `Apple Silicon':: |
| @end menu |
| |
| @node Prerequisites, Cairo graphics, macOS, macOS |
| @subsection Prerequisites |
| |
| The following are essential to build @R{}: |
| |
| @itemize |
| @item |
| Apple's `Command Line Tools': these can be (re-)installed by running |
| @command{xcode-select --install} in a terminal. |
| |
| If you have a fresh OS installation, running e.g.@: @command{make} in a |
| terminal will offer the installation of the command-line tools. If you |
| have installed Xcode, this provides the command-line tools. The tools |
| may need to be reinstalled when macOS is upgraded, as upgrading may |
| partially or completely remove them. |
| |
| The Command Line Tools provide C and C++ compilers derived from LLVM's |
| @command{clang} but nowadays known as `Apple clang' with different |
| versioning (so Apple clang 13 is unrelated to LLVM clang 13). |
| |
| @item |
| A Fortran compiler. An installer for @command{gfortran} is available at |
| @uref{https://github.com/fxcoudert/gfortran-for-macOS/releases/download/8.2/gfortran-8.2-Mojave.dmg}.@footnote{This |
| is said to be for Mojave and later but works well enough on High |
| Sierra.} This installs into @file{/usr/local/gfortran}. |
| |
| @item |
| Binary components @code{pcre2} and @code{xz} (for @code{liblzma}) from |
| @uref{https://mac.r-project.org/bin/darwin17/x86_64/}. For example |
| @example |
| curl -OL https://mac.r-project.org/bin/darwin17/x86_64/pcre2-10.39-darwin.17-x86_64.tar.xz |
| sudo tar -xvzf pcre2-10.39-darwin.17-x86_64.tar.gz -C / |
| curl -OL https://mac.r-project.org/bin/darwin17/x86_64/xz-5.2.5-darwin.17-x86_64.tar.xz |
| sudo tar -xvzf xz-5.2.5-darwin.17-x86_64.tar.xz -C / |
| @end example |
| (Messages like @samp{usr/local/: Can't restore time} should be ignored.) |
| @end itemize |
| @noindent |
| (there is an @R{} script at @uref{https://mac.r-project.org/bin/} to |
| help with this) and desirable |
| @itemize |
| @item |
| GNU @code{readline5} from |
| @uref{https://mac.r-project.org/bin/darwin17/x86_64/},@footnote{For |
| licence reasons this is version 5.2 of @code{readline}: for those who |
| want a more recent version it is straightforward to compile it from its |
| sources.}. If @code{readline} is not present, the emulation in Apple's |
| version of @code{libedit} (aka @code{editline}) will be used: if you |
| wish to avoid that, configure with @option{--without-readline}. |
| |
| @item |
| Components @code{jpeg}, @code{libpng}, @code{pkgconfig}, @code{tiff} |
| from @uref{https://mac.r-project.org/bin/darwin17/x86_64/} and |
| @code{zlib-system-stub} from @uref{https://mac.R-project.org/libs-4/}, |
| for the full range of bitmapped graphics devices. (Some builds of |
| @code{tiff} may require @code{libwebp} and/or @code{openjpeg}.) |
| |
| @item |
| An X sub-system unless configuring using @option{--without-x}: see |
| @uref{https://www.xquartz.org/}. @R{}'s @command{configure} |
| script can be told to look for @code{X11} in XQuartz's main |
| location of @file{/opt/X11}, e.g.@: by |
| @example |
| --x-includes=/opt/X11/include --x-libraries=/opt/X11/lib |
| @end example |
| @noindent |
| although without this linked versions under @file{/usr/X11} will be |
| found. (It seems that for some versions of macOS/XQuartz |
| @file{/usr/X11} may exist but be a link to a non-existent directory: |
| reinstalling XQuartz might help.) Be wary of pre-release versions of |
| XQuartz, which may be offered as an update. |
| |
| @item |
| An Objective-C compiler, as provided by @command{clang} in the Command |
| Line Tools: this is needed for the @code{quartz()} graphics device. |
| |
| Use @option{--without-aqua} if you want a standard Unix-alike build: |
| apart from disabling @code{quartz()} and the ability to use the build |
| with @Rapp{}, it also changes the default location of the personal |
| library (see @code{?.libPaths}). |
| |
| @item |
| Support for Cairo-based graphics devices. @xref{Cairo graphics}. |
| |
| @item |
| A TeX installation. @xref{Other libraries}. |
| |
| @item |
| @command{texi2any} from a @samp{texinfo} distribution, which requires |
| @command{perl} (currently version 5.18 (High Sierra) -- 5.28 is a |
| default part of macOS but it has been announced that it may not be in |
| future). |
| @c macOS 10.15 release notes, but is in 11 |
| @c https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes |
| A version of @command{texi2any} has been included in the binary |
| distribution of @R{} and there is a @code{texinfo} component at |
| @uref{https://mac.r-project.org/bin/darwin17/x86_64/}. |
| @end itemize |
| |
| To build @R{} itself from the sources with the compilers in the Command |
| Line Tools (or Xcode) and @command{gfortran} from the installer |
| mentioned above, use a file @file{config.site} containing |
| @example |
| CC=clang |
| OBJC=$CC |
| FC=/usr/local/gfortran/bin/gfortran |
| CXX=clang++ |
| @end example |
| @noindent |
| and configure by something like |
| @example |
| ./configure -C \ |
| --enable-R-shlib --enable-memory-profiling \ |
| --x-includes=/opt/X11/include --x-libraries=/opt/X11/lib \ |
| --with-tcl-config=/usr/local/lib/tclConfig.sh \ |
| --with-tk-config=/usr/local/lib/tkConfig.sh \ |
| PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/lib/pkgconfig |
| @end example |
| @noindent |
| (See below for Tcl/Tk, including other options.) |
| |
| To install packages using compiled code one needs the Command Line Tools |
| (or Xcode) and appropriate compilers, e.g.@: Fortran and the C/C++ |
| compilers from those tools. Some packages have further requirements |
| such as @command{pkg-config}. |
| |
| @c svn was in CLT 11.3.1, even in the opensource.apple.com repository |
| A subversion client, @command{svn} version 1.10, used to be part of |
| macOS@footnote{but as a stub invoking an executable provided by the |
| Command Line Tools and the latter is not in versions 11.5 and later of |
| the Command Line Tools.}. A more recent client can be obtained from |
| @uref{https://mac.r-project.org/tools/}, for example by |
| @example |
| curl -OL https://mac.r-project.org/tools/subversion-1.14.0-darwin15.6.tar.gz |
| tar xf subversion-1.14.0-darwin15.6.tar.gz |
| sudo cp subversion-1.14.0-darwin15.6/svn /usr/local/bin |
| @end example |
| |
| If you have a build@footnote{For example, some Homebrew |
| distributions.} of @code{cairo} with dynamic libraries, you can add |
| option @option{--without-static-cairo} to the @command{configure} call |
| (it probably would work anyway). |
| |
| As from Command Line Tools version 12, |
| @option{-Wno-implicit-function-declaration} needs to be included in |
| @code{CFLAGS} to configure @R{} 4.0.2 and earlier as well as some |
| external software. |
| |
| @menu |
| * Note for Catalina and later users:: |
| @end menu |
| |
| @node Note for Catalina and later users, , Prerequisites, Prerequisites |
| @subsubsection Note for Catalina and later users |
| |
| A more recent Fortran compiler for Catalina and later is available at |
| @uref{https://github.com/fxcoudert/gfortran-for-macOS/releases/download/10.2/gfortran-10.2-Catalina.dmg}. |
| (That does not run on High Sierra.) This supports the option |
| @option{-fc-prototypes-external} mentioned in the `Writing R Extensions' |
| manual. |
| |
| For Big Sur and later there is |
| @uref{https://github.com/fxcoudert/gfortran-for-macOS/releases/download/11.2-bigsur-intel/gfortran-Intel-11.2-BigSur.dmg} |
| and for Monterey there is |
| @uref{https://github.com/fxcoudert/gfortran-for-macOS/releases/download/11.2-monterey-intel/gfortran-Intel-11.2-Monterey.dmg}. |
| |
| The default security settings for Catalina and later can make it |
| difficult to install recently-built Apple packages which have not been |
| `notarized'@footnote{See |
| @uref{https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution}.} |
| by Apple. And not just packages, as this has been seen for executables |
| contained in tarballs/zipfiles (for example, for @command{pandoc}). |
| Usually one can use @samp{Open With} (Control/right/two-finger-click in |
| Finder), then select @samp{Installer} and @samp{Open} if you get a |
| further warning message. This applies also to some `nightly builds' |
| from @uref{https://mac.R-project.org/}. |
| |
| If you run into problems with `quarantine' for tarballs downloaded in a |
| browser, consider using @command{curl -OL} to download (as illustrated |
| above) or @command{xattr -c} to remove extended attributes. |
| |
| Should one want to build @R{} for Intel on an @cputype{arm64} Big Sur |
| Mac, add the target for the C and C++ compilers: |
| |
| @example |
| CC="clang -arch x86_64 |
| OBJC=$CC |
| CXX="clang++ -arch x86_64" |
| @end example |
| |
| @noindent |
| and install the Fortran compiler and external software as described |
| above. |
| |
| @node Cairo graphics, Other C/C++ compilers, Prerequisites, macOS |
| @subsection Cairo graphics |
| |
| @cindex Cairo |
| Cairo-based graphics devices such as @code{cairo_ps}, @code{cairo_pdf}, |
| @code{X11(type = "cairo")} and the Cairo-based types of devices |
| @code{bmp} @code{jpeg}, @code{png} and @code{tiff} are not the default |
| on macOS, and much less used than the Quartz-based devices. However, |
| the only SVG device in the @R{} distribution, @code{svg}, is based on |
| Cairo. |
| |
| Support for Cairo is optional and can be added in several ways, all of |
| which need @code{pkg-config}. @command{configure} will add Cairo support |
| if @code{pkg-config} finds package @code{cairo} unless |
| @code{--without-cairo} is used. |
| |
| A way to statically link Cairo is by downloading and unpacking |
| components @code{cairo}, @code{fontconfig}, @code{freetype}, |
| @code{pixman} and @code{zlib-system-stub} (and do not have |
| @file{/opt/X11/lib/pkgconfig} in @env{PKG_CONFIG_PATH}). Some static |
| builds of @code{fontconfig} need @code{libxml2} (from component |
| @code{xml2}) and others @code{expat}, supplied by macOS but needing a |
| file @file{/usr/local/lib/pkgconfig/expat.pc} along the lines of |
| @example |
| Name: expat |
| Version: 2.2.8 |
| Description: expat XML parser |
| URL: http://www.libexpat.org |
| Libs: -lexpat |
| Cflags: |
| @end example |
| @noindent |
| Note that the list of components is liable to change: running |
| @command{pkg-config cairo --exists --print-errors} should tell you if |
| any others are required. |
| |
| If you have XQuartz 2.7.x installed (not 2.8.x) and ensure XQuartz's |
| @code{pkg-config} files are found first on its configuration path, Cairo |
| will be linked dynamically. This can be done by setting something like |
| @example |
| export PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/lib/pkgconfig |
| @end example |
| @noindent |
| or by appending that variable to the @command{configure} command. (Note |
| that this uses rather old versions of the graphics software.) |
| |
| @c Homebrew is another with dynamic libraries |
| If you use XQuartz or another build of @code{cairo} with dynamic |
| libraries, you can add option @option{--without-static-cairo} to the |
| @command{configure} call (it may work without). |
| @c A possible issue is that --static will require the private |
| @c dependencies of fontconfig, usually either xml2 or expat, and a |
| @c dynamic installation might not have the pkg-config files for those. |
| @c Another issue seen in XQuartz 2.8.0 is that pkg-config requires |
| @c the private dependencies of cairo of which xproto is not included. |
| |
| @cindex Pango |
| The best font experience of Cairo graphics will be to use it in |
| combination with Pango which will match that supported on most other |
| Unix-alikes. @command{configure} uses @command{pkg-config} to determine |
| if all the external software required by both Pango and Cairo is |
| available: running @command{pkg-config pangocairo --exists |
| --print-errors} should show if the installation suffices and if not, |
| what is missing. At the time of writing using pre-built components |
| @code{cairo}, @code{fontconfig}, @code{freetype}, @code{ffi}, |
| @code{fribidi}, @code{gettext}, @code{icu}, @code{glib}, |
| @code{harfbuzz}, @code{pango}, @code{pcre}, @code{pixman} and |
| @code{xml2} sufficed. |
| |
| @node Other C/C++ compilers, Other libraries, Cairo graphics, macOS |
| @subsection Other C/C++ compilers |
| |
| Other distributions of @command{clang} may be available from |
| @uref{https://github.com/llvm/llvm-project/releases/}. In particular, |
| these include support for OpenMP which Apple builds of @command{clang} |
| do not. |
| |
| Suppose one of these distributions is installed under |
| @file{/usr/local/clang}. Use a file @file{config.site} containing |
| @example |
| CC=/usr/local/clang/bin/clang |
| OBJC=$CC |
| FC=/usr/local/gfortran/bin/gfortran |
| CXX=/usr/local/clang/bin/clang++ |
| LDFLAGS="-L/usr/local/clang/lib -L/usr/local/lib" |
| R_LD_LIBRARY_PATH=/usr/local/clang/lib:/usr/local/lib |
| @end example |
| @noindent |
| The care to specify library paths is to ensure that the OpenMP runtime |
| library, here @file{/usr/local/clang/lib/libomp.dylib}, is found when |
| needed. If this works, you should see the line |
| @example |
| checking whether OpenMP SIMD reduction is supported... yes |
| @end example |
| @noindent |
| in the @command{configure} output. Also, @samp{R_LD_LIBRARY_PATH} needs |
| to be set to find the latest version of the C++ run-time libraries |
| rather than the system ones. |
| |
| For Mojave and later the system paths need to be specified @emph{via} |
| @example |
| CC="/usr/local/clang/bin/clang -isysroot |
| /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk" |
| CXX="/usr/local/clang/bin/clang++ -isysroot |
| /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk" |
| @end example |
| @noindent |
| (Long lines split for the manual, only.) Should the location of the SDK |
| change (or where Xcode provides the SDK rather than the Command Line |
| Tools), it can be found by running @command{xcrun -show-sdk-path}. |
| |
| It is usually possible to build @R{} with GCC (built from the sources, |
| from a @command{gfortran} distribution, from Homebrew, @dots{}). When |
| last tested@footnote{with @command{gcc} 10.2.} it was not possible to |
| use @command{gcc} to build the @code{quartz()} device, so |
| @command{configure --without-aqua} may be required. |
| |
| @node Other libraries, Tcl/Tk headers and libraries, Other C/C++ compilers, macOS |
| @subsection Other libraries |
| |
| Pre-compiled versions of many of the @ref{Useful libraries and programs} |
| are available from @uref{https://mac.r-project.org/bin/darwin17/x86_64/} or |
| @uref{https://mac.R-project.org/libs/}. |
| |
| @cindex BLAS library |
| @cindex LAPACK library |
| The @code{Accelerate} |
| library@footnote{@uref{https://developer.apple.com/documentation/accelerate}.} |
| can be used @emph{via} the configuration option |
| |
| @example |
| --with-blas="-framework Accelerate" |
| @end example |
| |
| @noindent |
| to provide potentially higher-performance versions of the @acronym{BLAS} |
| and LAPACK routines.@footnote{It has been reported that for some |
| non-Apple toolchains @code{CPPFLAGS} needed to contain |
| @code{-D__ACCELERATE__}: not needed for @command{clang} from |
| @uref{https://releases.llvm.org}.} This also includes a full |
| LAPACK which can be used @emph{via} @option{--with-lapack}: however, the |
| version of LAPACK it contains has |
| @c 3.2.1 in Monterey. |
| often been seriously old (and is not used unless @option{--with-lapack} |
| is specified). Some @acronym{CRAN} builds of @R{} can be |
| switched@footnote{@url{https://cran.r-project.org/bin/macosx/RMacOSX-FAQ.html#Which-BLAS-is-used-and-how-can-it-be-changed_003f}} |
| to use Accelerate's BLAS. |
| |
| @c https://developer.apple.com/documentation/accelerate/veclib |
| Threading in Accelerate is controlled by `Grand Central Dispatch' and is |
| said not to need user control. Test @file{nls.R} in package @pkg{stats} |
| has often failed with the Accelerate BLAS on Intel macOS. |
| |
| Looking at the top of |
| @file{/Library/Frameworks/R.framework/Resources/etc/Makeconf} |
| will show the compilers and configuration options used for the |
| @acronym{CRAN} binary package for @R{}: at the time of writing the |
| non-default options |
| @example |
| --enable-memory-profiling --enable-R-framework |
| --x-libraries=/opt/X11/lib --x-includes=/opt/X11/include |
| @end example |
| @noindent |
| were used. (@option{--enable-R-framework} implies @option{--enable-R-shlib}.) |
| |
| Configure option @option{--with-internal-tzcode} is the default on macOS, |
| as the system implementation of time zones does not work correctly for |
| times before 1902 or after 2037 (despite using a 64-bit @code{time_t}). |
| |
| The main @TeX{} implementation used by the developers is |
| MacTeX@footnote{An essentially equivalent @TeX{} installation can be |
| obtained by the Unix TeX Live installation scripts.} |
| (@uref{https://www.tug.org/mactex/}): the full installation is about |
| 7.5GB, but a much smaller version (`Basic TeX') is available at |
| @uref{https://www.tug.org/mactex/morepackages.html} to which you will |
| need to add some packages to build @R{}, e.g.@: for the 2022 version we |
| needed to add@footnote{E.g.@: @emph{via} @command{tlmgr install helvetic |
| inconsolata texinfo} .} @pkg{helvetic}, @pkg{inconsolata} and |
| @pkg{texinfo} which brought this to about 310MB.@footnote{Adding all the |
| packages needed to check @acronym{CRAN} increased this to about 600MB.} |
| @samp{TeX Live Utility} (available @emph{via} the MacTeX front page) |
| provides a graphical means to manage @TeX{} packages. MacTeX 2021 |
| requires Mojave or later: for earlier macOS versions see the |
| instructions@footnote{which amount to installing MacTeX 2020 (whose |
| LaTeX packages are frozen) or TeXLive 2021 (which has been tried and has |
| current updates).} on the MacTeX front page. It contains executables |
| which run natively on both @cputype{x86_64} and @cputype{arm64}. |
| |
| Checking packages thoroughly requires @command{ghostscript} (part of the |
| full MacTeX distribution or separately from |
| @uref{https://www.tug.org/mactex/morepackages.html}, including for High |
| Sierra) and @command{qpdf} (from |
| @uref{https://mac.r-project.org/bin/darwin17/x86_64/}, a version of |
| which is in the @file{bin} directory of a binary installation of @R{}, |
| usually |
| @file{/Library/@/Frameworks/@/R.framework/@/Resources/@/bin/@/qpdf}). |
| |
| One macOS quirk is that the default path has @file{/usr/local/bin} after |
| @file{/usr/bin}, contrary to common practice on Unix-alikes. This means |
| that if you install tools from the sources they will by default be |
| installed under @file{/usr/local} and not supersede the system |
| versions. |
| |
| Parallel installation of packages will make use of the utility |
| @command{timeout} if available. A dual-architecture build can be |
| downloaded from @uref{https://www.stats.ox.ac.uk/pub/bdr/timeout}: make |
| it executable (@code{chmod 755 timeout}) and put it somewhere on your |
| path. |
| |
| @node Tcl/Tk headers and libraries, Java (macOS), Other libraries, macOS |
| @subsection Tcl/Tk headers and libraries |
| |
| If you plan to use the @code{tcltk} package for @R{}, you need to |
| install a distribution of Tcl/Tk. There are two alternatives. If you |
| use @Rapp{} you will want to use X11-based Tcl/Tk (as used on other |
| Unix-alikes), which is installed under @file{/usr/local/lib} as part of |
| the @acronym{CRAN} binary for @R{}.@footnote{Just that component can be |
| selected from the installer for @R{}: at the `Installation Type' screen |
| select `Customise' and then just the `Tcl/Tk 8.6.6' component.} |
| This may need @command{configure} options |
| @example |
| --with-tcltk=/usr/local/lib |
| @end example |
| or |
| @example |
| --with-tcl-config=/usr/local/lib/tclConfig.sh |
| --with-tk-config=/usr/local/lib/tkConfig.sh |
| @end example |
| Note that this requires a matching@footnote{At the time of writing the |
| Intel distribution used 2.7.11 and the @cputype{arm64} used 2.8.1.} |
| XQuartz installation. |
| |
| There is also a native (`Aqua') version of Tcl/Tk which produces widgets |
| in the native macOS style: this will not work with @Rapp{} because of |
| conflicts over the macOS menu, but for those only using command-line |
| @R{} this provides a much more intuitive interface to Tk for experienced |
| Mac users. Earlier versions of macOS came with an Aqua Tcl/Tk |
| distribution but these were often not at all recent versions of Tcl/Tk. |
| It is better to install Tcl/Tk 8.6.x from the sources@footnote{Configure |
| Tk with @option{--enable-aqua}.} or a binary distribution from |
| @uref{https://www.activestate.com/activetcl/downloads}. For the latter, |
| configure @R{} with |
| @example |
| --with-tcl-config=/Library/Frameworks/Tcl.framework/tclConfig.sh |
| --with-tk-config=/Library/Frameworks/Tk.framework/tkConfig.sh |
| @end example |
| |
| If you need to find out which distribution of Tk is in use at run time, |
| use |
| @example |
| library(tcltk) |
| tclvalue(.Tcl("tk windowingsystem")) # "x11" or "aqua" |
| @end example |
| |
| Note that some Tcl/Tk extensions only support the X11 interface: this |
| includes @code{Tktable} and the @acronym{CRAN} package |
| @CRANpkg{tkrplot}. |
| |
| @node Java (macOS), Frameworks, Tcl/Tk headers and libraries, macOS |
| @subsection Java |
| |
| @c The situation with Java support on macOS is messy,@footnote{For more |
| @c details see @uref{https://www.macstrategy.com/article.php?3}.} and |
| @c distribution of Java for all platforms changed in 2018. |
| |
| macOS does not comes with an installed Java runtime (JRE) and a macOS |
| upgrade may remove one if already installed: it is intended to be |
| installed at first use. Check if a JRE is installed by running |
| @command{java -version} in a @command{Terminal} window: if Java is not |
| installed@footnote{In the unlikely event that the version reported does |
| not start with @code{1.8.0}, @code{11} or higher you need to update your |
| Java.} this should prompt you to install it.@footnote{Not at the time of |
| writing for @cputype{arm64}.} You can also install directly a recent |
| Java from |
| @uref{https://www.oracle.com/java/technologies/javase-downloads.html, |
| Oracle}. Builds of OpenJDK with a less restrictive licence may also be |
| available, e.g.@: from @uref{https://adoptium.net, Adoptium}, |
| @uref{https://www.azul.com/downloads/zulu-community/, Azul} or |
| @uref{https://jdk.java.net/}. We recommend you install a version with |
| long-term support, e.g.@: 11 or 17 but not 12--16 or 18 which |
| have/had a 6-month lifetime. (Note that these sources may use unusual |
| designations for Intel macOS builds such as @code{x86 64-bit} and |
| @code{x64}.) |
| |
| Binary distributions of @R{} are built against a specific version |
| (e.g.@: 11.0.6 or 17.0.1) of Java so @command{sudo R CMD javareconf} |
| will likely be needed to be run before using Java-using packages. |
| |
| To use Java (specifically, package @CRANpkg{rJava}) with a |
| @acronym{CRAN} (@cputype{x86_64}) binary distribution of @R{} on |
| @cputype{arm64} macOS, install an Intel build of a Java JRE from one of |
| the sites linked above, then run @command{sudo R CMD javareconf}. |
| |
| To see what compatible versions of Java are currently installed, run |
| @command{/usr/libexec/java_home -V -a x86_64}. If needed, set the |
| environment variable @env{JAVA_HOME} to choose between these, both when |
| @R{} is built from the sources and when @command{R CMD javareconf} is |
| run. |
| |
| Configuring and building @R{} both looks for a JRE and for support for |
| compiling JNI programs (used to install packages @CRANpkg{rJava} and |
| @CRANpkg{JavaGD}); the latter requires a JDK (Java SDK). Most |
| distributions of Java 9 or later are of a full JDK. |
| |
| The build process tries to fathom out what JRE/JDK to use, but it may |
| need some help, e.g.@: by setting environment variable @env{JAVA_HOME}. |
| To select a build from @uref{https://adoptium.net, Adoptium} |
| set e.g.@: |
| @example |
| JAVA_HOME=/Library/Java/JavaVirtualMachines/termurin-17.jdk/Contents/Home |
| @end example |
| @noindent |
| in @file{config.site}. For Java 17 from @uref{https://jdk.java.net/}, |
| use |
| @example |
| JAVA_HOME=/path/to/jdk-17.jdk/Contents/Home |
| @end example |
| |
| For an @cputype{arm64} build, the earliest Java version which is |
| officially supported is 17. The currently simplest way to install Java |
| is from @uref{https://adoptium.net, Adoptium} (who call the architecture |
| @cputype{aarch64}): this installs into an Apple-standard location and so |
| works with @command{/usr/bin/java}. Other builds are available from |
| @uref{https://www.azul.com/downloads/zulu-community/?os=macos&architecture=arm-64-bit&package=jdk} |
| and from OpenJDK at @uref{https://jdk.java.net/17/}, for which |
| @env{JAVA_HOME} may need to be set both when configuring @R{} and at |
| runtime. |
| |
| |
| @c A Oracle JDK can be |
| @c specified explicitly by something like |
| @c @example |
| @c JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home |
| @c JAVA_CPPFLAGS="-I/$@{JAVA_HOME@}/include -I/$@{JAVA_HOME@}/include/darwin" |
| @c JAVA_LD_LIBRARY_PATH="$@{JAVA_HOME@}/lib/server" |
| @c JAVA_LIBS="-L/$@{JAVA_HOME@}/lib/server -ljvm" |
| @c @end example |
| @c @noindent |
| @c in @file{config.site}. |
| |
| @c jdk.java.net no longer has Java 11 LTS builds. |
| |
| Note that it is necessary to set the environment variable @env{NOAWT} to |
| @code{1} to install many of the Java-using packages. |
| |
| |
| @node Frameworks, Building R.app, Java (macOS), macOS |
| @subsection Frameworks |
| |
| The @acronym{CRAN} build of @R{} is installed as a framework, which is |
| selected by the option |
| |
| @example |
| ./configure --enable-R-framework |
| @end example |
| |
| (This is intended to be used with an Apple toolchain: others may not |
| support frameworks correctly but those from |
| @uref{https://releases.llvm.org} do.) |
| |
| It is only needed if you want to build @R{} for use with the @Rapp{} |
| console, and implies @option{--enable-R-shlib} to build @R{} as a |
| dynamic library. This option configures @R{} to be built and installed |
| as a framework called @file{R.framework}. The default installation path |
| for @file{R.framework} is @file{/Library/Frameworks} but this can be |
| changed at configure time by specifying the flag |
| @option{--enable-R-framework[=@var{DIR}]} (or @option{--prefix}) or at |
| install time @emph{via} |
| |
| @example |
| make prefix=/where/you/want/R.framework/to/go install |
| @end example |
| |
| Note that installation as a framework is non-standard (especially to a |
| non-standard location) and Unix utilities may not support it (e.g.@: the |
| @command{pkg-config} file @file{libR.pc} will be put somewhere unknown |
| to @command{pkg-config}). |
| |
| @node Building R.app, Building binary packages, Frameworks, macOS |
| @subsection Building R.app |
| |
| Building the @Rapp{} GUI console is a separate project, using Xcode. |
| Before compiling @Rapp{} make sure the current version of @R{} is |
| installed in @file{/Library/Frameworks/R.framework} and working at the |
| command-line (this can be a binary install). |
| |
| The current sources can be checked out by |
| @example |
| svn co https://svn.r-project.org/R-packages/trunk/Mac-GUI |
| @end example |
| @noindent |
| and built by loading the @code{R.xcodeproj} project (select the |
| @code{R} target and a suitable configuration), or from the command-line |
| by e.g.@: |
| @example |
| xcodebuild -target R -configuration Release |
| @end example |
| See also the @file{INSTALL} file in the checkout or directly at |
| @uref{https://svn.r-project.org/R-packages/trunk/Mac-GUI/INSTALL}. |
| |
| @Rapp{} does not need to be installed in any specific way. Building |
| @Rapp{} results in the @Rapp{} bundle which appears as one @R{} icon. This |
| application bundle can be run anywhere and it is customary to place it |
| in the @file{/Applications} folder. |
| |
| @node Building binary packages, `Apple Silicon', Building R.app, macOS |
| @subsection Building binary packages |
| |
| @acronym{CRAN} macOS binary packages are distributed as tarballs with |
| suffix @file{.tgz} to distinguish them from source tarballs. One can |
| @command{tar} an existing installed package, or use @command{R CMD |
| INSTALL --build}. |
| |
| However, there are some important details. |
| @itemize |
| |
| @item |
| Current @acronym{CRAN} @cputype{x86_64} macOS distributions are targeted |
| at High Sierra so it is wise to ensure that the compilers generate code |
| that will run on High Sierra or later. With the recommended compilers |
| we can use |
| @example |
| CC="clang -mmacosx-version-min=10.13" |
| CXX="clang++ -mmacosx-version-min=10.13" |
| FC="/usr/local/gfortran/bin/gfortran -mmacosx-version-min=10.13" |
| @end example |
| |
| @item |
| Using the flag @option{-Werror=partial-availability} can help trigger |
| compilation errors on functionality not in High Sierra. |
| |
| @item |
| Check that any compiled code is not dynamically linked to libraries only |
| on your machine, for example by using @command{otool -L} or |
| @command{objdump -macho -dylibs-used}. This can include C++ and Fortran |
| run-time libraries under @file{/usr/local}: one can use |
| @command{install_name_tool} to point these at system versions or those |
| shipped with @R{}, for example |
| @example |
| install_name_tool -change /usr/local/clang/lib/libc++.1.dylib \ |
| /usr/lib/libc++.1.dylib \ |
| @var{pkg}.so |
| |
| install_name_tool -change /usr/local/gfortran/lib/libgfortran.5.dylib \ |
| /Library/Frameworks/R.framework/Resources/lib/libgfortran.5.dylib \ |
| @var{pkg}.so |
| @end example |
| |
| @noindent |
| (where the details depend on the compilers and @acronym{CRAN} macOS @R{} |
| release). |
| |
| @item |
| For C++ code there is the possibility that calls will be generated to |
| entry points not in the system @file{/usr/lib/libc++.1.dylib}. The |
| previous step allows this to be tested against the system library on the |
| build OS, but not against earlier ones. It may be possible to |
| circumvent that by static linking to @file{libc++.a} and |
| @file{libc++abi.a} by something like |
| @example |
| SHLIB_CXXLD = /usr/local/clang/bin/clang |
| PKG_LIBS = /usr/local/clang/lib/libc++.a /usr/local/clang/lib/libc++abi.a |
| @end example |
| @noindent |
| in @file{src/Makevars}. It would also be possible to static link the |
| Fortran runtime libraries @file{/usr/local/gfortran/lib/libgfortran.a} |
| and @file{/usr/local/gfortran/lib/libquadmath.a} should the Fortran |
| compiler have later versions (but @command{gfortran} 8, 9, 10 and 11 all |
| have version @code{5.0.0}). |
| @end itemize |
| @noindent |
| The @acronym{CRAN} binary packages are built with the Apple compiler on High |
| Sierra, which avoids the first two and any issues with C++ libraries. |
| |
| @node `Apple Silicon', , Building binary packages, macOS |
| @subsection @samp{arm64} aka `Apple Silicon' |
| |
| @menu |
| * Native builds:: |
| @end menu |
| |
| In November 2020 Apple launched Macs using `Apple Silicon': this architecture |
| has unfortunately many names, including @cputype{aarch64} (in the FOSS world) |
| @cputype{arm64} and @cputype{arm64e} (by Apple): the machines are also |
| known as `M1', Apple's name for their (first-generation) CPU. |
| |
| It is possible to build and run @R{} and almost all packages for |
| @cputype{x86_64} using `Rosetta' emulation. To do so, install all the |
| prerequisites and other software described above, but include the flag |
| @option{-arch x86_64} for @command{clang} and @command{clang++}, for |
| example with a @file{config.site} file containing |
| |
| @example |
| CC="clang -arch x86_64" |
| OBJC=$CC |
| CXX="clang++ -arch x86_64" |
| FC="/usr/local/gfortran/bin/gfortran -mtune=native -mmacosx-version-min=10.13" |
| @end example |
| |
| To correctly set the architecture (which will be auto-detected as |
| @code{aarch64}), use something like |
| |
| @example |
| /path/to/configure --build=x86_64-apple-darwin20 |
| @end example |
| |
| @node Native builds, , `Apple Silicon', `Apple Silicon' |
| @subsubsection Native builds |
| |
| This section follows the @acronym{CRAN} distribution in using |
| @file{/opt/R/arm64} rather than @file{/usr/local}: this largely allows |
| natively-compiled software to co-exist with compiled-for-Intel software |
| (although the C/C++ compilers and linker will still search |
| @file{/usr/local/include} and @file{/usr/local/lib}). |
| |
| No Fortran compiler has been released for this architecture although |
| there are ports under development. We used the fork of |
| @command{gfortran} from @url{https://github.com/iains/gcc-darwin-arm64} |
| of which there are binary distributions at |
| @uref{https://mac.r-project.org/libs-arm64/} and |
| @uref{https://github.com/fxcoudert/gfortran-for-macOS/releases/}. It |
| seems some of these have been built using the SDK path for Xcode and not |
| that for the Command Line Tools which causes some problems@footnote{such |
| as being unable to find @code{-lm}.} when using the Fortran compiler to |
| link: to fix that change the symbolic link |
| @file{/opt/R/arm64/gfortran/SDK} to point to your SDK, e.g.@: to |
| @file{/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk} (the |
| appropriate path can be found by running @command{xcrun |
| -show-sdk-path}). |
| |
| A release of XQuartz 2.8.1 is available @emph{via} |
| @uref{https://www.xquartz.org/releases/}: this is dual-architecture so |
| supports both @cputype{arm64} and @cputype{x86_64} builds. |
| |
| Binary builds of the prerequisites are available at |
| @uref{https://mac.r-project.org/bin/darwin20/arm64/}. (The simplest way |
| to get Tcl/Tk is to install |
| @uref{https://mac.r-project.org/libs-arm64/tcltk-8.6.11-xft-darwin20.4-arm64.pkg} |
| which bundles Tcl, Tk and Tktable, but you may already have these |
| installed by the @R{} binary package installer.) These unpack into |
| @file{/opt/R/arm64}: it is simplest to first create that directory and |
| adjust its ownership if desired: |
| |
| @example |
| sudo mkdir -p /opt/R/arm64 |
| sudo chown -R myaccount /opt/R |
| @end example |
| |
| @noindent |
| Then components can be downloaded and unpacked, for example |
| |
| @example |
| curl -OL https://mac.r-project.org/libs-arm64/jpeg-9d-darwin.20-arm64.tar.gz |
| tar -C/ -xf jpeg-9d-darwin.20-arm64.tar.gz |
| @end example |
| |
| @noindent |
| using @command{sudo} if necessary. (There is an @R{} script at |
| @uref{https://mac.r-project.org/bin/} to help with this.) |
| |
| If compiling from source, @code{pcre2} (at least up to version 10.39) |
| needs to be built without JIT support (the default) as the @R{} build |
| segfaults if that is enabled, so do run @code{make check} on your build. |
| |
| Add @file{/opt/R/arm64/bin} to the @env{PATH}, create a file |
| @file{config.site} something like |
| |
| @example |
| CC="clang -target arm64-apple-macos11" |
| OBJC=$CC |
| FC="/opt/R/arm64/gfortran/bin/gfortran -mtune=native" |
| CXX="clang++ -target arm64-apple-macos11" |
| CFLAGS="-falign-functions=8 -g -O2 -Wall -pedantic" |
| CPPFLAGS=-I/opt/R/arm64/include |
| LDFLAGS=-L/opt/R/arm64/lib |
| R_LD_LIBRARY_PATH=/opt/R/arm64/lib |
| @end example |
| |
| @noindent |
| (the first flag in @code{CFLAGS} is needed to inter-work with the |
| current @command{gfortran} without segfaulting in some packages). Then |
| configure @R{} using something like |
| |
| @example |
| /path/to/configure --enable-R-shlib --enable-memory-profiling \ |
| --with-tcl-config=/opt/R/arm64/lib/tclConfig.sh \ |
| --with-tk-config=/opt/R/arm64/lib/tkConfig.sh \ |
| PKG_CONFIG_PATH=/opt/R/arm64/lib/pkgconfig:/usr/lib/pkgconfig \ |
| JAVA_HOME=/path/to/jdk-17.jdk/Contents/Home |
| @end example |
| |
| Updating a build may fail because of the bug |
| described at @uref{https://openradar.appspot.com/FB8914243} but |
| @emph{ab initio} builds work. |
| |
| As with Intel builds, the @code{Accelerate} library could be used |
| @emph{via} the configuration option |
| |
| @example |
| --with-blas="-framework Accelerate" |
| @end example |
| |
| @noindent |
| Some @acronym{CRAN} builds of @R{} can be |
| switched@footnote{@url{https://cran.r-project.org/bin/macosx/RMacOSX-FAQ.html#Which-BLAS-is-used-and-how-can-it-be-changed_003f}} |
| to use it. |
| |
| @c It is possible to build external C/C++ libraries containing both |
| @c architectures which could then be used for building packages. A typical |
| @c configure line might be |
| |
| @c @example |
| @c ./configure --enable-static --disable-shared \ |
| @c CC='clang -arch arm64 -arch x86_64' CFLAGS=-O2 \ |
| @c CXX='clang++ -arch arm64 -arch x86_64' CXXFLAGS=-O2 \ |
| @c CPP='clang -E' CXXCPP='clang++ -E' |
| @c @end example |
| |
| @c @noindent |
| @c Such libraries installed into the usual default of @file{/usr/local} |
| @c will be usable for both @cputype{arm64} and @cputype{x86_64} builds. |
| |
| @c https://developer.apple.com/documentation/xcode/building_a_universal_macos_binary |
| According to Apple, C/C++ code intended only for this architecture can |
| be enclosed in an @code{#ifdef} block using macro @code{__arm64__} or |
| @code{__aarch64__} : you may want to also condition on @code{__APPLE__} |
| as those macros are defined on other OSes, at least for @command{clang} |
| and @command{gcc} (@code{__aarch64__}). |
| |
| If building software or installing source packages with @command{cmake} |
| (or a non-Apple @command{make}) ensure it contains the @cputype{arm64} |
| architecture (use @command{file} to be sure). Running compilers from an |
| @cputype{x86_64} executable will generate @cputype{x86_64} code @dots{}. |
| |
| @c @node Solaris, FreeBSD, macOS, Platform notes |
| @c @section Solaris |
| @c @cindex Solaris |
| |
| @c @menu |
| @c * 64-bit builds:: |
| @c * Using gcc:: |
| @c @end menu |
| |
| @c @R{} has been built successfully on Solaris 10 using the (zero cost) |
| @c Oracle Developer Studio@footnote{Formerly known as Oracle Solaris Studio |
| @c or Sun Studio.} compilers: there has also been success with |
| @c @command{gcc}/@command{gfortran}. (Recent Sun machines are AMD Opterons |
| @c or Intel Xeons (@cputype{amd64}) rather than @cputype{x86}, but 32-bit |
| @c @cputype{x86} executables are the default.) How these compilers |
| @c identify themselves is slightly confusing: commands @command{CC -V} with |
| @c Developer Studio 12.5 and 12.6 report as versions 5.14 and 5.15. We |
| @c will only consider Developer Studio versions 12.5 (May 2016) and 12.6 |
| @c (July 2017). |
| |
| @c There have been few reports on Solaris 11, with no known extra issues. |
| |
| @c Solaris was last tested on Sparc machines in June 2017 and on |
| @c @cputype{amd64} in December 2021. |
| |
| @c The Solaris versions of several of the tools needed to build @R{} |
| @c (e.g.@: @command{make}, @command{ar} and @command{ld}) are in |
| @c @file{/usr/ccs/bin}, so if using those tools ensure this is in your |
| @c path. A version of the preferred @acronym{GNU} @command{tar} is (if |
| @c installed) in @file{/usr/sfw/bin}. It may be necessary to avoid the |
| @c tools in @file{/usr/ucb}: POSIX-compliant versions of some tools can be |
| @c found in @file{/usr/xpg4/bin} and @file{/usr/xpg6/bin}. |
| |
| @c A large selection of Open Source software can be installed from |
| @c @uref{https://www.opencsw.org}, by default installed under |
| @c @file{/opt/csw}. Solaris 10 ships with @code{bzlib} version 1.0.6 |
| @c (sufficient) but @code{zlib} version 1.2.3 (too old): OpenCSW has 1.2.8. |
| @c (Note from 2019: updating of OpenCSW has slowed or stopped.) |
| |
| @c At least when compiling with Oracle compilers, Solaris uses far more |
| @c stack space than other platforms. This makes it desirable to build |
| @c PCRE1 (and PCRE2 < 10.30) with the option |
| @c @option{--disable-stack-for-recursion}: the OpenCSW distribution was at |
| @c the time of writing. |
| |
| @c The Oracle compilers are unusual in not including |
| @c @file{/usr/local/include} in the default include search path: @R{}'s |
| @c default @code{CPPFLAGS=-I/usr/local/include} remedies this. If you rely |
| @c on OpenCSW software you may need @code{CPPFLAGS=-I/opt/csw/include} (or |
| @c both). |
| |
| @c You will need @acronym{GNU} @code{libiconv} and @code{readline}: the |
| @c Solaris version of @code{iconv} is not sufficiently powerful. |
| |
| @c The native @command{make} suffices to build @R{} but a number of |
| @c packages require @acronym{GNU} @command{make} (some without declaring it |
| @c as @samp{SystemRequirements} in the @file{DESCRIPTION} file). |
| |
| @c The support for the C99 @code{long double} type on Sparc hardware uses |
| @c quad-precision arithmetic, and this is usually slow because it is done |
| @c by software emulation. On such systems the @command{configure} option |
| @c @option{--disable-long-double} can be used for faster but less accurate |
| @c computations. |
| |
| @c The Solaris time-zone conversion services seem to be unreliable pre-1916 |
| @c in Europe (when daylight-savings time was first introduced): most often |
| @c reporting in the non-existent DST variant. Using @command{configure} |
| @c option @option{--with-internal-tzcode} is recommended, and required if |
| @c you find time-zone abbreviations being given odd values (as has been |
| @c seen on 64-bit builds without it). It is also required for |
| @c @command{make check} to pass on Solaris 10. |
| |
| @c Using configure options @option{--with-internal-iswxxxxx} and |
| @c @option{--with-internal-towlower} is recommended for those working with |
| @c non-Western character data (as the system implementations use old tables |
| @c only covering the Unicode Basic Multilingual Plane). |
| |
| @c When using the Oracle compilers do @emph{not} specify @option{-fast}, as |
| @c this disables @acronym{IEEE} arithmetic and @command{make check} will |
| @c fail. |
| |
| @c A little juggling of paths was needed to ensure @acronym{GNU} |
| @c @code{libiconv} (in @file{/usr/local}) was used rather than the Solaris |
| @c @code{iconv}: |
| |
| @c @example |
| @c CC="cc -xc99" |
| @c CFLAGS="-O -xlibmieee" |
| @c FC=f95 |
| @c FFLAGS=-O |
| @c CXX=CC |
| @c CXXSTD="-std=c++11 -library=stdcpp,CrunG3" |
| @c CXX11STD="-std=c++11 -library=stdcpp,CrunG3" |
| @c CXX14STD="-std=c++14 -library=stdcpp,CrunG3" |
| @c CXXFLAGS=-O |
| @c R_LD_LIBRARY_PATH="/opt/developerstudio12.6/lib:/usr/local/lib:/opt/csw/lib" |
| @c @end example |
| |
| @c The Oracle compilers do not by default conform to the C99 standard |
| @c (appendix F 8.9) on the return values of functions such as @code{log}: |
| @c use @option{-xlibmieee} to ensure this. |
| |
| @c A peculiarity of some versions of the Fortran compiler has been that |
| @c when asked to link a shared object they did not link against all the |
| @c Fortran 9x runtime libraries, hence |
| @c @example |
| @c FCLIBS_XTRA="-lfsu /opt/developerstudio12.6/lib/libfui.so.2" |
| @c @end example |
| |
| @c @noindent |
| @c has been needed. |
| |
| @c Using @code{-xlibmil} in @code{CFLAGS} or @code{FFLAGS} allows more |
| @c system mathematical functions to be inlined. |
| |
| @c On @cputype{x86} you will get marginally higher performance @emph{via} |
| |
| @c @example |
| @c CFLAGS="-xO5 -xlibmieee -xlibmil -nofstore -xtarget=native" |
| @c FFLAGS="-xO5 -xlibmil -nofstore -xtarget=native" |
| @c CXXFLAGS="-xO5 -xlibmil -nofstore -xtarget=native" |
| @c SAFE_FFLAGS="-O -xlibmil -fstore -xtarget=native" |
| @c @end example |
| |
| @c @noindent |
| @c but the use of @code{-nofstore} can be less numerically stable, and some |
| @c packages have in the past failed to compile at optimization |
| @c level 5. |
| |
| @c The Oracle compilers provide several implementations of the C++ |
| @c standards which select both the set of headers and a C++ runtime |
| @c library. One of those is selected by the @option{-library} flag, which |
| @c as it is needed for both compiling and linking is best specified as part |
| @c of the compiler or standard. Current @R{} expects a C++11 compiler, for |
| @c which the choice given above is the only possibility. Although version |
| @c 12.5 accepted the flag @option{-std=c++14}, it did not pass |
| @c @command{configure}'s conformance tests: version 12.6 does. |
| |
| |
| @c @cindex BLAS library |
| @c @cindex LAPACK library |
| |
| @c The performance library @code{sunperf} is available for use with the |
| @c Oracle compilers. If selected as a @acronym{BLAS}, it must also be |
| @c selected as LAPACK @emph{via} |
| |
| @c @example |
| @c ./configure --with-blas='-library=sunperf' --with-lapack |
| @c @end example |
| |
| @c @noindent |
| @c This has often given test failures in the past, in several different |
| @c places.@footnote{When last checked it failed in @file{tests/reg-BLAS.R}, |
| @c and on some builds, including for @cputype{amd64}, it failed in |
| @c @code{example(eigen)}.} |
| |
| @c Parsing very complex @R{} expressions needs a lot of stack space when |
| @c the Oracle compilers are used: several packages require the stack |
| @c increased to at least 20MB. |
| |
| @c Some people have reported that the Solaris @code{libintl} needs to be |
| @c avoided, for example by using @option{--disable-nls} or |
| @c @option{--with-included-gettext} or using @code{libintl} from OpenCSW. |
| @c (On the other hand, there have been many successful installs which |
| @c automatically detected @code{libintl} from OpenCSW or selected the |
| @c included @code{gettext}.) |
| |
| @c It has been reported that some Solaris installations need |
| |
| @c @example |
| @c INTERNET_LIBS="-lsocket -lnsl" |
| @c @end example |
| |
| @c @noindent |
| @c on the @command{configure} command line or in file @file{config.site}; |
| @c however, there have been many successful installs without this. |
| |
| @c @node 64-bit builds, Using gcc, Solaris, Solaris |
| @c @subsection 64-bit builds |
| |
| @c On both @samp{x86} and @samp{Sparc} platforms the compilers default to |
| @c 32-bit code. |
| |
| @c For a 64-bit target add @option{-m64} to the compiler macros |
| @c and use something like @code{LDFLAGS=-L/usr/local/lib/amd64} or |
| @c @code{LDFLAGS=-L/usr/local/lib/sparcv9} as appropriate (and other 64-bit |
| @c library directories if used, e.g.@: @code{-L/opt/csw/lib/amd64}). |
| @c It will also be necessary to point @command{pkg-config} at the 64-bit |
| @c directories, e.g.@: by something like |
| |
| @c @example |
| @c PKG_CONFIG_PATH= /usr/local/lib/amd64/pkgconfig:/opt/csw/lib/64/pkgconfig:/usr/lib/64/pkgconfig |
| @c @end example |
| |
| @c @noindent |
| @c and to specify a 64-bit Java VM by e.g.@: |
| |
| @c @example |
| @c JAVA_CPPFLAGS="-I$@{JAVA_HOME@}/../include -I$@{JAVA_HOME@}/../include/solaris" |
| @c JAVA_LD_LIBRARY_PATH=$@{JAVA_HOME@}/lib/amd64/server |
| @c JAVA_LIBS="-L$@{JAVA_HOME@}/lib/amd64/server \ |
| @c -R$@{JAVA_HOME@}/lib/amd64/server -ljvm" |
| @c @end example |
| |
| @c @node Using gcc, , 64-bit builds, Solaris |
| @c @subsection Using gcc |
| |
| @c If using @command{gcc}, ensure that the compiler was compiled for the |
| @c version of Solaris in use. (This can be ascertained from @command{gcc |
| @c -v}.) @command{gcc} makes modified versions of some header files, and |
| @c several reports of problems were due to using @command{gcc} compiled on |
| @c one version of Solaris on a later version. Note that this can even |
| @c apply to OS patches: some 2016 patches to Solaris 10 changed its C |
| @c header files in way incompatible@footnote{In particular, header |
| @c @file{cmath} in C++11 mode includes @file{math.h} and |
| @c @file{iso/math_c99.h} and @command{gcc} had `fixed' an earlier version |
| @c of the latter.} with the modified versions included with OpenCSW's |
| @c binary distribution. |
| |
| @c The notes here are for @command{gcc} set up to use the Solaris linker: |
| @c it can also be set up to use GNU @command{ld}, but that has not been |
| @c tested. The tests were for compilers from the OpenCSW repository: |
| @c Solaris systems often come with much older compilers installed under |
| @c @file{/usr/sfw/bin}. One of @option{-m32} or @option{-m64} will be the |
| @c default and could be omitted, but it is not easy to find out which. |
| @c (For OpenCSW it is @option{-m32}.) |
| |
| @c Compilation for an @cputype{x86} target with @command{gcc}@tie{}5.2.0 |
| @c needed |
| |
| @c @example |
| @c CC="gcc -m32" |
| @c CPPFLAGS="-I/opt/csw/include -I/usr/local/include" |
| @c FC="gfortran -m32" |
| @c CXX="g++ -m32" |
| @c LDFLAGS="-L/opt/csw/lib -L/usr/local/lib" |
| @c @end example |
| |
| @c For an @cputype{amd64} target we used |
| |
| @c @example |
| @c CC="gcc -m64" |
| @c CPPFLAGS="-I/opt/csw/include -I/usr/local/include" |
| @c FC="gfortran -m64" |
| @c CXX="g++ -m64" |
| @c LDFLAGS="-L/opt/csw/lib/amd64 -L/usr/local/lib/amd64" |
| @c @end example |
| |
| @c Note that paths such as @file{/opt/csw/lib}, @file{/usr/local/lib/amd64} |
| @c and @file{/opt/csw/lib/amd64} may need to be in the |
| @c @enindex LD_LIBRARY_PATH |
| @c @env{LD_LIBRARY_PATH} during configuration. |
| |
| @c The latest version of @command{gcc} available in the OpenCSW |
| @c distribution at the time of writing was 5.5.0 (and had been since Oct |
| @c 2017). Later versions can be built from the sources, e.g.@: 9.3.0 (which |
| @c supports C++17, unlike 5.x). |
| |
| |
| @node FreeBSD, OpenBSD, macOS, Platform notes |
| @section FreeBSD |
| @cindex FreeBSD |
| |
| There have been few recent reports on FreeBSD: there is a `port' at |
| @uref{https://svnweb.freebsd.org/ports/head/math/}. Recent versions of |
| FreeBSD use Clang and the @code{libc++} C++ headers and runtime, but the |
| `port' is configured to use GCC. |
| |
| Use of ICU for collation and the @command{configure} option |
| @option{--with-internal-tzcode} are desirable workarounds. |
| |
| @node OpenBSD, Cygwin, FreeBSD, Platform notes |
| @section OpenBSD |
| @cindex OpenBSD |
| |
| Ingo Feinerer installed @R{} version 3.2.2 on OpenBSD 5.8 arch |
| @cputype{amd64} (their name for @cputype{x86_64}). Details of the build |
| (and patches applied) are at |
| @uref{https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/math/R/}. (Downgrading |
| the @code{zlib} requirement to 1.2.3 is against the advice of the @R{} |
| developers.) |
| |
| @node Cygwin, New platforms, OpenBSD, Platform notes |
| @section Cygwin |
| |
| The 32-bit version never worked well enough to pass @R{}'s @command{make |
| check}, and residual support from earlier experiments was removed in |
| @R{} 3.3.0. |
| |
| The 64-bit version was never supported. |
| |
| @node New platforms, , Cygwin, Platform notes |
| @section New platforms |
| |
| There are a number of sources of problems when installing @R {} on a new |
| hardware/OS platform. These include |
| |
| @strong{Floating Point Arithmetic}: @R{} requires arithmetic compliant |
| with @acronym{IEC}@tie{}60559, also known as @acronym{IEEE}@tie{}754. |
| This mandates the use of plus and minus infinity and @code{NaN} (not a |
| number) as well as specific details of rounding. Although almost all |
| current FPUs can support this, selecting such support can be a pain. |
| The problem is that there is no agreement on how to set the signalling |
| behaviour; Sun/Sparc, SGI/IRIX and @cputype{ix86} Linux require no |
| special action, FreeBSD requires a call to (the macro) |
| @code{fpsetmask(0)} and OSF1 required that computation be done with a |
| @option{-ieee_with_inexact} flag etc. With Intel compilers on 32-bit and |
| 64-bit Intel machines, one has to explicitly disable flush-to-zero and |
| denormals-are-zero modes. Some ARM processors including A12Z and M1 |
| (Apple Silicon) by default use runfast mode, which includes |
| flush-to-zero and default-nan and hence has to be disabled. With |
| default-nan mode, the NaN payload used for representation of numeric NA |
| values is lost even on simple operations with finite values. On a new |
| platform you must find out the magic recipe and add some code to make it |
| work. This can often be done via the file @file{config.site} which |
| resides in the top level directory. |
| |
| Beware of using high levels of optimization, at least initially. On |
| many compilers these reduce the degree of compliance to the |
| @acronym{IEEE} model. For example, using @option{-fast} on the Oracle |
| compilers has caused @R{}'s @code{NaN} to be set incorrectly, and |
| @command{gcc}'s @option{-ffast-math} and @command{clang}'s |
| @option{-Ofast} have given incorrect results. |
| |
| @strong{Shared Objects}: There seems to be very little agreement |
| across platforms on what needs to be done to build shared objects. |
| there are many different combinations of flags for the compilers and |
| loaders. @acronym{GNU} libtool cannot be used (yet), as it currently |
| does not fully support Fortran: one would need a shell wrapper for |
| this). The technique we use is to first interrogate the X window system |
| about what it does (using @command{xmkmf}), and then override this in |
| situations where we know better (for tools from the @acronym{GNU} |
| Compiler Collection and/or platforms we know about). This typically |
| works, but you may have to manually override the results. Scanning the |
| manual entries for @command{cc} and @command{ld} usually reveals the |
| correct incantation. Once you know the recipe you can modify the file |
| @file{config.site} (following the instructions therein) so that the |
| build will use these options. |
| |
| It seems that @command{gcc}@tie{}3.4.x and later on @cputype{ix86} Linux |
| defeat attempts by the LAPACK code to avoid computations entirely in |
| extended-precision registers, so file @file{src/modules/lapack/dlamc.f} |
| may need to be compiled without optimization or with additional flags. |
| Set the configure variable @env{SAFE_FFLAGS} to the flags to be used for |
| this file. |
| |
| If you do manage to get @R{} running on a new platform please let us |
| know about it so we can modify the configuration procedures to include |
| that platform. |
| |
| If you are having trouble getting @R{} to work on your platform please |
| feel free to use the @samp{R-devel} mailing list to ask questions. We |
| have had a fair amount of practice at porting @R{} to new platforms |
| @enddots{} |
| |
| @node Function and variable index, Concept index, Platform notes, Top |
| @unnumbered Function and variable index |
| |
| @printindex vr |
| |
| @node Concept index, Environment variable index, Function and variable index, Top |
| @unnumbered Concept index |
| |
| @printindex cp |
| |
| @node Environment variable index, , Concept index, Top |
| @unnumbered Environment variable index |
| |
| @printindex en |
| |
| |
| @bye |
| |
| @c Local Variables: *** |
| @c mode: TeXinfo *** |
| @c End: *** |