


	UCS INSTALLATION GUIDE



This guide is intended to provide some help when the UCS installation 
does not work out of the box as described in the README file.



CONTENTS

  1. Install.perl Options
  2. Missing Prerequisites
  3. Installation on Win32 / Cygwin [experimental]



1. Install.perl OPTIONS

The UCS auto-configuration script "System/Install.perl" accepts a number of
command-line options, which are mainly used to provide hints to the script
when auto-detection (e.g. of helper applications) fails.  Usage of these
options is described in Section 2 (MISSING PREREQUISITES) below.  Type

  perl System/Install.perl --help

for an option summary.  Note that there is no option to specify a particular
Perl interpreter to be used by UCS.  Simply run "Install.perl" with the
desired Perl interpreter, e.g.

  /usr/local/bin/perl5.8.1 System/Install.perl



2. MISSING PREREQUISITES

The auto-configuration script will abort with an error message unless all
prerequisites are fulfilled.  In the case of some optional modules and helper
applications, it will ask the user whether to proceed with the installation.
It is safe to answer "yes" here, although some functionality will not be
available.

Each of the subsections below discusses on of the mandatory requirements,
starting with the error message printed by the auto-configuration script,
and followed by installation tips and relevant command-line options of
"Install.perl". 


2.1. Perl version 5.6.1 or newer

``Perl version error: ... . Aborted.''

The UCS/Perl code relies on the built-in functionality of Perl v5.6.1, some of
which may not be available in earlier versions.  If you are running an older
version of Perl, please upgrade to the latest release (which will give you the
additional benefit of Unicode support) or ask your system administrator to do
so.  On some systems (most notably SUN Solaris), the "standard" Perl
interpreter ("/usr/bin/perl") may be seriously out of date, while a recent
version is installed in a different location (e.g. "/usr/local/bin/perl"). 
In this case, be sure to run "Install.perl" with the correct Perl
interpreter.  A specific version of Perl can usually be selected by adding
the version number to the program name.  For instance, if you know that Perl
v5.8.1 is installed somewhere on your system, type

  perl5.8.1 System/Install.perl

and installation should work properly.


2.2. Required Perl modules

``Error: one or more modules required by UCS are not installed on your system.''

This error message is followed by a listing of the missing Perl modules.  The
modules listed here are absolutely mandatory for normal operation of UCS/Perl
and must be installed before the UCS system can be used.

There are three options for installing Perl modules:

 1. Ask your system administrator to install the necessary modules, 
    as listed by the auto-configuration script.

 2. If you have root access (or write access to the global Perl library
    directories, at least), you can easily install modules with the "cpan"
    script or by typing
 
      perl -MCPAN -e shell

    This will enter an interactive installation program.  For each of the
    missing prerequisites, type

      module <ModuleName>

    to display information about the module and

      install <ModuleName>

    to install it on your system.

 3. As a last resort, you can try to install modules manually.  Point your
    web browser at "http://www.cpan.org/", locate the required modules, and
    download them.  Each module will come as a GZipped Tar archive.
    Uncompress this archive in a temporary directory and follow the
    instructions in the "README" and/or "INSTALL" files.  Since you cannot
    install the modules in the global Perl library directories (if you can,
    you should use "cpan" to install modules), you must find out from the
    Perl (or module) documentation how to install in a "local" directory
    instead.  A quick'n'dirty hack is the following solution:

      - Create a directory "~/perl5lib/" (or a similar name) in your home 
        directory.
      - Instead of typing "make install" for the module, copy the contents
        of "blib/lib" and "blib/arch" to "~/perl5lib", including all
        subdirectories. 
      - You should now be able to use the module, but you have to tell the
        Perl interpreter about your local library directories.

          perl -I ~/perl5lib/lib -I ~/perl5lib/arch -e 'use <ModuleName>'

If the modules are installed in a local library directory rather than Perl's
standard tree (solution 3 above), you must specify the additional library
directories with the "-I" option when you invoke the auto-configuration
script:

  perl System/Install.perl -I ~/perl5lib/lib -I ~/perl5lib/arch

(note the blank between "-I" and the directory name, and that the
configuration options have to be given after "Install.perl").


2.3. R version 1.6 or newer

``Error: Couldn't find R program in your search path.''
``Error: Can't run the R interpreter''
``Error: R interpreter (version ...) is too old (1.6 or newer required)''

R is a programming language and interactive environment for statistical
computation.  The R interpreter is an integral part of the UCS system.  It is
the basis of the UCS/R subsystem, but it is also used extensively by UCS/Perl
as a library of special functions and statistical distributions.  R is still
evolving rapidly so there may be subtle incompatibilities in older versions.

When you get one of the error messages above, it usually means that R has not
been installed on your system (or perhaps a version that is seriously out of
date by now).  Download the latest version of R from the homepage at
"http://www.r-project.org/" (where pre-compiled binary packages are available
for all major operating systems) and install it, or ask your system
administrator to do so.  

If you do not have root access, you may need to install R in a "local"
directory.  In this case, "Install.perl" will not be able to auto-detect the R
interpreter.  One solution is to copy ("cp -p") or link ("ln -s") the
interpreter (a program with the name "R") into some directory in your search
path ("~/bin" is often included by default), where it can be auto-detected.
Otherwise, specify the full path to the interpreter with the "-R" switch.  For
instance, if the R distribution is installed under "/usr/local/lib/R", the
pathname of the interpreter itself should be "/usr/local/lib/R/bin/R".  Run
the auto-configuration script with

  perl System/Install.perl -R /usr/local/lib/R/bin/R

