Yorick Version 1.4
***********
* 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.
---------------
Contents
--------
1. Installation
2. Yorick directory structure
3. Configuration options and problems
4. Optimization
5. Fine tuning
6. Problems
7. Documentation
8. Getting started
9. Address
10. Legal matters
1. Installation
---------------
You need an ANSI C compiler in order to build Yorick "as is".
Yorick must find a bunch of startup files (interpreted code which it
needs to read when it starts). The Gist CGM browser has the same
problem -- it needs to find a template to be able to create PostScript
output. The "Yorick directory structure" section below gives details.
Your simplest option is to build Yorick right here in its source
directory -- but be aware that if you remove the source directory at
some future date, Yorick and Gist will stop working! To configure
Yorick in this way, type:
./configure --prefix=here
You can leave out the --prefix=here parameter if you want to install
Yorick in the /usr/local directory tree. You'll most likely need to
be root in order to do that. See "Configuration options and problems"
below if something goes wrong with configure.
Now that you've configured Yorick, build the code by typing:
make
If the make succeeds, you can test to see if the code works by typing:
make check
If the check succeeds, install yorick and gist by typing:
make install
Finally, you will want to clean up by typing:
make clean
If you want to return to the state before the configure, so you can
reconfigure Yorick for a build on a new platform, or for installation
in a different directory, type:
make distclean
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.
2. Yorick directory structure
-----------------------------
Architecture-independent files (text):
Y_SITE/
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>
gist/
ps.ps *.gs *.gp
<PostScript template, style sheets, and palettes for graphics.>
doc/
<Yorick documentation>
contrib/
<optional world-writable place for local contributors>
Architecture-dependent files (executables, object libraries, header files):
Y_HOME/
Maketmpl
<Makefile template for building custom yoricks>
lib/
libyor.a libgist.a libyorm.a libdrat.a
<object libraries for various parts of Yorick>
contrib/
<optional world-writable place for local contributors>
bin/
codger <code generator for building custom yoricks>
h/
<C header files for building custom yoricks>
The user-level executable files (also architecture-dependent):
Y_BINDIR/
yorick gist
<the Yorick interpreter and the Gist binary CGM browser>
The Y_SITE and Y_BINDIR directories are the only ones necessary to run
Yorick. The Y_HOME directory comes into play only if you want to add
your own compiled functions to Yorick.
The GNU Autoconf scheme for computing the directory paths is based on
placing Y_SITE, Y_HOME, and Y_BINDIR relative to two higher level
directories prefix and exec-prefix. These both default to /usr/local,
but can be reset by specifying --prefix= or --exec-prefix= options to
configure. If you use these, you will get:
Y_SITE = prefix/share/yorick/1.4
Y_HOME = exec-prefix/lib/yorick/1.4
Y_BINDIR = exec-prefix/bin
You can give configure the --disable-share option if your site does
not use "share" subdirectories; in that case, Y_SITE will be in
prefix/lib instead of prefix/share. See "Configuration options and
problems" below for other alternatives. In particular,
exec-prefix/lib/yorick/1.4 might be visible from several different
architectures at your site; if so you will need the --enable-suffix
option to be able to create a version of yorick for each architecture.
If you give configure the special prefix --prefix=here this scheme is
disabled, and you get:
Y_SITE = srcdir/Yorick
Y_HOME = exec-prefix (which defaults to srcdir in this case)
Y_BINDIR = exec-prefix/bin
(In this case, you probably need to either move the executables in
Y_BINDIR to a place on your path, or make softlinks to them.)
3. Configuration options and problems
-------------------------------------
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=here
You may also need to set the LIBS or LDFLAGS variables (see the section
"Compilers and Options" in INSTALL). The default optimization should be
adequate; but see the "Optimization" section below.
This configure script also supports the following non-standard options:
--prefix=here
To set the prefix to this source directory. See the section
"Yorick directory structure" above. You can specify --exec-prefix
as usual if you just want the Y_SITE files to go here.
--with-gcc
Use this to make configure try to find gcc instead of cc.
--enable-share=name
--disable-share
The GNU default is to place architecture independent files in
/usr/local/share (or prefix/share in general). If /usr/local/name
(or prefix/name in general) is more appropriate for your system,
use this option.
--disable-share is equivalent to --enable-share=lib
--enable-suffix=host
Adds the suffix "/host" to Y_HOME. This may be necessary if you are
building yorick for a number of different architectures, and your
exec-prefix is visible from all of them. For example,
--enable-suffix=SunOS
will cause Y_HOME to be (by default) /usr/local/lib/yorick/1.4/SunOS
You can use this option with --prefix=here as well.
--enable-bindir=path
--disable-bindir
Set Y_BINDIR to path for situations where the default calculation
(see "Yorick directory structure" above) is wrong.
With --disable-bindir the yorick and gist executables will be installed
in Y_HOME/bin (with codger). This is always a safe option, as you can
move them or make softlinks to them later.
4. Optimization
---------------
By default, Yorick will be built with "-O" optimization. If you have
serious problems, you can build a debugging "-g" version by typing
(in the top level directory):
make clean
make debug
make
and perhaps "make install". To return to the default "-O" optimization,
do this:
make clean
make optimize
make
On most platforms, optimization beyond "-O" does not seem to help
Yorick's performance much. If you want to experiment with something
like "-aggressive" on your platform, run make optimize like this:
make optimize O_FLAGS="+O4 -aggressive"
On some platforms, "-aggressive" (or whatever) causes the compiler to
fail if specified on the load line instead of the compile line. If
you need a different option for loading, do this:
make optimize O_FLAGS="+O4 -aggressive" LD_FLAGS=+O4
Again, this tinkering is probably a waste of your time.
5. 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.
I have been told that the man page for_set_fpe.3f might give
you some hints for how to do this with Fortran.
(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. If you go for
archive libraries on Solaris, you may need Yorick/dlsym.c, and
see the note in Yorick/Maketmpl.in.
(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
the Makefile template Maketmpl, installed in Y_HOME. After
make install, feel free to do so.
6. Problems
-----------
(1) Some DEC alpha compilers break the routine YpDo in Yorick/parse.c.
If this happens, make check will tell you to recompile parse.c at -g.
(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.) The latest version of DEC's compiler
(as of November 1996) does not have this problem; consider upgrading.
If you have no idea how to do this yourself, try the following:
Look through the output from make to find the line that compiled
parse.c (just search backward for parse.c if you can). Edit that
line, changing the -O flag to -g then cd into the Yorick/ directory
and execute the edited compile line.
Finally, return to the top level, and rebuild Yorick:
cd ..
make
make check
Doing "make check" shouldn't fail any more.
(2) 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.
(3) 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).
(4) If you use a non-HP compiler (e.g.- gcc) on a PA-RISC machine, it
is almost certainly installed incorrectly. The libm.a in /lib is
*not* the correct one; you want the one in /lib/pa1.1. After
configure, change LOWLIBS in config.status, placing -L/lib/pa1.1
before -lm, and rerun it (config.status).
(5) If you yorick graphics fails with a message that it can't find
work.gs, then you didn't install Yorick properly. In the top level
directory where you built it, try "make clean; make; make install".
The same thing applies if Yorick can't find its startup include files
(like std.i).
(6) Some Linux libc versions have a bug in sscanf so that real numbers
like "1.23E-4" will not be read properly. "1.23e-4" works fine, so the
workaround is not to use capital E in your input files (the yorick
parser is not affected, only the read and sread functions). Amazingly
enough "1.23E4" is fine as well, only exponents with an explicit +-
are a problem.
7. 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. To build the hypertext
version, cd to Yorick/doc and type:
makeinfo yorick.tex
The distribution comes with a pre-built PostScript version of the
manual yorick.ps, and the set of quick reference sheets refs.ps. If
you have TeX and you want to rebuild yorick.ps for A4 paper, put the
@afourpaper macro near the top of yorick.tex and rerun tex.
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. They are built when you do "make install".
The file Yorick/include/README contains a thumbnail description of the
library functions in the Yorick/include directory.
8. 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.4/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
> #include "demo5.i"
> demo5 // demonstrate pl3d "3D" graphics functions
> 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.
9. 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.
10. 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.
