R-admin

R Installation and AdministrationVersion2.13.2(2011-09-30) R Development Core TeamPermission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.Permission is granted to copy and distribute modified versions of this manual under the con-ditions for verbatim copying,provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.Permission is granted to copy and distribute translations of this manual into another lan-guage,under the above conditions for modified versions,except that this permission notice may be stated in a translation approved by the R Development Core Team.Copyright c 2001–2010R Development Core TeamISBN3-900051-09-7Table of Contents1Obtaining R (1)1.1Getting and unpacking the sources (1)1.2Getting patched and development versions (1)1.2.1Using Subversion and rsync (1)2Installing R under Unix-alikes (3)2.1Simple compilation (3)2.2Help options (4)2.3Making the manuals (4)2.4Installation (6)2.5Uninstallation (8)2.6Sub-architectures (8)2.6.1Multilib (9)2.7Testing an Installation (9)2.8Byte-compiler (10)3Installing R under Windows (11)3.1Building from source (11)3.1.1Getting the tools (11)3.1.2Getting the source files (11)3.1.3Building the core files (12)3.1.4Building the bitmap files (13)3.1.5Checking the build (13)3.1.6Building the manuals (13)3.1.7Building the Inno Setup installer (14)3.1.8Building the MSI installer (15)3.1.9Cross-building on Linux (16)3.1.1064-bit Windows builds (16)3.2Byte-compiler (16)3.3Testing an Installation (16)4Installing R under(Mac)OS X (17)4.1Building from source on(Mac)OS X (17)5Running R (18)6Add-on packages (19)6.1Default packages (19)6.2Managing libraries (19)6.3Installing packages (20)6.3.1Windows (21)6.3.2OS X (22)6.3.3Customizing package compilation (22)6.3.4Multiple sub-architectures (22)6.4Updating packages (23)6.5Removing packages (23)6.6Setting up a package repository (23)6.7Checking installed source packages (24)7Internationalization and Localization (26)7.1Locales (26)7.1.1Locales under Linux (27)7.1.2Locales under Windows (27)7.1.3Locales under OS X (27)7.2Localization of messages (27)8Choosing between32-and64-bit builds (29)9The standalone Rmath library (31)9.1Unix-alikes (31)9.2Windows (32)Appendix A Essential and useful other programs under a Unix-alike (34)A.1Essential programs and libraries (34)A.2Useful libraries and programs (35)A.2.1Tcl/Tk (37)A.2.2Java support (37)A.3Linear algebra (38)A.3.1BLAS (38)A.3.1.1ATLAS (39)A.3.1.2ACML (39)A.3.1.3Goto BLAS (39)A.3.1.4Intel MKL (40)A.3.1.5Shared BLAS (40)A.3.2LAPACK (41)A.3.3Caveats (42)Appendix B Configuration on a Unix-alike (43)B.1Configuration options (43)B.2Internationalization support (44)B.3Configuration variables (44)B.3.1Setting paper size (44)B.3.2Setting the browsers (45)B.3.3Compilation flags (45)B.3.4Making manuals (45)B.4Setting the shell (45)B.5Using make (45)B.6Using FORTRAN (46)B.6.1Using gfortran (46)B.7Compile and load flags (47)Appendix C Platform notes (49)C.1X11issues (49)C.2Linux (50)C.2.1Intel compilers (51)C.2.2Oracle Solaris Studio compilers (52)C.3FreeBSD (52)C.4(Mac)OS X (53)C.4.164-bit builds (53)C.4.2Snow Leopard (54)C.5Solaris (54)C.5.1Using gcc (56)C.6AIX (57)C.7Cygwin (59)C.8New platforms (59)Appendix D The Windows toolset (61)D.1L A T E X (62)D.2The Inno Setup installer (62)D.3The command line tools (62)D.4The MinGW toolchain (63)D.4.132-bit toolchain (63)D.4.264-bit toolchain (63)D.5Useful additional programs (64)Function and variable index (65)Concept index (66)Environment variable index (67)1Obtaining RSources,binaries and documentation for R can be obtained via CRAN,the“Comprehensive R Archive Network”whose current members are listed at / mirrors.html.1.1Getting and unpacking the sourcesThe simplest way is to download the most recent‘R-x.y.z.tar.gz’file,and unpack it with tar-xf R-x.y.z.tar.gzon systems that have a suitable1tar installed.On other systems you need to have the gzip program installed,when you can usegzip-dc R-x.y.z.tar.gz|tar-xf-The pathname of the directory into which the sources are unpacked should not contain spaces,as most make programs(and specifically GNU make)do not expect spaces.If you want the build to be usable by a group of users,set umask before unpacking so that the files will be readable by the target group(e.g.,umask022to be usable by all users). Keep this setting of umask whilst building and installing.If you use a recent GNU version of 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 usetar--no-same-owner-xf R-x.y.z.tar.gzand perhaps also include the option‘--no-same-permissions’.(These options can also be set in the TAR_OPTIONS environment variable:if more than one option is included they should be separated by spaces.)1.2Getting patched and development versionsA patched version of the current release,‘r-patched’,and the current development version,‘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(2.x.0)version,‘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 ftp://ftp.stat.math.ethz.ch/pub/Software/R/. Download‘R-patched.tar.gz’or‘R-devel.tar.gz’(or the‘.tar.bz2’versions)and unpack as described in the previous section.They are built in exactly the same way as distributions of R releases.1.2.1Using Subversion and rsyncSources are also available via https:///R/,the R Subversion reposi-tory.If you have a Subversion client(see /),you can check out and update the current‘r-devel’from https:///R/trunk/and the current‘r-patched’from‘https:///R/branches/R-x-y-branch/’1 e.g.GNU tar version1.15or later,or that from the‘libarchive’(as used on OS10.6)or‘HeirloomToolchest’distributions.(where x and y are the major and minor number of the current released version of R).E.g., usesvn checkout https:///R/trunk/pathto check out‘r-devel’into directory path(which will be created if necessary). The alpha,beta and RC versions of an upcoming x.y.0release are available from ‘https:///R/branches/R-x-y-branch/’in the four-week period prior to the release.Note that‘https:’is required,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.wget-r or svn export from that URL will not work: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 rsync or downloaded from CRAN.To use rsync to install the appropriate sources for the recommended packages,run./tools/rsync-recommended from the top-level of the R sources.If downloading manually from CRAN,do ensure that you have the correct versions of the recommended packages:if the number in the file‘VERSION’is‘x.y.z’you need to download the contents of‘/src/contrib/dir’,where dir is‘x.y.z/Recommended’for r-devel or‘x.y-patched/Recommended’for r-patched,respec-tively,to directory‘src/library/Recommended’in the sources you have unpacked.After downloading manually you need to execute tools/link-recommended from the top level of the sources to make the requisite links in‘src/library/Recommended’.A suitable in-cantation from the top level of the R sources using wget might be(for the correct value of ‘dir’)wget-r-l1--no-parent-A\*.gz-nd-P src/library/Recommended\/src/contrib/dir./tools/link-recommended2Installing R under Unix-alikesR will configure and build under most common Unix and Unix-alike platforms including ‘cpu-*-linux-gnu’for the‘alpha’,‘arm’,‘hppa’,‘ix86’,‘ia64’,‘m68k’,‘mips’,‘mipsel’,‘powerpc’,‘s390’,‘sparc’,and‘x86_64’CPU s,‘i386-apple-darwin’,‘x86_64-apple-darwin’,‘i386-sun-solaris’,‘sparc-sun-solaris’,‘x86_64-*-freebsd’,and‘powerpc-ibm-aix6*’as well as perhaps(it is tested less frequently on these platforms)‘powerpc-apple-darwin’,‘i386-*-freebsd’,‘i386-*-netbsd’and‘i386-*-openbsd’.In addition,binary distributions are available for some common Linux distributions and for OS X(formerly Mac OS).See the FAQ for current details.These are installed in platform-specific ways,so for the rest of this chapter we consider only building from the sources.2.1Simple compilationFirst review the essential and useful tools and libraries in Appendix A[Essential and useful other programs under a Unix-alike],page34,and install those you want or need.Ensure that the environment variable TMPDIR is either unset(and‘/tmp’exists and can be written in and scripts can be executed from)or points to a valid temporary directory(one from which execution of scripts is allowed).Choose a place 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 R HOME.Untar the source code. This should create directories‘src’,‘doc’,and several more under a top-level directory: change to that top-level directory(At this point North American readers should consult Section B.3.1[Setting paper size],page44.)Issue the following commands: ./configuremake(See Section B.5[Using make],page45if your make is not called‘make’.) Then check the built system works correctly bymake checkFailures are not necessarily problems as they might be caused by missing functionality,1 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 C locales and non-UTF-8non-Western-European locales.)A failure in‘tests/ok-errors.R’may indicate inadequate resource limits(see Chapter5[Running R],page18).More comprehensive testing can be done bymake check-develormake check-allsee file‘tests/README’.If the command configure and make commands execute successfully,a shell-script front-end called‘R’will be created and copied to‘R_HOME/bin’.You can copy this script to a place 1for example,if you configured R with‘--without-recommended’.where users can invoke it,for example to‘/usr/local/bin/R’.You could also copy the man page‘R.1’to a place where your man reader finds it,such as‘/usr/local/man/man1’. If you want to install the complete R tree to,e.g.,‘/usr/local/lib/R’,see Section2.4 [Installation],page6.Note:you do not 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,‘TOP_SRCDIR’).To build in‘BUILDDIR’,runcd BUILDDIRTOP_SRCDIR/configuremakeand 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 GNU make to allow this,and the pathname of the build directory should not contain spaces.)Now rehash if necessary,type R,and read the R manuals and the R FAQ(files‘FAQ’or ‘doc/manual/R-FAQ.html’,or /doc/FAQ/R-FAQ.html which always has the version for the latest release of R).2.2Help optionsBy 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 configure option‘--enable-prebuilt-html’.Whether R CMD INSTALL(and hence install.packages)pre-builds HTML pages is determined by looking at the R installation and is reported by R CMD INSTALL--help:it can be overridden by specifying one of the INSTALL options‘--html’or‘--no-html’.The server is disabled by setting the environment variable R_DISABLE_HTTPD to a non-empty value,either before R is started or within the R session before HTML help(including 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 ?tools::startDynamicHelp for more details.2.3Making the manualsThere is a set of manuals that can be built from the sources,‘refman’Printed versions of the help pages for the base packages.‘fullrefman’Printed versions of all the help pages for base and recommended packages(over3200pages).‘R-FAQ’R FAQ‘R-intro’“An Introduction to R”.‘R-data’“R Data Import/Export”.‘R-admin’“R Installation and Administration”,this manual.‘R-exts’“Writing R Extensions”.‘R-lang’“The R Language Definition”.To make these(except‘fullrefman’),usemake dvi to create DVI versionsmake pdf to create PDF versionsmake info to create info files(not‘refman’).You will not be able to build any of these unless you have makeinfo version4.7or later installed,and for DVI or PDF you must have texi2dvi and‘texinfo.tex’installed(which are part of the GNU texinfo distribution but are,especially‘texinfo.tex’,often made part of the T E X package in re-distributions).The DVI versions can be previewed and printed using standard programs such as xdvi and dvips.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 GNU info program.The DVI and PDF versions will be created using the paper size selected at configuration(default ISO a4):this can be overridden by setting R_PAPERSIZE on the make command line,or setting R_PAPERSIZE in the environment and using make-e.(If re-making the manuals for a different paper size,you should first delete the file‘doc/manual/version.texi’.)There are some issues with making the reference manual,and in particular with the PDF version‘refman.pdf’.The help files contain both ISO Latin1characters(e.g.in‘text.Rd’) and upright quotes,neither of which are contained in the standard L A T E X Computer Modern fonts.We have provided four alternatives:times(The default for PDF.)Using standard PostScript fonts.This works well both for on-screen viewing and for printing.One disadvantage is that the Usageand Examples sections may come out rather wide(and R2.14.0will haveworkarounds for this).Note that in most L A T E X installations this will not actually use the standardfonts for PDF,but rather embed the URW clones NimbusRom,NimbusSansand(for Courier,if used)NimbusMon.lm Using the Latin Modern fonts.These are not often installed as part of a T E X dis-tribution,but can obtained from /tex-archive/fonts/ps-type1/lm/and mirrors.This uses fonts rather similar to Computer Modern,but is not so good on-screen as times.cm-super Using type-1versions of the Computer Modern fonts by Vladimir Volovich.This is a large installation,obtainable from /tex-archive/fonts/ps-type1/cm-super/and its mirrors.These type-1fonts have poorhinting and so are nowhere near so readable on-screen as the other three options. ae(The default for DVI.)A package to use composites of Computer Modern fonts.This works well most of the time,and its PDF is more readable on-screen thanthe previous two options.There are three fonts for which it will need to usebitmapped fonts,‘tctt0900.600pk’,‘tctt1000.600pk’and‘tcrm1000.600pk’.Unfortunately,if those files are not available,Acrobat Reader will substitutecompletely incorrect glyphs so you need to examine the logs carefully.The default can be overridden by setting the environment variables R_RD4PDF and R_RD4DVI.(On Unix-alikes,these will be picked up at install time and stored in ‘etc/Renviron’,but can still be overridden when the manuals are built.)The default value for R_RD4PDF is‘times,hyper’:omit‘hyper’if you do not want hyperlinks,e.g.for printing.The default for R_RD4DVI is‘ae’.2.4InstallationTo ensure that the installed tree is usable by the right group of users,set umask appropriately (perhaps to‘022’)before unpacking the sources and throughout the build process.After./configuremakemake check(or,when building outside the source,TOP_SRCDIR/configure,etc)have been completed successfully,you can install the complete R tree to your system by typingmake installA parallel make can be used(but run make all first).This will install to the following directories:‘prefix/bin’or‘bindir’the front-end shell script and other scripts and executables‘prefix/man/man1’or‘mandir/man1’the man page‘prefix/LIBnn/R’or‘libdir/R’all the rest(libraries,on-line help system,...).Here LIBnn is usually‘lib’,but may be‘lib64’on some64-bit Linux systems.This is known as the Rhome directory.where prefix is determined during configuration(typically‘/usr/local’)and can be set by running configure with the option‘--prefix’,as in./configure--prefix=/where/you/want/R/to/goThis causes make install to install the R script to‘/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 configure.You can install into another directory tree by using make prefix=/path/to/here installat least with GNU make(and current Solaris and FreeBSD make,but not some older Unix makes).More precise control is available at configure time via options:see configure--help for details.(However,most of the‘Fine tuning of the installation directories’options are not used by R.)Configure options‘--bindir’and‘--mandir’are supported and govern where a copy of the R script and the man page are installed.The configure option‘--libdir’controls where the main R files are installed:the default is‘eprefix/LIBnn’,where eprefix is the prefix used for installing architecture-dependent files,defaults to prefix,and can be set via the configure option‘--exec-prefix’.Each of bindir,mandir and libdir can also be specified on the make install command line(at least for GNU make).The configure or make variables rdocdir and rsharedir can be used to install the system-independent‘doc’and‘share’directories to somewhere other than libdir. The C header files can be installed to the value of rincludedir:note that as the headers are not installed into a subdirectory you probably want something like rincludedir=/usr/local/include/R-2.13.2.If you want the R home to be something other than‘libdir/R’,use‘rhome’:for example make install rhome=/usr/local/lib64/R-2.13.0will use a version-specific R home on a Linux64-bit system.If you have made R as a shared/dynamic library you can install it in your system’s library directory bymake prefix=/path/to/here install-libRwhere prefix is optional,and libdir will give more precise control.make install-stripwill install stripped executables,and on platforms where this is supported,stripped libraries in directories‘lib’and‘modules’and in the standard packages.Note that installing R into a directory which contains spaces is not supported,and at least some aspects(such as installing source packages)will not work.To install DVI,info and PDF versions of the manuals,use one or more of make install-dvimake install-infomake install-pdfOnce again,it is optional to specify prefix,libdir or rhome(the DVI and PDF manuals are installed under the R home directory).(make install-info needs Perl installed if there is no command install-info on the system.)More precise control is possible.For info,the setting used is that of infodir(default ‘prefix/info’,set by configure option‘--infodir’).The DVI and PDF files are installed into the R‘doc’tree,set by the make variable 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 prefix(and so on) should reflect the final destination,and DESTDIR should be used:see / prep/standards/html_node/DESTDIR.html.You can optionally install the run-time tests that are part of make check-all by make install-testswhich populates a‘tests’directory in the installation.2.5UninstallationYou can uninstall R bymake uninstalloptionally specifying prefix etc in the same way as specified for installation.This will also uninstall any installed manuals.There are specific targets to uninstall DVI,info and PDF manuals in file‘doc/manual/Makefile’.Target uninstall-tests will uninstall any installed tests,as well as removing the di-rectory‘tests’containing the test results.2.6Sub-architecturesSome platforms can support closely related builds of R which can share all but the exe-cutables and dynamic objects.Examples include builds under Solaris for different chips(in particular,32-and64-bit builds),64-and32-bit builds on‘x86_64’Linux and different CPU s(e.g.‘ppc’,‘i386’and‘x86_64’)under(Mac)OS X>=10.4.R supports the idea of architecture-specific builds,specified by adding‘r_arch=name’to the configure line.Here name can be anything non-empty,and is used to name subdi-rectories of‘lib’,‘etc’,‘include’and the package‘libs’subdirectories.Example names from other systems are the use of‘sparcv9’on Sparc Solaris and‘32’by gcc on‘x86_64’Linux.If you have two or more such builds you can install them over each other(and for32/64-bit builds on one architecture,one build can be done without‘r_arch’).The space savings can be considerable:on‘x86_64’Linux a basic install(without debugging symbols)took 63Mb,and adding a32-bit build added6Mb.If you have installed multiple builds you can select which build to run byR--arch=nameand just running‘R’will run the last build that was installed.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 configure script or a‘src/Makefile’file.In such cases you can install for extra builds byR--arch=name CMD INSTALL--libs-only pkg(s)If you want to mix sub-architectures compiled on different platforms(for example ‘x86_64’Linux and‘i686’Linux),it is wise to use explicit names for each,and you may also need to set‘libdir’to ensure that they install into the same place.When sub-architectures are used the version of Rscript in e.g.‘/usr/bin’will be the last installed,but architecture-specific versions will be available in e.g.‘/usr/lib64/R/bin/exec${R_ARCH}’.Normally all installed architectures will run on the platform so the architecture of Rscript itself does not matter.The executable Rscript will run the R script,and at that time the setting of the R_ARCH environment variable determines the architecture which is run.When running post-install tests with sub-architectures,useR--arch=name CMD make check[-devel|all]to select a sub-architecture to check.Sub-architectures are also used on Windows,but by selecting executables within the appropriate‘bin’directory,‘R_HOME/bin/i386’or‘R_HOME/bin/x64’.For backwards compatibility with R<2.12.0,there are executables‘R_HOME/bin/R.exe’or ‘R_HOME/bin/Rscript.exe’:these will run an executable from one of the subdirectories, which one being taken first from the R_ARCH environment variable,then from the‘--arch’command-line option2and finally from the installation default(which is32-bit for a combined32/64bit R installation).2.6.1MultilibOn Linux,there is an alternative mechanism for mixing32-bit and64-bit libraries known as multilib.If a Linux distribution supports multilib,then parallel builds of R may be installed in the sub-directories‘lib’(32-bit)and‘lib64’(64-bit).The build to be run may then be chosen using the setarch command.For example,a32-bit build may be chosen by setarch i686RThe setarch command is only operational if both32-bit and64-bit builds are installed. If there is only one installation of R,then this will always be run regardless of the architec-ture specified by the setarch command.There can be problems with installing packages on the non-native architecture.It is a good idea to run e.g.setarch i686R 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).At present there is a potential problem with packages using Java,as the post-install for a‘i386’RPM on‘x86_64’Linux reconfigures Java and will find the‘x86_64’Java.If you know where a32-bit Java is installed you may be able to run(as root)export JAVA_HOME=<path to jre directory of32-bit Java>setarch i686R CMD javareconfto get a suitable setting.When this mechanism is used,the version of Rscript in e.g.‘/usr/bin’will be the last installed,but an architecture-specific version will be available in e.g.‘/usr/lib64/R/bin’. Normally all installed architectures will run on the platform so the architecture of Rscript does not matter.2.7Testing an InstallationFull testing is possible only if the test files have been installed withmake install-testswhich populates a‘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 R.home())and runcd tests##followed by one of../bin/R CMD make check../bin/R CMD make check-devel2with possible values‘i386’,‘x64’,‘32’and‘64’.../bin/R CMD make check-alland other useful targets are test-BasePackages and test-Recommended to the 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 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 BLAS(see Section A.3.1.5[Shared BLAS],page40).Alternatively,the installed R can be run,preferably with‘--vanilla’.Then library("tools")testInstalledBasic("both")testInstalledPackages(scope="base")testInstalledPackages(scope="recommended")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‘tests’folder of the R home directory and run slightly fewer tests than the first approach:in particular they do not test Internet access.These tests work best if diff(in‘Rtools*.exe’for Windows users)is in the path,and on some systems need the collation locale set manually(the R code tries to do so but it may not be possible to reset it):so if needed try setting the environment variable LC_COLLATE to‘C’before starting R.It is possible to test the installed packages(but not the package-specific tests)by testInstalledPackages even if make install-tests was not run.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 settingLANGUAGE=en LC_TIME=C2.8Byte-compilerR2.13.0introduced a new‘byte’compiler which compiles R code to a‘byte code’represen-tation.This is by default not used,but is available for experimentation.To compile all the base and recommended packages,runmake bytecodein the top-level build directory.This will build(or re-build)R in the normal way,then compile the package code(which for the recommended packages entails a complete re-install of the package from the tarball).To update R,set the environment variables R_COMPILE_PKGS=1R_COMPILER_SUPPRESS_ALL=1before re-running make.It is however recommended that experimentation is done in the R-devel version of R, which has an updated version of the byte-compiler and more facilities to use it.。