-----------------------------------------------------------------------

   RLaB Installation Instructions:

   Read WHATS.NEW if you are already a RLaB user.

   Read the PROBLEMS file if you have troubles with installation.

   To configure rlab for your platform you must:

   Make the Libraries: The libraries that are compatible with
   rlab v1.19 are: rblas-1.1.tar
 		   rlap-2.0tar
		   rfft-1.2.tar	
		   rnlib-1.1.tar
		   plplot4p99i.tar.gz (optional)

   Each library unpacks into it's own directory. Use configure to
   create the Makefile, then type `make'. `make install' to install
   the library. See the README file in each library directory for
   further instructions. See README.PLPLOT in this directory for
   Plplot specific instructions.

   1.) Unpack the rlab distribution (you have already done that :-).

	1.a) Make all the libraries that you want rlab to use. When
	you run configure in the next step it will configure rlab to
	use the resources _presently_ available. Thus, if you want
	Plplot graphics, you must make and install plplot before
	running rlab's configure.

   2.) Type `./configure' from within the top-level rlab directory.

	2.a) Configure will recognize certain "with" options:

	--prefix=dir		Use dir as the root of the software
				installation tree.
	--with-cc		Use the cc compiler
	--with-gcc		Use the GNU C compiler
	--with-LIBS=dir		Look for all libraries in dir 1st. If
				the bulk of your libraries are not in
				/usr/local/lib, then this is a good
				option to use.
	--with-NALIBS=dir	Look for the Numerical Analysis
				libraries in dir
	--with-FLIBS=dir	Look for the f2c libraries in dir. If
				the f2c libraries are in the same
				place as the Numerical Analysis libs,
				then this option is unnecessary.

	--with-PLIBS=dir	Look for the PLPLOT library in
				dir/lib. If Plplot is installed in
				$HOME/plplot, $HOME/plplot/lib,
				$HOME/plplot/include, etc... The use:
				--with-PLIBS=$HOME/plplot

	--with-includes=dir	Look for X-windows include files in
				dir.

	--with-libraries=dir	Look for X-windows libraries in dir.

	--disable-fpe		Do not try and set floating point
				exception handling. Use whatever the
				system supplies.

	--with-gnuplot		Use Gnuplot, even if Plplot exists.

	See the Fortran notes below if you wish to link with Fortran
	compiled subroutines.

	configure automatically removes its own cache file when it is
	finished. This way it will be safe/reliable to re-run
	configure at a later date.

   3.) Type `make'

	3.a) If you want to install rlab someplace other than
	/usr/local, then type `make prefix=/usr/someplace/else' (if
	you did not use the --prefix option with configure).

	3.b) Type `make Test'. This run rlab through some simple tests
	to verify correct behavior. When the test completes
	successfully, you will see the string "FINISHED TESTS".
	Otherwise, there is an error that needs correcting. Either the
	error is a run-time error or some type of system error
	(segmentation violation or bus error). Run-time errors can be
	identified because RLaB will produce its own error message
	(usually `rlab: USER-RAISED-ERROR').

	If you get a system error, then please e-mail a copy of the
	traceback to ians@eskimo.com, along with a description of your
	hardware, and operating system.

	If you get a run-time error, then go to the identified line
	number in the file `./test'. See if you can replicate the
	behavior at the command line (run `rlab -qrl' if you need to
	prevent attempts to load the libraries). On some systems the
	behavior might be acceptable. If you need help determining the
	cause of the error send mail to ians@eskimo.com. Send a
	description of your hardware and operating system along with a
	copy of the output from `make Test'.


   4.) Type `make -n install' and verify that the install process is to
   your liking.

	4.a) If you want to install rlab someplace other than
	/usr/local, then type `make prefix=/usr/someplace/else -n install'.
	prefix should match whatever was used in step 3.a.

   5.) Type the make-command used in step 4 or 4a without the `-n'
   option.

   6.) Enjoy ...

   7.) Send bug reports to ians@eskimo.com, or to the mailing list at
   rlab-list@eskimo.com. If you want to subscribe to the mailing list
   send mail to ians@eskimo.com.

   IN CASE OF EMERGENCY: If the make does not proceed through
   installation without problems, then human intervention will be
   required. The files created by configure (Makefile and config.h)
   can be edited by hand, or Makefile.dist (cp to Makefile), and
   config.h.dist (cp to config.h) can be edited to achieve a
   compileable rlab. These files are supposed to have enough comments
   to allow installers to figure out the correct options.

   See the file PROBLEMS for solutions to some commonly encountered
   difficulties.

   Please send report(s) of any compilation or installation
   difficulties to ians@eskimo.com. 

   ---------------------------------------------------------------

   NOTES:

   F2C LIBS:

   If you use the f2c translated numerical libraries, and you do not
   use the f2c Fortran libraries (instead you might use vendor
   supplied Fortran libraries), you will most likely have trouble
   during the final link of the executable.  Unfortunately, most
   vendors have been unable to refrain from gratuitously modifying
   libF77.a, and libI77.a. To solve this problem get the f2c
   distribution from netlib (netlib.att.com, in netlib/f2c), or from
   prep.ai.mit.edu (in pub/gnu).

   Another alternative is to get the Fortran source for each of the
   libraries (it is all available from netlib and statlib), and use
   your vendors Fortran compiler and libraries. On some architectures
   the resulting RLaB will be faster at operations that involve the
   BLAS.

   FORTRAN:

   RLaB is used on many machines without a Fortran compiler. This is
   made possible by the AT&T f2c project. However, some users have a
   Fortran compiler, and even specially optimized versions of the BLAS
   subroutines. If you wish to link with Fortran compiled (or vendor
   supplied) libraries, you are on your own. I would like to make this
   process simpler in the near future but, for now it requires user
   intervention. If you know a little about C - Fortran interfaces,
   then you may wish to give it a try:

	0) Get and build ALL of the libraries with a Fortran compiler.
	   You will need the double precision version of fftpack (send
	   me mail if you do not have it). The remaining libraries
	   are available from netlib. 
	1) Run configure
	2) Edit the generated Makefile.
		a) Comment out the rules for lp.o, bl.o and ode.o
		b) Uncomment the fule for .f.o
		c) Set the value of F77
		d) Edit the value of FLIBS. This is tougher than it
	           may seem at 1st. Each platform tends to be
	           different. If you are successfull, please send me
	           the FLIBS definition that works. I will keep a list
	           to make it easier on others in the future.
		e) Set the value for FCONV. this variable controls the
		   convention used for the C - Fortran interface.
	4) You may need to change the typedefs at the bottom of fi.h
	   to suit your particular Fortran compiler. Most Fortran
	   compilers do not use long ints (but f2c does). On many
	   machines long ints are the same size as int (but not on the
	   DEC-alpha) so it may not make any difference. If you get
	   bad pivot values from factor(), this is a good sign that
	   the C and Fortran ints are not the same size.
	3) Type make

	Some tested platforms...

	Sun, SunOS 5.3 (Solaris 2.3):
		FLIBS = -L/opt/SUNWspro/SC3.0.1/lib -lF77 -lM77 -lsunmath
		FCONV = -DUSE_F2C

	Sun SunOS 4.1.2
		FLIBS = -L/usr/lang/SC1.0 -lF77
		FCONV = -DUSE_F2C

	DEC-Ultrix-RISC:
		FLIBS = -L. -lF77 -lI77 -lUfor -lfor -lutil \
			-lots -L/usr/lib/cmplrs/fort -li_31
		FCONV = -DUSE_F2C

	OSF1 V2.0/V3.0 250 alpha:
		FLIBS = -L. -lfor -lUfor -lFutil -lots -lm -lc
		FCONV = -DUSE_F2C

	HP-UX A.09.03 E 9000/712
		FLIBS = -lU77 -lcl -lm
		FCONV = -DUSE_LOWER

	AIX v3.2:
		FLIBS = -L. -lxlf -lxlfutil
		FCONV = -DUSE_LOWER
		You will need to make sure that -lc appears before any
		numercial libs. Otherwise rlab will dump core in the
		AIX Fortran getenv().

	Titan P3000:
		FLIBS = -L. -lF77 -lI77 -lUmF77 -lubF77 -liF77
		FCONV = -DUSE_UPPER

	Watch out for things like:

	a) Linking to Fortran versions of getenv(). On some machines
	you may have to put -lc at the head of the library list.

   PLOTTING:

   RLaB uses the PLPLOT library to provide data plotting
   services. PLPLOT is freely available. You can get PLPLOT from
   dino.ph.utexas.edu in the directory plplot. If you have a double
   precision version of the PLPLOT library configure may find it and
   turn on the plotting capability. At present configure searches for
   libplplotdX.a and libplplotdtk.a. If you have a PLPLOT library
   under some other name, then edit the Makefile variable PLIBS and
   PLIB_DIR to reflect the correct library, and then edit config.h so
   that HAVE_RLAB_PLPLOT is defined. The RLaB Primer and the examples
   directory both contain plot usage examples.

   As an alternative to PLPLOT RLaB can use its built-in piping and
   file I/O capabilities to get data to most plot programs fairly
   easy. There is a sample Rlab program in a file called
   toolbox/gnuplot.r that uses these capabilities to interactively
   make plots by running GNUPLOT as a sub-process. To use this
   function (plot()), you must have the GNUPLOT program somewhere in
   your PATH.  If you don't have GNUPLOT, or wish to use some other
   plotting program feel free to modify the plot() interface to suit
   your needs.

   I recommend that you use GNUPLOT version 3.2 or higher. Versions
   before 3.2 tend to break the input stream when an input error
   occurs, thus making plotting intolerant of user errors.

-----------------------------------------------------------------------

This is a generic INSTALL file for utilities distributions.
If this package does not come with, e.g., installable documentation or
data files, please ignore the references to them below.

To compile this package:

1.  Configure the package for your system.  In the directory that this
file is in, type `./configure'.  If you're using `csh' on an old
version of System V, you might need to type `sh configure' instead to
prevent `csh' from trying to execute `configure' itself.

