1Welcome
2-------
3
4Yorick is an interactive programming language for scientific computing
5that includes scientific visualization functions, and text and binary
6I/O functions geared to millions of numbers.
7
8Yorick is open source software, under a
9[BSD license](https://github.com/dhmunro/yorick/blob/master/LICENSE.md).
10Yorick runs under UNIX, MacOS X (X windows), and MS Windows.  You can
11find many yorick resources online:
12
13* Home pages at [yorick.github.com][] and [yorick.sourceforge.net][],
14  including the user manual and extensive documentation.
15* User forums at [yorick.sourceforge.net][].
16* Browse or download sourcecode at [github.com/dhmunro/yorick][].
17* Read end of Quick start section below on running yorick demo programs.
18
19[yorick.github.com]:         http://yorick.github.com
20[yorick.sourceforge.net]:    http://yorick.sourceforge.net
21[github.com/dhmunro/yorick]: http://github.com/dhmunro/yorick
22
23Files in the regexp/ subdirectory are the work of Guido van Rossum and
24Henry Spencer; read the files for details.  The latter is Copyright
25(c) 1986 by University of Toronto.
26
27Files in the fft directory are C translations of the Swarztrauber
28fortran FFTPACK routines.  Files in the matrix directory are C
29translations of the fortran LAPACK routines.  The original fortran is
30available from [netlib.org](http://netlib.org/).
31
32
33Quick start
34-----------
35
36On most UNIX-like systems (including Linux and MacOS X), you can build
37yorick by changing to the top level directory of the source
38distribution and typing:
39
40    make install
41
42This will create a subdirectory relocate/ in the source tree.  The
43yorick executable is relocate/bin/yorick.  You can move the relocate/
44directory wherever you want (the name "relocate" is unimportant), but
45any changes in the relative locations of the files therein will
46prevent yorick from starting correctly.  You can, of course, softlink
47to the yorick executable from wherever you like, or exec yorick from a
48shell script outside its relocate/ directory.  The relocate/ directory
49is organized as follows:
50
51    relocate/  files required for building compiled packages, and:
52      bin/     binary executables
53      lib/     binary libraries for compiled packages
54      include/ header files for compiled package APIs
55      i0/      interpreted code required for yorick to start
56      i/       optional interpreted code libraries
57      i-start/ interpreted code that autoloads at startup
58      g/       graphics style files, palettes, and templates
59      doc/     documentation files
60
61To build a tarball containing a yorick executable, type instead:
62
63    make relocatable
64
65This creates a tarball yorick-V.N-RR.tgz containing the yorick code,
66interpreted library, and documentation.  Move it to the directory
67where you wish to install yorick, then unpack it with:
68
69    gzip -dc yorick-V.N-RR.tgz | tar xvf -
70
71The yorick executable will be yorick-V.N-RR/bin/yorick.  Read
72yorick-V.N-RR/README for more information.
73
74To build yorick on a MS Windows machine, read win/README.
75
76Yorick is a command line program; you need to run it in a terminal
77window.  You will want command line recall and editing.  If your
78terminal window does not support that, you can either run yorick under
79emacs (see the emacs/ directory in the source), or you can get a
80readline wrapper like [rlwrap](http://freshmeat.net/projects/rlwrap/).
81
82If you need some test programs to run, you can try the demos.  Start
83yorick and type:
84
85    include, "demo3.i"
86    demo3
87
88The demo3 runs a simulation of a chaotic pendulum (it will stop after
89about a minute).  Yorick functions generally have documentation which
90you can read in the terminal using the help command:
91
92    help, demo3
93
94The help message includes the path to the source file, which you can
95open and read with any text editor, to find out exactly how demo3
96works (or any other yorick interpreted command).  There are five demo
97programs (demo1 through demo5).  You can also do a comprehensive test
98of your yorick installation by typing:
99
100    include, "testfull.i"
101
102
103Roadmap of yorick source
104------------------------
105
106The top-level distribution directory contains this README, scripts for
107configuring and building yorick, and a number of subdirectories.  Some
108subdirectories contain core parts of yorick; others are extras which
109you might reasonably omit.  Here's a quick roadmap:
110
111    play/     (portability layer)
112      here are event loop, low level io, graphics primitives
113      everything else is supposed to be strictly architecture-independent
114        (however, other non-core packages may slightly violate this rule)
115    win/      (MS Windows specific files)
116      here are the MS Visual C++ project files
117      some Windows code is in subdirectories like play/win
118    gist/
119      play-based 2D scientific visualization library
120    yorick/
121      yorick language interpreter (C source)
122    matrix/
123      LAPACK linear algebra functions (C source)
124    math/
125      non-matrix mathematical functions (C source)
126    fft/
127      Swartztrauber Fast Fourier Transform (C source)
128    i/
129      library of interpreted functions
130    i0/
131      interpreted code required at startup
132    i-start/
133      interpreted code run at startup, usually containing autoloads
134    extend/
135      sample trivial compiled extension for yorick
136    mpy/
137      MPI-based yorick multiprocessing package
138    drat/
139      compiled extension to do 2D cylindrical radiation transport
140    hex/
141      compiled extension to do 3D radiation transport
142    doc/
143      documentation: yorick user manual, quick reference cards
144    emacs/
145      GNU Emacs lisp code for running yorick and editing yorick source
146
147    distribs/
148      files for creating RedHat RPM, FreeBSD, and other distributions
149    debian/
150      instructions for creating Debian .deb distribution
151
152
153Other build options
154-------------------
155
156You can take up to four steps to configure, build, test, and install
157yorick.  In order, the four separate commands are:
158
159    make config
160    make
161    make check
162    make install
163
164 Yorick requires an ANSI C compiler and libraries, some POSIX standard
165 functions (plus either poll or select, which are not covered by any
166 standard, but are present on all UNIX systems), and the basic X11
167 library (R4 might work, but anything R5 or better should certainly
168 work).  However, these components may be misinstalled or installed in
169 places where the configuration process cannot find them.  If so, you
170 can either fix your system or edit the files Make.cfg and
171 play/unix/config.h by hand to repair any errors or oversights of "make
172 config".
173
174 The "make config" step creates the file Make.cfg (in this top-level
175 directory).  By default, the compiler and loader flags are just "-O".
176 If you want fancier options, you can edit Make.cfg before you build;
177 just modify the Y_CFLAGS and/or Y_LDFLAGS variable.  Optimization flags
178 like -g or -O are handled separately; use the COPT_DEFAULT variable
179 to set those.
180
181 Instead of editing Make.cfg by hand after the "make config" step, you
182 can also set a variety of environment variables to control the
183 configuration process.  You can read the configuration scripts --
184 configure, play/unix/config.sh, play/x11/xconfig.sh, and
185 yorick/yconfig.sh -- to find out precisely what they do.  Here they
186 are, with sample non-default values:
187
188    CC='xlc -q64'      # C compiler name plus overall mode switch
189    CFLAGS=-g          # compile flags (-O is default)
190    LDFLAGS=-g         # load flags (optimization CFLAGS is default)
191    AR='ar -X 64'      # ar archive program
192    RANLIB='ranlib -X 64'  # ranlib archive indexer
193    MATHLIB=-lmcompat      # math library (-lm is default)
194
195    FPU_IGNORE=yes  # give up trying to catch floating point exceptions
196    NO_PLUGINS=yes  # build yorick with no plugin support
197    LD_STATIC=yes   # force hex and drat packages to be statically loaded
198    NO_PASSWD=yes   # hack for crippled OSes or crosscompilers (catamount)
199    NO_CUSERID=yes  # hack for crippled OSes or crosscompilers (catamount)
200    NO_PROCS=yes    # build yorick with no subprocess or poll/select support
201                      (catamount) - this cripples yorick event handling
202    NO_POLL=yes     # forces use of select when poll present but broken
203                      (Mac OS X uses this by default)
204
205    NO_XLIB=yes     # build yorick with no onscreen graphics
206    X11BASE=/weird/X11root         # try -I/weird/X11root/include, and
207                                         -L/weird/X11root/lib
208    X11INC=/weird/X11root/include  # directory containing X11/Xlib.h
209    X11LIB=/weird/X11root/lib      # directory containing libX11.a or .so
210
211Other make targets include:
212
213    clean      -- get rid of the mess left over from the build
214       do this after successful install
215    distclean  -- clean plus all files generated by the config step
216       config does distclean before it begins
217    siteclean  -- distclean plus resets ysite.sh to original settings
218    uninstall  -- gets rid of all installed files
219       be sure to do uninstall before distclean if you want to
220       get rid of the yorick you installed (otherwise you will
221       need to make ysite again)
222
223There are many more build targets and make macros.  Read the comments
224in Makefile and Makepkg for more information.
225