Installing pqR on a Unix/Linux system (For installing pqR on a MS Windows system, see src/gnuwin32/INSTALL) This document describes how to build and install pqR from a tar archive of the source, as distributed at pqR-project.org. If you are building pqR from a download of a development version from the repository at https://github.com/radfordneal/pqR, see the note at the end of this document. More detailed information on installation is in the "R Installation and Administration Manual", an HTML copy of which is in the source directory, at doc/html/R-admin.html. Readers familiar with the process of installing versions of R distributed by the R Core Team (from source) should note that the process for pqR is basically the same. However, there are some configuration options specific to pqR that you may wish to set, as described below, and in the R-admin manual. The instructions here are for Linux or Unix (including Mac OS X and Solaris). See src/gnuwin32/INSTALL for instructions on installing pqR on Microsoft Windows systems. Configuring pqR After uncompressing and unpacking the tar archive (with a command such as "tar xf pqR-2014-11-16.tar.gz"), you should make a directory in which to build pqR, such as "pqR-2014-11-16-myconfig". It is possible to instead build pqR in the source directory, but using a separate directory is preferable, so that the source directory says clean, and so that you can create more than one configuration if desired. You should then enter the build directory, and issue the command: path-to-source-directory/configure where "path-to-source-directory" is the path to the source directory, perhaps something like "../pqR-2014-11-16". The configure command will produce a lot of output regarding the results of checks for various system facilities, and end (if successful) with a summary of the features of this configuration. These features are partly determined by the available system facilities, and partially by options you can give to "configure". You can get a list of configuration options with path-to-source-directory/configure --help These options are discussed in the R-admin manual. The ones most likely to be useful are as follows: --enable-R-shlib Build R as a shared library. This is necessary if you want to use RStudio. --disable-helper-threads This disables use of "helper threads" to do some operations in parallel. Specifying this options is desirable if your computer does not have multiple processors, multiple cores, or hyperthreading. It is necessary if your system does not support the OpenMP facility. --enable-compressed-pointers Builds pqR with compressed pointers rather than pointers that are machine addresses. This slows the interpreter by up to about 40%, but reduces memory usage (and increases speed for some memory-intensive operations). It is possible but mostly pointless for a 32-bit build, since the compressed and uncompressed pointers are then the same size. --with-blas or --with-blas=... Used to specify that an external BLAS package should be used rather than the built-in BLAS supplied with pqR. See R-admin for details. BLAS_in_helpers=TRUE Specify this option if you use the --with-blas option to link to BLAS routines other the ones built into pqR, and these routines are thread-safe, and hence may be run in parallel. This is the default if no --with-blas argument is specified, since the BLAS routines supplied with pqR are thread-safe, but an external BLAS is assumed to not be thread-safe if this option is not given. You might need BLAS_in_helpers=FALSE if you're not specifying an external BLAS now, but might later substitute a non-thread-safe BLAS (as is possible if the BLAS is a shared library, as it is by default). mat-mult-with-BLAS=TRUE Specify this if by default you want matrix multiply operations in R code to always be done with whatever BLAS you supply (or with the one supplied with pqR), rather than the C routines built into pqR. Your BLAS may be faster than the built-in C routines, but on the other hand, the built-in C routines guarantee that NA, Inf, etc. are propagated correctly, and will pipeline output to other operations when run in parallel. This option specifies only the default, which can be changed using "options" (see help("%*%") and help(options) for details). Note that matrix multiplies done as part of other operations are always done with the BLAS. The default setting for this option is FALSE if no --with-blas argument is given to configure, and NA if --with-blas is specified. A value of NA specifies that the BLAS routines should only be used for large matrix-matrix multiplies, and only if the operands do not have elements that are NA or NaN (see help("%*%") for details). R_PAPERSIZE=letter Sets the default paper size to 8 1/2 by 11 inch letter size. The default is A4, appropriate for Europeans, but probably not North Americans. --enable-byte-compiled-packages Enables byte compilation for the builtin and recommended packages built along with pqR. This does not affect whether packages installed later are byte compiled. Byte compilation is undesirable in pqR, since it does not support some of pqR's speed improvements. See library(compiler); help(compile) for further information. CC=... CXX=... FC=... F77=... Specifies which compilers to use for C, C++, Fortran 90/95, and Fortran 77. Suitable compilers may be chosen automatically, but the GNU compilers can be specified as follows: CC='gcc -std=gnu99' CXX='g++' FC='gfortran' F77='gfortran' Adding a -m32 option (eg, CC='gcc -m32 -std=gnu99') may be useful to compile in 32-bit mode on a 64-bit system. CFLAGS=... CXXFLAGS=... FCFLAGS=... FFLAGS=... Sets the compiler flags for C and Fortran. If the GNU compilers are used with an Intel/AMD 64-bit processor, the following flags are recommended: CFLAGS='-g -O2 -mtune=native' CXXFLAGS='-g -O2 -mtune=native' FCFLAGS='-g -O3 -mtune=native' FFLAGS='-g -O3 -mtune=native' For a 32-bit build, adding the -mfpmath=sse option is probably desirable (unless you have a very old processor, Pentium III or earlier, that lacks the SSE2 instructions). Compiling pqR Once you have run the "configure" script, you can compile pqR, and make all the base and recommended packages, with the command make This will take a while, and produce lots of output, which might contain some meaningful error or warning messages (though some warnings are normal). The above "make" command will make HTML versions of the manuals (placing them in doc/manual). You can optionally make PDF or GNU info versions of the manuals using either or both of the following commands: make pdf make info However, making these versions requires additional system facilities which you might not have available. See the section on "Making the manuals" in the R-admin manual for details. Checking that pqR works correctly After compiling pqR, you can check that it works with the command make check More extensive checks, including of the recommended packages, can be run with make check-all Some discrepancies are typically shown in the output of these commands, because accuracy of functions such as sin differs from one computer to another, because the exact form of error messages may change, and because some output depends on the current date, the set of files present, etc. However, any report of "ERROR" or "FAILED" that appears indicates a problem, except if it is due to lack of internet access, or to running the checks in a C/POSIX locale. Running and installing pqR For compatibility with other R releases, the script to run pqR is called "R", not "pqR". After compiling pqR as described above, you can run it, without any further installation steps, using the command path-to-build-directory/bin/R or just "bin/R" if you are currently in the build directory. Other standard R commands such as Rscript can be run similarly. To install pqR in system directories, use the commands make install make install-pdf make install-info or some subset of them. By default, these install to the subdirectory R of your home directory (on Linux), but this can be changed using the --prefix configure option. For more details, see the R-admin manual. Building pqR from a development version If you download a version of pqR from the source code repository that is not a release version, you should first, in the source directory, run the command ./create-configure If this succeeds (it may not if you lack some system facilities), you can then proceed as described above. However, note that the release date may not be set to anything meaningful. Also, the descriptions of the modifications done to create pqR will be in files in the "mods" directory, rather than the single file "MODS".