or simply specify the base directory of the R distribution:

  perl System/Install.perl -rh /usr/local/lib/R/bin/R


2.4. Optional modules and helpers

If one or more of the optional Perl modules are missing, the
auto-configuration script will issue a warning and ask you whether to proceed
with the installation.  If you want to make use of all the features of
UCS/Perl, answer "no" and install the missing items.

In order to install the optional Perl modules, proceed as described in
Section 2.2 above (and don't forget to use the "-I" option when the modules
are installed in a "local" directory). 

UCS/Perl uses the "a2ps" program to format data sets in PostScript for
printing.  This tool should be shipped together with any decent distribution
of a Unix-like operating system, but you may need to install it separately
using the package manager of your distribution.  If you cannot find a
pre-compiled version of "a2ps", ask your vendor or system administrator.


2.5. Installing UCS without the prerequisites

UCS/Perl really, really needs the mandatory prerequisites to run smoothly (and
there's little point in trying to use UCS/R without an R interpreter).  If you
are absolutely certain that you want to go ahead without them, you can
tell "Install.perl" to skip all tests with the "--force" option:

  perl System/Install.perl --force

Be warned that you do this entirely AT YOUR OWN RISK, and expect to encounter
all kinds of problems. 



3. INSTALLATION ON Win32 / CYGWIN

Before you read any further, please consider replacing Windows with a DECENT
operating system.  Bill Gates has enough money without your help.

This version of the UCS system includes experimental support for Win32 through
the Cygwin emulation layer.  At the moment, this option is not suitable for
inexperienced users, as there are many pitfalls that you may have to work
around.  You should at least be familiar with the Windows file system and the
Cygwin environment, and you need to know the difference between a Cygwin shell
and your good old MS-DOS window.

ActivePerl for Windows is NOT supported.


3.1. Installing prerequisites

First of all, you need to install the Cygwin environment, which you can
download from "http://www.cygwin.com/".  During the installation procedure,
you will be asked to select various software packages.  Make sure that "perl"
and "a2ps" are selected.  You should now be able to open a shell window by
clicking on the "Cygwin" icon.  Type "perl -v" and "a2ps --version" to verify
the installation.

The Cygwin distribution doesn't include all required Perl modules, but they
can easily be installed with the "cpan" script (see Section 2.2 above).  When
you run "cpan" for the first time, you will probably asked to complete the
configuration.  In most cases, it is safe to accept the default settings.
You should at least install the "Expect" and "Term::ReadKey" modules (both of
which are unproblematic).  

Unfortunately, the latest versions of Perl/Tk are broken under Cygwin.  You
may be able to compile and install one of the older versions, but you have to
install and run an X server first (XFree86 is available as part of the Cygwin
distribution).  Search Google for more information.  At the moment, Perl/Tk is
only used by the documentation viewer, so it isn't really worth the trouble.

A pre-compiled Windows version of R can be downloaded from the R homepage at
"http://www.r-project.org/".  It seems to be a native Win32 version, which
does not use the Cygwin emulation layer.  This incompatibility is a major
source of problems, although UCS/Perl makes a serious effort to work around
them and communicate successfully with R.


3.2. Unpacking UCS

Unpack the UCS distribution somewhere in the normal Cygwin directory tree
(i.e. the root file system mounted on "/"), not on a Windows disk drive
(e.g. "C:", which is mounted under "/cygdrive/c").  Please stay away from
directory paths that contain whitespace or other special characters!  These
are quite likely to confuse some part or other of the UCS system.

During auto-configuration, UCS will try to locate your Cygwin installation on
one of the Windows disk drives, where the Windows version of R can access the
library and data files. 

Don't worry if "tar" spits out one or two error messages while unpacking the
data (the first message should read ``cannot create symbolic link ...'').
This is due to an impoverished file system that cannot distinguish between
uppercase and lowercase, but it should not cause any problems for the UCS
installation.


3.3. Configuration

Configuration of the UCS system is performed with the "Install.perl" script,
which is invoked in the usual way from the Cygwin shell.  The script should 
detect the Cygwin environment and print a corresponding message.  Since the
R interpreter is not integrated with Cygwin, auto-configuration will fail.
You need to find out where the R distribution is installed and specify this
directory with the "-rh" (or "--R-home") option.  For instance, when R is
installed under

  C:\Program Files\R\

you should invoke the configuration script with

  perl System/Install.perl -rh "C:/Program Files/R"

Note the forward slashes and the quotes to protect whitespace in the directory
name (if possible, install R in another directory without whitespace).
"Install.perl" will try to find the command-line version of the R interpreter
in the specified directory.  If this fails, you have to look for a file called
"Rterm.exe" and specify its full path with the "-R" option.  If you have no
idea where R is installed, try searching for "Rterm.exe" with the Windows
search function.

If you are lucky, UCS has been configured successfully and you can proceed in
the normal way (as described in the "README" file).  Try stepping through the
tutorial "doc/getting-started.txt".  In order to run the UCS/R tutorial,
follow the instructions in "doc/getting-started.txt" and "System/R/README".
When you have changed to the "System/R/" directory, start the R GUI
environment from your Cygwin shell.  In the example above, you would type:

  "C:/Program Files/Rgui.exe"

Then you should be able load the tutorial ("script/tutorial.R") in the GUI and
step through it.

From here on, you are on your own.
