Tree [02437b] TAU /
History



File Date Author Commit
distribs 2009-12-02 paumard paumard [9089a7] minor change in distribs/debian/copyright
doc 2009-12-05 dhmunro dhmunro [ea29df] made several Debian patches part of main distri...
drat 2007-03-25 dhmunro dhmunro [f8d43f] fixed Windows make bug preventing drat.dll, hex...
emacs 2009-12-05 dhmunro dhmunro [ea29df] made several Debian patches part of main distri...
extend 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
extendf 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
fft 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
g 2007-06-29 dhmunro dhmunro [79f9df] changed fill to eofill in ps.ps to match onscre...
gist 2010-04-01 dhmunro dhmunro [4c0adc] fixed bugs with degrees=, hhmm=, base60= keywor...
hex 2007-03-25 dhmunro dhmunro [f8d43f] fixed Windows make bug preventing drat.dll, hex...
i 2010-07-03 dhmunro dhmunro [b02baa] begin 2.2 development, added oxy = object orien...
i-start 2010-05-30 dhmunro dhmunro [8e55bd] added autoloads for rcheby.i
i0 2010-07-04 dhmunro dhmunro [10e822] enhanced after function
icons 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
math 2008-04-13 dhmunro dhmunro [7060ba] bugfix in unused math/heapsort.c
matrix 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
mpy 2010-07-08 alanmorris alanmorris [982672] Fast forward from git:
opengl 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
play 2010-07-08 alanmorris alanmorris [982672] Fast forward from git:
regexp 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
tau 2010-09-10 uosameer uosameer [8c99cb] Yorick statements are instrumented and main is ...
win 2007-03-07 dhmunro dhmunro [d43893] fix bug in wspawn.c, yorlib.dsp for windows
yorick 2010-07-08 alanmorris alanmorris [982672] Fast forward from git:
LICENSE 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
Makedll 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
Makeexe 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
Makefile 2010-02-28 dhmunro dhmunro [5cf885] changed "make reloc" to default, cleaned up com...
Makepkg 2010-02-25 dhmunro dhmunro [bd8856] added dumpconfig target to top level Makefile, ...
ONEWS 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
README 2006-02-02 dhmunro dhmunro [122637] updated advice about setting Y_HOME and Y_SITE
TODO 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
VERSION 2010-07-03 dhmunro dhmunro [b02baa] begin 2.2 development, added oxy = object orien...
configure 2010-09-10 uosameer uosameer [02437b] When TAU is disabled, we echo CC=$CC in Make.cf...
install.rel 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
instally.sh 2005-09-18 dhmunro dhmunro [7fd98b] Initial revision
yorapi.sh 2006-02-02 thiebaut thiebaut [1ff021] removed "sort -u" command in yorapi.sh
ysite.sh 2010-02-28 dhmunro dhmunro [130423] make reloc now default, many compiler warnings ...

Read Me

