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".