The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation, and
creates the Makefile(s) (one in each subdirectory of the source
directory).  In some packages it creates a C header file containing
system-dependent definitions.  It also creates a file `config.status'
that you can run in the future to recreate the current configuration.

Running `configure' takes a minute or two.  While it is running, it
prints some messages that tell what it is doing.  If you don't want to
see the messages, run `configure' with its standard output redirected
to `/dev/null'; for example, `./configure >/dev/null'.

To compile the package in a different directory from the one
containing the source code, you must use a version of `make' that
supports the VPATH variable, such as GNU `make'.  `cd' to the directory
where you want the object files and executables to go and run
`configure'.  `configure' automatically checks for the source code in
the directory that `configure' is in and in `..'.  If for some reason
`configure' is not in the source code directory that you are
configuring, then it will report that it can't find the source code.
In that case, run `configure' with the option `--srcdir=DIR', where
DIR is the directory that contains the source code.

By default, `make install' will install the package's files in
/usr/local/bin, /usr/local/lib, /usr/local/man, etc.  You can specify an
installation prefix other than /usr/local by giving `configure' the option
`--prefix=PATH'.  Alternately, you can do so by consistently giving a value
for the `prefix' variable when you run `make', e.g.,
	make prefix=/usr/gnu
	make prefix=/usr/gnu install

