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 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 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: firstname.lastname@example.org 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.