INSTALL 9.23 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

3 4
(For installing pqR on a MS Windows system, see src/gnuwin32/INSTALL)

Radford Neal's avatar
Radford Neal committed
5 6 7 8 9
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
10

Radford Neal's avatar
Radford Neal committed
11 12 13
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
14

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

21 22 23 24
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.

Radford Neal's avatar
Radford Neal committed
25

Radford Neal's avatar
Radford Neal committed
26
Configuring pqR
Radford Neal's avatar
Radford Neal committed
27

Radford Neal's avatar
Radford Neal committed
28
After uncompressing and unpacking the tar archive (with a command such
29 30
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
31 32 33
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
34

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

Radford Neal's avatar
Radford Neal committed
37
    path-to-source-directory/configure
Radford Neal's avatar
Radford Neal committed
38

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

Radford Neal's avatar
Radford Neal committed
42 43 44 45 46
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
47

Radford Neal's avatar
Radford Neal committed
48
You can get a list of configuration options with
Radford Neal's avatar
Radford Neal committed
49

Radford Neal's avatar
Radford Neal committed
50
    path-to-source-directory/configure --help
Radford Neal's avatar
Radford Neal committed
51

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

55 56 57 58 59
    --enable-R-shlib

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

Radford Neal's avatar
Radford Neal committed
60
    --disable-helper-threads
Radford Neal's avatar
Radford Neal committed
61

Radford Neal's avatar
Radford Neal committed
62 63 64 65 66
        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
67

68
    --enable-compressed-pointers
Radford Neal's avatar
Radford Neal committed
69

70 71 72 73 74 75
        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.
Radford Neal's avatar
Radford Neal committed
76

77
    --with-blas  or   --with-blas=...
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99

        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
100 101
        with the one supplied with pqR), rather than the C routines
        built into pqR.  Your BLAS may be faster than the built-in C
102 103 104 105 106 107 108 109 110 111 112 113 114 115
        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
116 117 118 119 120
    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.
121 122 123 124 125 126 127 128 129

    --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.
Radford Neal's avatar
Radford Neal committed
130 131
 
    CC=...
132
    CXX=...
Radford Neal's avatar
Radford Neal committed
133 134 135
    FC=...
    F77=...

136 137 138 139
        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
140

141 142 143 144
          CC='gcc -std=gnu99'
          CXX='g++'
          FC='gfortran'
          F77='gfortran'
Radford Neal's avatar
Radford Neal committed
145

146 147
        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
148 149

    CFLAGS=...
150 151
    CXXFLAGS=...
    FCFLAGS=...
Radford Neal's avatar
Radford Neal committed
152 153 154 155 156 157
    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:

158 159 160 161
          CFLAGS='-g -O2 -mtune=native'
          CXXFLAGS='-g -O2 -mtune=native'
          FCFLAGS='-g -O3 -mtune=native'
          FFLAGS='-g -O3 -mtune=native'
Radford Neal's avatar
Radford Neal committed
162 163 164

        For a 32-bit build, adding the -mfpmath=sse option is probably
        desirable (unless you have a very old processor, Pentium III
165
        or earlier, that lacks the SSE2 instructions).
Radford Neal's avatar
Radford Neal committed
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203


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
204 205 206 207 208 209
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.
Radford Neal's avatar
Radford Neal committed
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241


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

242 243 244 245 246
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".