INSTALL 8.71 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1
Installing pqR on a Unix/Linux system
Radford Neal's avatar
Radford Neal committed
2

Radford Neal's avatar
Radford Neal committed
3 4 5 6 7
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.
Radford Neal's avatar
Radford Neal committed
8

Radford Neal's avatar
Radford Neal committed
9 10 11
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.
Radford Neal's avatar
Radford Neal committed
12

Radford Neal's avatar
Radford Neal committed
13 14 15 16 17
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.
Radford Neal's avatar
Radford Neal committed
18 19


Radford Neal's avatar
Radford Neal committed
20
Configuring pqR
Radford Neal's avatar
Radford Neal committed
21

Radford Neal's avatar
Radford Neal committed
22
After uncompressing and unpacking the tar archive (with a command such
23 24
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
Radford Neal's avatar
Radford Neal committed
25 26 27
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.
Radford Neal's avatar
Radford Neal committed
28

Radford Neal's avatar
Radford Neal committed
29
You should then enter the build directory, and issue the command:
Radford Neal's avatar
Radford Neal committed
30

Radford Neal's avatar
Radford Neal committed
31
    path-to-source-directory/configure
Radford Neal's avatar
Radford Neal committed
32

Radford Neal's avatar
Radford Neal committed
33
where "path-to-source-directory" is the path to the source directory,
34
perhaps something like "../pqR-2014-11-16".
Radford Neal's avatar
Radford Neal committed
35

Radford Neal's avatar
Radford Neal committed
36 37 38 39 40
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".
Radford Neal's avatar
Radford Neal committed
41

Radford Neal's avatar
Radford Neal committed
42
You can get a list of configuration options with
Radford Neal's avatar
Radford Neal committed
43

Radford Neal's avatar
Radford Neal committed
44
    path-to-source-directory/configure --help
Radford Neal's avatar
Radford Neal committed
45

Radford Neal's avatar
Radford Neal committed
46 47
These options are discussed in the R-admin manual.  The ones most
likely to be useful are as follows:
Radford Neal's avatar
Radford Neal committed
48

Radford Neal's avatar
Radford Neal committed
49
    --disable-helper-threads
Radford Neal's avatar
Radford Neal committed
50

Radford Neal's avatar
Radford Neal committed
51 52 53 54 55
        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.
Radford Neal's avatar
Radford Neal committed
56

Radford Neal's avatar
Radford Neal committed
57
    --disable-byte-compiled-packages
Radford Neal's avatar
Radford Neal committed
58

Radford Neal's avatar
Radford Neal committed
59 60 61 62 63 64 65 66 67 68 69 70
        Disables byte compilation for the builtin and recommended 
        packages built along with pqR.  This does not affect whether
        packages installed later are byte compiled.  It is not clear
        whether or not byte compilation is desirable in pqR, since
        it speeds up some operations, but does not support some of
        pqR's speed improvements.

    --enable-R-shlib

        Build R as a shared library.  This is necessary if you want to
        use RStudio.

71
    -- with-blas  or   --with-blas=...
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93

        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
94 95
        with the one supplied with pqR), rather than the C routines
        built into pqR.  Your BLAS may be faster than the built-in C
96 97 98 99 100 101 102 103 104 105 106 107 108 109
        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).

Radford Neal's avatar
Radford Neal committed
110 111 112 113 114 115 116
    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.
 
    CC=...
117
    CXX=...
Radford Neal's avatar
Radford Neal committed
118 119 120
    FC=...
    F77=...

121 122 123 124
        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:
Radford Neal's avatar
Radford Neal committed
125

126 127 128 129
          CC='gcc -std=gnu99'
          CXX='g++'
          FC='gfortran'
          F77='gfortran'
Radford Neal's avatar
Radford Neal committed
130

131 132
        Adding a -m32 option (eg, CC='gcc -m32 -std=gnu99') may be
        useful to compile in 32-bit mode on a 64-bit system.
Radford Neal's avatar
Radford Neal committed
133 134

    CFLAGS=...
135 136
    CXXFLAGS=...
    FCFLAGS=...
Radford Neal's avatar
Radford Neal committed
137 138 139 140 141 142 143
    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 -DENABLE_ISNAN_TRICK'
144 145
          CXXLAGS='-g -O2 -mtune=native'
          FCLAGS='-g -O2 -mtune=native'
Radford Neal's avatar
Radford Neal committed
146 147 148 149
          FFLAGS='-g -O2 -mtune=native'

        For a 32-bit build, adding the -mfpmath=sse option is probably
        desirable (unless you have a very old processor, Pentium III
150
        or earlier, that lacks the SSE2 instructions).
Radford Neal's avatar
Radford Neal committed
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188


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
189 190 191 192 193 194 195 196
commands, because floating-point round-off errors and sizes of objects
differ from one computer to another (including 32-bit versus 64-bit
builds), because the exact form of error messages may differ depending
on whether a package was byte compiled or not, 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.
Radford Neal's avatar
Radford Neal committed
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228


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 /usr/local, 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

229 230 231 232 233
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".