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