Copyright (c) 2005, The Regents of the University of California.
All rights reserved.
This file is part of yorick (http://yorick.sourceforge.net).
Read the accompanying LICENSE file for details.

Yorick is an interactive programming language for scientific computing
that includes scientific visualization functions, and text and binary
I/O functions geared to millions of numbers.

Yorick runs under UNIX and MacOS X (X windows), and MS Windows.  If you
have problems building or running yorick, check the README files in the
various subdirectories of this source tree, and yorick's home page
at yorick.sourceforge.net.

Files in the regexp/ subdirectory are the work of Guido van Rossum
and Henry Spencer; read the files for details.
The latter is Copyright (c) 1986 by University of Toronto.

Files in the fft directory are C translations of the Swarztrauber
fortran FFTPACK routines.  Files in the matrix directory are C
translations of the fortran LAPACK routines.  The original fortran is
available from netlib.org.



OVERVIEW
--------

To build a relocatable version of yorick:

  make relocatable

This creates a tarball yorick-V.N-RR.tgz containing the yorick code,
interpreted library, and documentation.  Move it to the directory
where you wish to install yorick, then unpack it with:

  gzip -dc yorick-V.N-RR.tgz | tar xvf -

The yorick executable will be yorick-V.N-RR/bin/yorick.  Read
yorick-V.N-RR/README for more information.

You can also build non-relocatable versions of yorick, which must be
installed in a particular directory you specify when you build the
code.  If you want to check yorick out before making a decision, try

  make
or
  make install

which will assume that this source directory is where you are going to
install the executable yorick.  See the sections INSTALLING YORICK and
BUILDING YORICK below for more detailed information.



ROADMAP
-------

The top-level distribution directory contains this README, scripts for
configuring and building yorick, and a number of subdirectories.  Some
subdirectories contain core parts of yorick; others are extras which
you might reasonably omit.  Here's a quick roadmap:

  play/     (portability layer)
    here are event loop, low level io, graphics primitives
    everything else is supposed to be strictly architecture-independent
      (however, other non-core packages may slightly violate this rule)
  win/      (MS Windows specific files)
    here are the MS Visual C++ project files
    some Windows code is in subdirectories like play/win
  gist/
    play-based 2D scientific visualization library
  yorick/
    yorick language interpreter (C source)
  matrix/
    LAPACK linear algebra functions (C source)
  math/
    non-matrix mathematical functions (C source)
  fft/
    Swartztrauber Fast Fourier Transform (C source)
  i/
    library of interpreted functions
  i0/
    interpreted code required at startup
  i-start/
    interpreted code run at startup, usually containing autoloads
  extend/
    sample trivial compiled extension for yorick
  mpy/
    MPI-based yorick multiprocessing package
  drat/
    compiled extension to do 2D cylindrical radiation transport
  hex/
    compiled extension to do 3D radiation transport
  doc/
    documentation: yorick user manual, quick reference cards
  emacs/
    GNU Emacs lisp code for running yorick and editing yorick source

  distribs/
    files for creating RedHat RPM, FreeBSD, and other distributions
  debian/
    instructions for creating Debian .deb distribution



INSTALLING YORICK
-----------------

Yorick consists of an executable code plus a library of interpreted
functions.  If you do not install the interpreted library where yorick
expects, yorick will not run.  A proper installation should have the
following directory structure:

  $Y_SITE/
    i0/
      ".i" yorick source files, required when yorick starts
    i/
      ".i" yorick source files, interpreted library
    g/
      ".gp" palette and ".gs" style files for graphics library
    doc/
      yorick documentation (optional)

  $Y_HOME/
    Makepkg  => Makefile template for building custom yorick versions
      Makeexe, Makedll are components of this build system
    include/
      ".h" C header files for building custom yorick versions
      NOTE: this should be in Y_SITE...
    lib/
      binary object libraries for building custom yorick versions
      executables for support codes required during yorick builds
      executable yorick (or any sibling of lib/, such as bin/)
    bin/
      yorick executable (this may be installed elsewhere sometimes)
    packages/
      directory containing information about packages which extend
      yorick beyond this basic distribution

********** DO NOT set either Y_SITE or Y_HOME to a directory you value.
* DANGER * (In particular, Y_HOME should NEVER be your HOME directory.)
********** make uninstall might destroy Y_SITE and Y_HOME

The contents of Y_SITE are architecture independent; every machine on
a network may share the same Y_SITE directory.

The contents of Y_HOME depend on architecture, that is, on the
hardware and operating system; different machines on the same network
may require different Y_HOME directories.

Sharing Y_SITE among several installations of yorick with different
Y_HOME turns out to be a poor idea in practice.  It was inspired by
the /usr/local versus /usr/share distinction in the Linux file system
standard, but separate Y_SITE and Y_HOME directories have created far
more trouble that could possibly be justified either by the tiny
savings in disk space or the apparent maintenance advantage of a
common Y_SITE.  In practice, the versions of yorick sharing a common
Y_SITE have tended to diverge enough that the interpreted code
intended for one version of yorick becomes inappropriate for another.
Therefore, I strongly recommend setting Y_SITE = Y_HOME in all new
yorick installations.  On MS Windows systems, this identity is
mandatory.  In fact, the best idea is to use "make reloc" or
"make relocatable", which do not build in any fixed directory, but
force yorick to discover Y_SITE and Y_HOME at runtime.

In any case, you also need to arrange for users to be able to find and
start yorick.  Under MS Windows, you do that by making a shortcut that
starts $Y_HOME/bin/yorick.  Under UNIX, you either need to make sure
that yorick users have $Y_HOME/bin on their PATH environment variable,
or put a softlink or script that points to $Y_HOME/bin/yorick in some
standard place like /usr/bin or /usr/local/bin that is likely to be on
everyones PATH.

********** DO NOT set either Y_SITE or Y_HOME to a directory you value.
* DANGER * (In particular, Y_HOME should NEVER be your HOME directory.)
********** make uninstall might destroy Y_SITE and Y_HOME




BUILDING YORICK
---------------

To build yorick on a MS Windows machine, read win/README.

The best choice for Y_SITE and Y_HOME (see INSTALLING YORICK above) is
Y_HOME=Y_SITE=relocate, which you can specify with

   make reloc
which is equivalent to
   make Y_HOME=relocate ysite

The relocate choice forces the runtime computation of Y_HOME and
Y_SITE.

To set Y_HOME and Y_SITE to hardwired values, you can either edit the
file ysite.sh (read the comments there for a detailed description of
what to do), or, alternatively, you can type (all UNIX commands must
be typed in the top-level directory of the distribution):

   make prefix=/my/top/path Y_PLATFORM=hal9000 ysite
     to get
       Y_SITE=/my/top/path/yorick/$Y_VERSION
       Y_HOME=/my/top/path/yorick/$Y_VERSION/hal9000
     (/my/top/path might be /usr/lib)

   make prefix=/my/top/path ysite
     to get
       Y_SITE=/my/top/path/share/yorick/$Y_VERSION
       Y_HOME=/my/top/path/lib/yorick/$Y_VERSION
     (/my/top/path is typically /usr or /usr/local)

   make Y_HOME=/my/homesite ysite
     to get
       Y_SITE=/my/homesite
       Y_HOME=/my/homesite

   make Y_SITE=/my/site Y_HOME=/my/home ysite
     to get
       Y_SITE=/my/site
       Y_HOME=/my/home

********** DO NOT set either Y_SITE or Y_HOME to a directory you value.
* DANGER * (In particular, Y_HOME should NEVER be your HOME directory.)
********** make uninstall might destroy Y_SITE and Y_HOME

If you want to build a gzipped tar file containing a relocatable
yorick binary, you can do

   make relocatable

This will make Y_HOME=Y_SITE=relocate, which causes both to fall back
to the runtime determination described above.  The relocatable target
does make ysite, make config, make, and make install, then packages
everything into a gzipped tar file called yorick-A.B-R.tgz, which is
left in the top level directory.  You can untar this tgz file wherever
you like to install yorick; it unpacks into a yorick-A.B-R directory,
but you are free to change that name to whatever you like.  Read the
top level README (which is install.rel in this directory) for complete
instructions.

You can take up to four steps to configure, build, test, and install
yorick.  In order, the four separate commands are:

   make config
   make
   make check
   make install

You can also just type "make" to configure and build, or "make
install" to configure, build, and install.  If things go wrong, type
"make clean", then take the steps one at a time.  Yorick requires an
ANSI C compiler and libraries, some POSIX standard functions (plus
either poll or select, which are not covered by any standard, but are
present on all UNIX systems), and the basic X11 library (R4 might
work, but anything R5 or better should certainly work).  However,
these components may be misinstalled or installed in places where the
configuration process cannot find them.  If so, you can either fix
your system or edit the files Make.cfg and play/unix/config.h by hand
to repair any errors or oversights of "make config".

The "make config" step creates the file Make.cfg (in this top-level
directory).  By default, the compiler and loader flags are just "-O".
If you want fancier options, you can edit Make.cfg before you build;
just modify the Y_CFLAGS and/or Y_LDFLAGS variable.  Optimization flags
like -g or -O are handled separately; use the COPT_DEFAULT variable
to set those.

Instead of editing Make.cfg by hand after the "make config" step, you
can also set a variety of environment variables to control the
configuration process.  You can read the configuration scripts --
configure, play/unix/config.sh, play/x11/xconfig.sh, and
yorick/yconfig.sh -- to find out precisely what they do.  Here they
are, with sample non-default values:

   CC='xlc -q64'      # C compiler name plus overall mode switch
   CFLAGS=-g          # compile flags (-O is default)
   LDFLAGS=-g         # load flags (optimization CFLAGS is default)
   AR='ar -X 64'      # ar archive program
   RANLIB='ranlib -X 64'  # ranlib archive indexer
   MATHLIB=-lmcompat      # math library (-lm is default)

   FPU_IGNORE=yes  # give up trying to catch floating point exceptions
   NO_PLUGINS=yes  # build yorick with no plugin support
   LD_STATIC=yes   # force hex and drat packages to be statically loaded
   NO_PASSWD=yes   # hack for crippled OSes or crosscompilers (catamount)
   NO_CUSERID=yes  # hack for crippled OSes or crosscompilers (catamount)
   NO_PROCS=yes    # build yorick with no subprocess or poll/select support
                     (catamount) - this cripples yorick event handling
   NO_POLL=yes     # forces use of select when poll present but broken
                     (Mac OS X uses this by default)

   NO_XLIB=yes     # build yorick with no onscreen graphics
   X11BASE=/weird/X11root         # try -I/weird/X11root/include, and
                                        -L/weird/X11root/lib
   X11INC=/weird/X11root/include  # directory containing X11/Xlib.h
   X11LIB=/weird/X11root/lib      # directory containing libX11.a or .so

Other make targets include:

   clean      -- get rid of the mess left over from the build
      do this after successful install
   distclean  -- clean plus all files generated by the config step
      config does distclean before it begins
   siteclean  -- distclean plus resets ysite.sh to original settings
   uninstall  -- gets rid of all installed files
      be sure to do uninstall before distclean if you want to
      get rid of the yorick you installed (otherwise you will
      need to make ysite again)
   uninstall1 -- gets rid of all files installed in Y_HOME
   install1   -- only installs to Y_HOME, not to Y_SITE




LEARNING YORICK
---------------

The user manual and quick reference cards for yorick are in doc/.  If
you have makeinfo and texi2dvi you can format yorick.tex yourself into
either info format (emacs help browser) or dvi format (xdvi).  See
doc/Makefile for details.  Postscript versions of both documents come
with the distribution, and may be found in doc/.

Yorick also has a brief manpage, doc/yorick.1, which you might wish to
install (just copy it to the appropriate place).

If you start yorick, you can type

#include "demo1.i"
demo1

to run a demonstration program.  Typing

help,demo1

prints a documentation string, which includes the name of the source
file.  Read the source for an explanation of how the demo program
works.  There are also demo2, demo3, demo4, and demo5 programs, which
give you a pretty good picture of yorick's capabilities; run them the
same way as demo1.