
			  Yorick Version 1.1

***********
* Warning *  The generic INSTALL file does not mention important details
***********  of Yorick installation.  See Installation below.

What is Yorick?
---------------

Read the ANNOUNCE file in this directory.

Installation
------------

You need an ANSI C compiler in order to build Yorick "as is".

Yorick configures itself by means of a configure script produced by the
GNU Autoconf program (available via anonymous FTP from prep.ai.mit.edu).
However, you may need to do some additional configuration by hand.  To
build Yorick, cd to the top level directory (which contains this README),
and type:

     ./configure --prefix=`pwd`
     make
     make check

Those are backquotes around the `pwd` (if pwd returns a mangled
version of your current directory, type the simpler name you
ordinarily use instead).  If you eventually want to install Yorick in
a directory other than this current directory, you will need to
specify where it is to be installed with a different --prefix and/or
--exec-prefix option to the configure script.  Read the section
"Yorick directory structure" below for details.

If configure can't find your ANSI C compiler, set the environment
variable CC to your ANSI C compiler's name, make sure it is on your
execution path, and rerun configure.  (The GNU gcc compiler is available
at prep.ai.mit.edu if you have no ANSI C compiler.)  For example:

     env "CC=cc -ansi" ./configure --prefix=`pwd`

You may also need to set the LIBS or LDFLAGS variables (see the section
"Compilers and Options" in INSTALL).

If the make works, the executable files will be Browser/gist,
Yorick/yorick, MathC/yorm, and Drat/drat.  The check target runs tests
on the Gist/libgist.a graphics library, and on Drat/drat, which is the
version of the interpreter which will eventually be installed.  These
checks take quite a while (though not as long as the make), but they
are worth doing to be sure the configure and make have worked
properly.  If the checks fail, you need to tinker with the Makefiles
until the check target runs.

The "Problems" section below describes the few known problems.  Be
sure to read it if you have Solaris or a DEC alpha.

To install Yorick in this very directory (`pwd` above):

     make install

Otherwise, do a "make clean" and read "Yorick directory structure" below
for instructions on how to build Yorick for installation in a
different directory.

Yorick is unusual in that it must find a bunch of startup files
(interpreted code which it needs to read when it starts).  If you just
copy the Yorick executable to some random place, it will continue to look
back to this directory to find those startup files.  NEITHER yorick NOR
gist WILL WORK IF YOU DELETE THE DIRECTORY CONTAINING THESE STARTUP
FILES!  After make install, however, you should do:

     make clean

in order to clean up all of the non-essential files.

Before you think that you're finished building Yorick, be sure to read
the section "Fine tuning" -- there are things the configure script
cannot do for you that you might want to do yourself.  Also, be sure
to follow the special instructions in "Yorick directory structure" if
you are building Yorick on several architectures in a heterogeneous
network.



Fine tuning
-----------