You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If
you give `configure' the option `--exec-prefix=PATH' or set the
`make' variable `exec_prefix' to PATH, the package will use PATH as
the prefix for installing programs and libraries.  Data files and
documentation will still use the regular prefix.  Normally, all files
are installed using the regular prefix.

Another `configure' option is useful mainly in `Makefile' rules for
updating `config.status' and `Makefile'.  The `--no-create' option
figures out the configuration for your system and records it in
`config.status', without actually configuring the package (creating
`Makefile's and perhaps a configuration header file).  Later, you can
run `./config.status' to actually configure the package.  You can also
give `config.status' the `--recheck' option, which makes it re-run
`configure' with the same arguments you used before.  This option is
useful if you change `configure'.

Some packages pay attention to `--with-PACKAGE' options to `configure',
where PACKAGE is something like `gnu-libc' or `x' (for the X Window System).
The README should mention any --with- options that the package recognizes.

`configure' ignores any other arguments that you give it.

If your system requires unusual options for compilation or linking
that `configure' doesn't know about, you can give `configure' initial
values for some variables by setting them in the environment.  In
Bourne-compatible shells, you can do that on the command line like
this:
	CC='gcc -traditional' DEFS=-D_POSIX_SOURCE ./configure

The `make' variables that you might want to override with environment
variables when running `configure' are:

(For these variables, any value given in the environment overrides the
value that `configure' would choose:)
CC		C compiler program.
		Default is `cc', or `gcc' if `gcc' is in your PATH.
INSTALL		Program to use to install files.
		Default is `install' if you have it, `cp' otherwise.

(For these variables, any value given in the environment is added to
the value that `configure' chooses:)
DEFS		Configuration options, in the form `-Dfoo -Dbar ...'
		Do not use this variable in packages that create a
		configuration header file.
LIBS		Libraries to link with, in the form `-lfoo -lbar ...'

If you need to do unusual things to compile the package, we encourage
you to figure out how `configure' could check whether to do them, and
mail diffs or instructions to the address given in the README so we
can include them in the next release.

2.  Type `make' to compile the package.  If you want, you can override
the `make' variables CFLAGS and LDFLAGS like this:

	make CFLAGS=-O2 LDFLAGS=-s

3.  If the package comes with self-tests and you want to run them,
type `make check'.  If you're not sure whether there are any, try it;
if `make' responds with something like
	make: *** No way to make target `check'.  Stop.
then the package does not come with self-tests.

4.  Type `make install' to install programs, data files, and
documentation.

5.  You can remove the program binaries and object files from the
source directory by typing `make clean'.  To also remove the
Makefile(s), the header file containing system-dependent definitions
(if the package uses one), and `config.status' (all the files that
`configure' created), type `make distclean'.

The file `configure.in' is used as a template to create `configure' by
a program called `autoconf'.  You will only need it if you want to
regenerate `configure' using a newer version of `autoconf'.
