← Back to branch summary

~ubuntu-branches/ubuntu/saucy/python-scipy/saucy

« back to all changes in this revision

Viewing changes to scipy/sandbox/xplt/src/README

  • Committer: Bazaar Package Importer
  • Author(s): Ondrej Certik
  • Date: 2008-06-16 22:58:01 UTC
  • mfrom: (2.1.24 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080616225801-irdhrpcwiocfbcmt
Tags: 0.6.0-12
http://bugs.debian.org/489149
* The description updated to match the current SciPy (Closes: #489149).
* Standards-Version bumped to 3.8.0 (no action needed)
* Build-Depends: netcdf-dev changed to libnetcdf-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
scipy/sandbox/xplt/src/README
 
1
Yorick is an interactive programming language for scientific computing
 
2
that includes scientific visualization functions, and text and binary
 
3
I/O functions geared to millions of numbers.
 
4
 
 
5
Yorick runs under UNIX (X windows), MS Windows, and MacOS X.
 
6
 
 
7
 
 
8
 
 
9
 
 
10
ROADMAP
 
11
-------
 
12
 
 
13
The top-level distribution directory contains this README, scripts for
 
14
configuring and building yorick, and a number of subdirectories.  Some
 
15
subdirectories contain core parts of yorick; others are extras which
 
16
you might reasonably omit.  Here's a quick roadmap:
 
17
 
 
18
  play/     (portability layer)
 
19
    here are event loop, low level io, graphics primitives
 
20
    everything else is supposed to be strictly architecture-independent
 
21
      (however, other non-core packages may slightly violate this rule)
 
22
  win/      (MS Windows specific files)
 
23
    here are the MS Visual C++ project files
 
24
    some Windows code is in subdirectories like play/win or opengl/win
 
25
  gist/
 
26
    play-based 2D scientific visualization library
 
27
  yorick/
 
28
    yorick language interpreter (C source)
 
29
  matrix/
 
30
    LAPACK linear algebra functions (C source)
 
31
  math/
 
32
    non-matrix mathematical functions (C source)
 
33
  fft/
 
34
    Swartztrauber Fast Fourier Transform (C source)
 
35
  i/
 
36
    library of interpreted functions
 
37
  i0/
 
38
    interpreted code required at startup
 
39
  extend/
 
40
    sample trivial compiled extension for yorick
 
41
  mpy/
 
42
    MPI-based yorick multiprocessing package
 
43
  drat/
 
44
    compiled extension to do 2D cylindrical radiation transport
 
45
  hex/
 
46
    compiled extension to do 3D radiation transport
 
47
  doc/
 
48
    documentation: yorick user manual, quick reference cards
 
49
  emacs/
 
50
    GNU Emacs lisp code for running yorick and editing yorick source
 
51
  opengl/
 
52
    OpenGL-based 3D scientific visualization library (unfinished)
 
53
 
 
54
 
 
55
 
 
56
 
 
57
INSTALLING YORICK
 
58
-----------------
 
59
 
 
60
Yorick consists of an executable code plus a library of interpreted
 
61
functions.  If you do not install the interpreted library where yorick
 
62
expects, yorick will not run.  A proper installation should have the
 
63
following directory structure:
 
64
 
 
65
  $Y_SITE/
 
66
    i0/
 
67
      ".i" yorick source files, required when yorick starts
 
68
    i/
 
69
      ".i" yorick source files, interpreted library
 
70
    g/
 
71
      ".gp" palette and ".gs" style files for graphics library
 
72
    doc/
 
73
      yorick documentation (optional)
 
74
 
 
75
  $Y_HOME/
 
76
    Maketmpl  => Makefile template for building custom yorick versions
 
77
    include/
 
78
      ".h" C header files for building custom yorick versions
 
79
      NOTE: this should be in Y_SITE...
 
80
    lib/
 
81
      binary object libraries for building custom yorick versions
 
82
      executables for support codes required during yorick builds
 
83
      executable yorick (or any sibling of lib/, such as bin/)
 
84
    bin/
 
85
      yorick executable (this may be installed elsewhere sometimes)
 
86
 
 
87
********** DO NOT set either Y_SITE or Y_HOME to a directory you value.
 
88
* DANGER * (In particular, Y_HOME should NEVER be your HOME directory.)
 
89
********** make uninstall might destroy Y_SITE and Y_HOME
 
90
 
 
91
The contents of Y_SITE are architecture independent; every machine on
 
92
a network may share the same Y_SITE directory.
 
93
 
 
94
The contents of Y_HOME depend on architecture, that is, on the
 
95
hardware and operating system; different machines on the same network
 
96
may require different Y_HOME directories.
 
97
 
 
98
On MS Windows systems Y_HOME and Y_SITE must be the same directory.
 
99
This is also a reasonable way to install yorick on single architecture
 
100
platforms.  For test versions of yorick, Y_HOME and Y_SITE can be
 
101
identical to the top-level distribution directory containing this
 
102
README.  When Y_HOME = Y_SITE and the yorick executable is in
 
103
Y_HOME/bin, yorick can always find its interpreted library and startup
 
104
files relative to the "launch directory" where the executable lives.
 
105
(A program can figure out where it's executable is on all systems.)
 
106
 
 
107
When you build yorick, the values of Y_HOME and Y_SITE are compiled
 
108
in.  As long as the compiled-in values of Y_HOME and Y_SITE are
 
109
correct, you can install the executable anywhere; it doesn't have to
 
110
go in Y_HOME/bin.  (This does no good on systems such as Windows,
 
111
where different users will install the program in different places,
 
112
which is why you must make Y_SITE and Y_HOME the same directory and
 
113
put the executable in Y_HOME/bin/.)
 
114
 
 
115
In any case, you also need to arrange for users to be able to find and
 
116
start yorick.  Under MS Windows, you do that by making an alias that
 
117
starts $Y_HOME/bin/yorick.  Under UNIX, you either need to make sure
 
118
that yorick users have $Y_HOME/bin on their PATH environment variable,
 
119
or put a softlink or script that points to $Y_HOME/bin/yorick in some
 
120
standard place like /usr/bin or /usr/local/bin that is likely to be on
 
121
everyones PATH.
 
122
 
 
123
Heterogeneous networks or development sites maintaining several
 
124
versions of yorick naturally require more complicated arrangements.
 
125
Here are two suggestions:
 
126
 
 
127
(1) With prefix = /usr or /usr/local and Y_VERSION = 1.5, 2.0, etc.:
 
128
 
 
129
  Y_SITE = $prefix/share/yorick/$Y_VERSION
 
130
  Y_HOME = $prefix/lib/yorick/$Y_VERSION
 
131
 
 
132
(2) With prefix = any directory cross-mounted to all architectures
 
133
(e.g.- /usr/share) and Y_PLATFORM = any designation unique to all
 
134
machines which can run the same binaries (e.g.- compaq, sunos, hpux,
 
135
linux86, i386-debian-linux):
 
136
 
 
137
  Y_SITE = $prefix/yorick/$Y_VERSION
 
138
  Y_HOME = $prefix/yorick/$Y_VERSION/$Y_PLATFORM
 
139
 
 
140
********** DO NOT set either Y_SITE or Y_HOME to a directory you value.
 
141
* DANGER * (In particular, Y_HOME should NEVER be your HOME directory.)
 
142
********** make uninstall might destroy Y_SITE and Y_HOME
 
143
 
 
144
 
 
145
 
 
146
 
 
147
BUILDING YORICK
 
148
---------------
 
149
 
 
150
To build yorick on a MS Windows machine, read win/README.
 
151
 
 
152
If you want to install yorick in a directory other than the one you
 
153
are building in, you must first set Y_SITE and Y_HOME, as described
 
154
above.  (Otherwise, just skip to the next paragraph.)  You can either
 
155
edit the file ysite.sh (read the comments there for a detailed
 
156
description of what to do), or, alternatively, you can type (all UNIX
 
157
commands must be typed in the top-level directory of the
 
158
distribution):
 
159
 
 
160
   make prefix=/my/top/path Y_PLATFORM=hal9000 ysite
 
161
     to get
 
162
       Y_SITE=/my/top/path/yorick/$Y_VERSION
 
163
       Y_HOME=/my/top/path/yorick/$Y_VERSION/hal9000
 
164
     (/my/top/path might be /usr/lib)
 
165
 
 
166
   make prefix=/my/top/path ysite
 
167
     to get
 
168
       Y_SITE=/my/top/path/share/yorick/$Y_VERSION
 
169
       Y_HOME=/my/top/path/lib/yorick/$Y_VERSION
 
170
     (/my/top/path is typically /usr or /usr/local)
 
171
 
 
172
   make Y_HOME=/my/homesite ysite
 
173
     to get
 
174
       Y_SITE=/my/homesite
 
175
       Y_HOME=/my/homesite
 
176
 
 
177
   make Y_SITE=/my/site Y_HOME=/my/home ysite
 
178
     to get
 
179
       Y_SITE=/my/site
 
180
       Y_HOME=/my/home
 
181
 
 
182
********** DO NOT set either Y_SITE or Y_HOME to a directory you value.
 
183
* DANGER * (In particular, Y_HOME should NEVER be your HOME directory.)
 
184
********** make uninstall might destroy Y_SITE and Y_HOME
 
185
 
 
186
If you want to build a gzipped tar file containing a relocatable
 
187
yorick binary, you can do
 
188
 
 
189
   make relocatable
 
190
 
 
191
This will make Y_HOME=Y_SITE=relocate, which causes both to fall back
 
192
to the runtime determination described above.  The relocatable target
 
193
does make ysite, make config, make, and make install, then packages
 
194
everything into a gzipped tar file called yorick-A.B-R.tgz, which is
 
195
left in the top level directory.  You can untar this tgz file wherever
 
196
you like to install yorick; it unpacks into a yorick-A.B-R directory,
 
197
but you are free to change that name to whatever you like.  Read the
 
198
top level README (which is install.rel in this directory) for complete
 
199
instructions.
 
200
 
 
201
More usually, you can take up to four steps to configure, build, test,
 
202
and install yorick.  In order, the four separate commands are:
 
203
 
 
204
   make config
 
205
   make
 
206
   make check
 
207
   make install
 
208
 
 
209
You can also just type "make" to configure and build, or "make
 
210
install" to configure, build, and install.  If things go wrong, type
 
211
"make clean", then take the steps one at a time.  Yorick requires an
 
212
ANSI C compiler and libraries, some POSIX standard functions (plus
 
213
either poll or select, which are not covered by any standard, but are
 
214
present on all UNIX systems), and the basic X11 library (R4 might
 
215
work, but anything R5 or better should certainly work).  However,
 
216
these components may be misinstalled or installed in places where the
 
217
configuration process cannot find them.  If so, you can either fix
 
218
your system or edit the files Make.cfg and play/unix/config.h by hand
 
219
to repair any errors or oversights of "make config".
 
220
 
 
221
The "make config" step creates the file Make.cfg (in this top-level
 
222
directory).  By default, the compiler and loader flags are just
 
223
"-O".  If you want fancier options, you can edit Make.cfg before
 
224
you build; just modify the COPTIONS and/or LDOPTIONS variable.  For
 
225
the convenience of gcc users, a maximal error-checking set of
 
226
options is included in Make.cfg.  Just set
 
227
COPTIONS=$(GCCOPTS)
 
228
to use this set.  (This actually detects a vast number of non-ansi
 
229
constructs in the system string.h header file on my system, so you
 
230
might need to get rid of the -ansi and -pedantic switches.)
 
231
 
 
232
Other make targets include:
 
233
 
 
234
   clean      -- get rid of the mess left over from the build
 
235
      do this after successful install
 
236
   distclean  -- clean plus all files generated by the config step
 
237
      config does distclean before it begins
 
238
   uninstall  -- gets rid of all installed files
 
239
      be sure to do uninstall before distclean if you want to
 
240
      get rid of the yorick you installed (otherwise you will
 
241
      need to make ysite again)
 
242
   uninstall1 -- gets rid of all files installed in Y_HOME
 
243
   install1   -- only installs to Y_HOME, not to Y_SITE
 
244
 
 
245
 
 
246
 
 
247
 
 
248
LEARNING YORICK
 
249
---------------
 
250
 
 
251
The user manual and quick reference cards for yorick are in doc/.  If
 
252
you have makeinfo and texi2dvi you can format yorick.tex yourself into
 
253
either info format (emacs help browser) or dvi format (xdvi).  See
 
254
doc/Makefile for details.  Postscript versions of both documents come
 
255
with the distribution, and may be found in doc/.
 
256
 
 
257
Yorick also has a brief manpage, doc/yorick.1, which you might wish to
 
258
install (just copy it to the appropriate place).
 
259
 
 
260
If you start yorick, you can type
 
261
 
 
262
#include "demo1.i"
 
263
demo1
 
264
 
 
265
to run a demonstration program.  Typing
 
266
 
 
267
help,demo1
 
268
 
 
269
prints a documentation string, which includes the name of the source
 
270
file.  Read the source for an explanation of how the demo program
 
271
works.  There are also demo2, demo3, demo4, and demo5 programs, which
 
272
give you a pretty good picture of yorick's capabilities; run them the
 
273
same way as demo1.