The configure script cannot do a few things that you may want to do
(then do a distclean and rebuild Yorick):

   (1) Most UN*X workstations will not deliver SIGFPE signals when
       you do things like divide by zero or square 1.e300.  Yorick
       expects these signals to be delivered!  (Type 1./0. at the
       > prompt after you start Yorick; it should respond angrily
       with something about ERROR.  If it meekly types something
       silly like "Inf", you have a problem that you should fix!  If
       you don't fix this, sooner or later you'll waste a large amount
       of CPU time slowly filling a 1000-by-1000 array full of Inf's
       or NaN's...)  Unfortunately, every manufacturer has a different
       idea of what you should do to get this signal delivered.  These
       fall into two categories:
       (a) a loader switch (e.g.- -fnonstd on Suns, +FPVZOD on HPs)
           This is easy.  Just set the LDFLAGS environment variable
           before you run configure (see above).
       (b) a subroutine which must be called at runtime
           In this case, you must modify the InitializeSignals
           routine in the file Yorick/sysdep.c.  Examples for several
           different architectures are shown there.

       The sysdep.c source code includes #ifdefs for SunOS, Solaris,
       HP 700 series, SGI, IBM RS6000, DEC alpha, Linux, and Cray
       machines; if you have one of these, you may not need to do
       anything yourself.  Do the 1./0. test to be sure.  The SGI
       machines are particularly baroque; beware of the TRAP_FPE
       environment variable described in the Problems section below.

       As of this writing, I have not been able to convince ULTRIX to
       deliver SIGFPE.  If you know how to do this, send me e-mail.

   (2) The configure script will not do anything about shared versus
       archive libraries.  Think about which you want.  You can set
       LDFLAGS before you run configure (see above) if you don't want
       default behavior.  The default is probably good enough, but if you
       use shared libraries, you need to check Yorick on any machines
       on your network whose operating system differs (even in minor
       version) from the machine where you built it.

   (3) The configure script knows little about Fortran compilers.  If
       you want to load special versions of Yorick which call Fortran
       routines, you may need to tinker with the Fortran section of
       Yorick/Makefile.  Possibly you will need to fix the FORTRAN_LIBS
       in Yorick/Makefile by hand.



Yorick directory structure
--------------------------

If you are building Yorick on a heterogeneous network, you can share the
source tree, startup files, and interpreted library among all the
machines on the network.  The directory structure created by the
"install" make target contains an architecture independent tree, and an
architecture dependent tree.  In the following description, "prefix" and
"exec-prefix" are absolute path names you pass to the configure script
(read the INSTALL file for more); in the make described above, both were
set to `pwd` (remember the backquotes?) -- the full name of the top level
directory.

Architecture-independent files (text):

     prefix/Yorick/

        startup/
           paths.i std.i graph.i stdx.i fft.i matrix.i drat.i
           <These files are required for Yorick to start properly.>
        include/
           *.i
           <Yorick interpreted code library.  Not optional.>
        gist/
           ps.ps *.gs *.gp
           <PostScript template, style sheets, and palettes for graphics.>
        doc/
           <Yorick documentation.  Optional, if there are no users.>
        contrib/
           <Optional world-writable place for local contributors.>


Architecture-dependent files (executables, object libraries, header files):

     exec-prefix/

        bin/
           yorick gist
           <The Yorick interpreter and the Gist binary CGM browser.>
        lib/
           libyor.a libgist.a libyorm.a libdrat.a
           <Object libraries for various parts of Yorick.>
        yorhome/
           Maketmpl codger *.h
           <Makefile template, codger code generator, header files.>
        contrib/
           <Optional world-writable place for local contributors.>

(The exec-prefix/lib and exec-prefix/yorhome directories are only
necessary if you want to be able to build new versions of Yorick with
embedded compiled code of your own.)

By default, both prefix and exec-prefix are /usr/local.  More than
likely, these are not correct for your site.  At my site, for example,
prefix is /env/Yorick/1.1 -- a directory tree visible from every
computer on the network -- and exec-prefix is /env/Yorick/1.1/ARCH,
where ARCH is HP for the HP binaries, Sun for the Sun binaries, etc.

Say you want to put Yorick in /env/Yorick/1.1 and /env/Yorick/1.1/HP,
like I do.  To build and install Yorick on each architecture on your
network, first unpack the Yorick distribution in /env/Yorick, then cd
into this top level directory:

     mkdir /env/Yorick
     mv yorick-1.1.tar.gz /env/Yorick
     cd /env/Yorick
     zcat yorick-1.1.tar.gz | tar xvf -
     mv yorick-1.1 1.1
     cd 1.1
     mkdir HP
     ./configure --prefix=`pwd` --exec-prefix=`pwd`/HP
     make
     make check
     make install
     make clean

Then, move to a machine of each different architecture on your
network, and type (substituting some unique string for ARCH):

     cd /env/Yorick/1.1
     ./configure --prefix=`pwd` --exec-prefix=`pwd`/ARCH
     make
     make check
     make install
     make clean

Softlinks from /usr/local/bin -- on everyones PATH -- are convenient:

     /usr/local/bin/yorick   ---->   exec-prefix/bin/yorick
     /usr/local/bin/gist     ---->   exec-prefix/bin/gist

Or, you can just move the yorick and gist executables into
/usr/local/bin (or wherever) and delete the exec-prefix/bin directory.
The architecture independent tree /env/Yorick/1.1 will include
the source code, which I prefer.  If you don't want to do this, unpack
the Yorick source in some directory other than /env/Yorick/1.1,
and use --prefix=/env/Yorick/1.1 instead of `pwd` when you do
the configure.



Problems
--------

(1) Some DEC alpha compilers break the routine YpDo in Yorick/parse.c.
    None of the tests in "make check" will catch this bug!  To check
    whether you are a victim, after "make check", start Yorick by typing
       Drat/drat
    and type (after the > prompt):
       help, Y_SITE
    Yorick should respond with 9 lines of help about the Y_SITE
    variable.  If it responds with only a single line describing
    Y_LAUNCH, you need to rebuild Yorick.  (If you don't, no Yorick
    program which uses a do-while loop will work properly.)  Type
       quit
    to get out of Yorick.  As far as I know, all you need to do is to
    recompile Yorick/parse.c with -g instead of -O.  (If you want to
    retain full performance during parsing, you can probably figure out a
    way to work around the compiler bug, which is that the "body" argument
    is not passed to the SetBranchTarget routine correctly in parse.c:YpDo.)

    If you have no idea how to do this yourself, try the following:
    From the top level directory, type:
       rm Drat/drat
       cd Yorick
       rm yorick parse.o libyor.a
    Then edit Makefile (Yorick/Makefile) to uncomment/comment two lines
    near the top, so they look like this:
C_OPTIMIZE = -g
# C_OPTIMIZE = -O
    Save the file, then type:
       make parse.o
    Edit the Makefile again, restoring the two lines to their original
    state:
# C_OPTIMIZE = -g
C_OPTIMIZE = -O
    Finally, return to the top level, and rebuild Yorick:
       cd ..
       make
       make check
       Drat/drat
    Typing "help, Y_SITE" should now result in the complete help
    message.

(2) If you are running on a Sun with Solaris -- SunOS 5 or greater --
you need to make the following modification to Yorick/Makefile after
running configure, before running make (search for ARFLAGS):
     ARFLAGS = rc
You may also need to add -lsunmath to Yorick/Makefile by hand:
     LOWLIBS = -lm -L/opt/SUNWspro/SC3.0/lib -lsunmath
(The -L option might be different on your system -- you need to find the
sunmath library.)
If you haven't bought a Sun compiler, you won't have libsunmath.  Try to
compile the file Yorick/ieee_sun.c with gcc -g to supply the missing
externals before you give up and comment out the stuff in Yorick/sysdep.c
which generates the calls.  The missing routines allow SIGFPE to be
delivered to your program; see Fine Tuning (1) above.

(3) Some monochrome X servers do something which causes the Gist/bench
test program to fail with a message about BadAccess from FreeColors.
If this happens, run the check target in the Drat directory:

     cd Drat; make check

As long as Yorick passes it's check, you are probably OK.  The gist
program may behave badly when you quit, however.  Be sure to try the
testg.i/grtest test mentioned below to be sure Yorick itself has working
graphics.

(4) On SGI machines under IRIX, Yorick may not behave properly if
you have set the environment variable TRAP_FPE.  Yorick *wants* to
handle floating point interrupts all by itself!  This problem shows
up in bizarre places; if you have set TRAP_FPE, you should make
an alias to start Yorick with it unset.

(5) Early IRIX 6.0 machines didn't ship with a 64 bit version of libfpe.a,
so you won't be able to make 1.0/0.0 illegal (see Fine Tuning 1).


Documentation
-------------

I haven't finished a user's manual; what I have so far is in Yorick/doc
as the file yorick.tex.  It is in GNU texinfo format, so you can use GNU
Emacs to read it online as hypertext (for Emacs 19.25 or above, all you
need do is to add the doc/ directory to Info-default-directory-list
variable), or TeX to make a printable document.

The two UNIX man pages yorick.1 and gist.1 (in this top level directory)
can be installed if you wish.  The gist page is a complete description
of the browser.  The yorick page tells how to get more help.

Other documentation (in Yorick/doc) includes:

     refs.tex
        a set of 6 quick reference sheets for the Yorick language; use
        a double sided Xerox to make 3 quick reference cards

     std.doc
        alphabetized collection of DOCUMENT comments for all of the
        standard basic Yorick commands and functions

     graph.doc
        ditto for all of the plotting commands and their keywords

     math.doc
        ditto for the FFT and LAPACK matrix routines in the Math package

     drat.doc
        ditto for the transport equation solver in the Drat package

The *.doc files are compilations of all of the DOCUMENT comments which
can be printed interactively using Yorick's help command; type "help"
(no quotes) after you start Yorick in order to find out more about how
to use the help command.

The file Yorick/include/README contains a thumbnail description of the
library functions in the Yorick/include directory.



Getting started
---------------

After you've had enough of the documentation, I recommend you peruse the
Yorick/include/demo1.i file.  This is a simple 1-D hydrodynamics code
implemented entirely in the interpreter.  It analyzes a piston moving
into a shock tube; you can watch weak sound waves propagate, or stronger
ones steepen into shocks.  Read the file carefully to get an idea of
what a Yorick program looks like.  Here is an interactive session in
which I run some demos (the stuff after the > prompt is what I typed):

tonto[1] yorick
 Yorick ready.  For help type 'help'
> #include "testg.i"
> grtest       // graphics test/crude tutorial
...lots of explanations and descriptions...
> #include "demo1.i"
> help, demo1
 /* DOCUMENT demo1
      run the 1-D hydrocode demonstration.  An X window should pop up
      in which a movie of a wave propagating down a shock tube appears.
      Use the 'sound' and 'shock' commands to set two different interesting
      initial conditions; the default is 'sound'.
 
    SEE ALSO: sound, shock, evolve
  */
 defined at:  LINE: 275  FILE: /wrk/munro/yorick-1.1/Yorick/include/demo1.i
> demo1        // watch jerky movie in an X window
> animate, 1   // turn on smooth animation
> demo1        // watch smooth movie in an X window
> shock
> demo1        // watch movie showing shock steepening
> #include "demo2.i"
> demo2        // watch 3 movies of a drumhead oscillating
> #include "demo3.i"
> demo3        // watch "Way cool, Dad!" chaotic pendulum movie
> #include "demo4.i"
> demo4        // Yorick solves an plots flow field around an airfoil
> quit
tonto[2] 

The Yorick/include/demo2.i has more eye-catching graphics than demo1.i,
although you won't like the first and third movies unless you have a
color monitor.  Again, reading the source code should be instructive.

Many of the other files in the Yorick/include library provide interesting
examples of how to use Yorick.  Read through any that interest you, using
the Yorick/doc/*.doc files to look up the meanings of any functions you
don't understand, and the quick reference cards to decipher any syntax
you can't understand.  Array indexing is particularly complicated ("rich")
in Yorick; a long (but poorly edited) section in the yorick.tex proto-manual
will hopefully clarify this for you.



Address
-------

I welcome constructive comments:            munro@icf.llnl.gov

If you find a bug (I've found a few myself), please fix it and tell me
what you did, so I can fix the distribution.

The ANNOUNCE file lists Yorick FTP sites, and tells how to subscribe
to the Yorick mailing list.



Legal matters
-------------

(c) 1994.  The Regents of the University of California.  All rights reserved.

Permission to use, copy, modify, and distribute this software for any
purpose without fee is hereby granted, provided that this entire
notice is included in all copies of any software which is or includes
a copy or modification of this software and in all copies of the
supporting documentation for such software.

This work was produced at the University of California, Lawrence
Livermore National Laboratory under contract no. W-7405-ENG-48 between
the U.S. Department of Energy and The Regents of the University of
California for the operation of UC LLNL.


			      DISCLAIMER

This software was prepared as an account of work sponsored by an
agency of the United States Government.  Neither the United States
Government nor the University of California nor any of their
employees, makes any warranty, express or implied, or assumes any
liability or responsibility for the accuracy, completeness, or
usefulness of any information, apparatus, product, or process
disclosed, or represents that its use would not infringe
privately-owned rights.  Reference herein to any specific commercial
products, process, or service by trade name, trademark, manufacturer,
or otherwise, does not necessarily constitute or imply its
endorsement, recommendation, or favoring by the United States
Government or the University of California.  The views and opinions of
authors expressed herein do not necessarily state or reflect those of
the United States Government or the University of California, and
shall not be used for advertising or product endorsement purposes.


				AUTHOR

David H. Munro wrote Yorick and Gist.  Berkeley Yacc (byacc) generated
the Yorick parser.  The routines in Math are from LAPACK and FFTPACK;
MathC contains C translations by David H. Munro.  The algorithms for
Yorick's random number generator and several special functions in
Yorick/include were taken from Numerical Recipes by Press, et. al.,
although the Yorick implementations are unrelated to those in
Numerical Recipes.  A small amount of code in Gist was adapted from
the X11R4 release, copyright M.I.T. -- the complete copyright notice
may be found in the (unused) file Gist/host.c.
