← Back to branch summary

~drgeo-developers/drgeo/trunk

« back to all changes in this revision

Viewing changes to VMs/iPad/source/unix/doc/squeak.1

  • Committer: Hilaire Fernandes
  • Date: 2012-01-27 21:15:40 UTC
  • Revision ID: hilaire.fernandes@gmail.com-20120127211540-912spf97bhpx6mve
Initial additions

Show diffs side-by-side

added added

removed removed

Lines of Context:
VMs/iPad/source/unix/doc/squeak.1
 
1
.\" squeak.1 -- manual page for Unix Squeak                     -*- nroff -*-
 
2
.\" 
 
3
.\"   Copyright (C) 1996-2004 by Ian Piumarta and other authors/contributors
 
4
.\"                              listed elsewhere in this file.
 
5
.\"   All rights reserved.
 
6
.\"   
 
7
.\"   This file is part of Unix Squeak.
 
8
.\" 
 
9
.\"   Permission is hereby granted, free of charge, to any person obtaining a copy
 
10
.\"   of this software and associated documentation files (the "Software"), to deal
 
11
.\"   in the Software without restriction, including without limitation the rights
 
12
.\"   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 
13
.\"   copies of the Software, and to permit persons to whom the Software is
 
14
.\"   furnished to do so, subject to the following conditions:
 
15
.\"
 
16
.\"   The above copyright notice and this permission notice shall be included in
 
17
.\"   all copies or substantial portions of the Software.
 
18
.\"
 
19
.\"   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 
20
.\"   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 
21
.\"   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 
22
.\"   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 
23
.\"   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 
24
.\"   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 
25
.\"   SOFTWARE.
 
26
.\" 
 
27
.\" Last edited: 2009-08-12 11:14:29 by piumarta on emilia-2.local
 
28
.\" 
 
29
.if @@\*(lq@ \{\
 
30
.       ds lq "
 
31
.       if t .ds lq ``
 
32
.       if !@@\(lq@ .ds lq "\(lq
 
33
.\}
 
34
.if @@\*(rq@ \{\
 
35
.       ds rq "
 
36
.       if t .ds rq ''
 
37
.       if !@@\(rq@ .ds rq "\(rq
 
38
.\}
 
39
.de Id
 
40
.ds Rv \\$3
 
41
.ds Dt \\$4
 
42
..
 
43
.de Sp
 
44
.if n .sp
 
45
.if t .sp 0.4
 
46
..
 
47
.TH SQUEAK 1 "\*(Dt" "Squeak Smalltalk System" "Squeak Smalltalk System"
 
48
.SH NAME
 
49
squeak, inisqueak \- Unix Squeak virtual machine and installer
 
50
.SH SYNOPSIS
 
51
.B inisqueak
 
52
.br
 
53
.B squeak
 
54
.RI "[ " option ".\|.\|. ] [ " image " ] [ " script " [ " argument ".\|.\|. ] ]"
 
55
.SH DESCRIPTION
 
56
.B squeak
 
57
is the virtual machine for the Squeak Smalltalk system.  It requires three files
 
58
to operate correctly: an
 
59
.B image
 
60
file containing a `snapshot' of a live Squeak session, a
 
61
.B changes
 
62
file containing the source code for modified methods in the image, and
 
63
a copy of (or a link to) a shared system
 
64
.B sources
 
65
file containing the source code for methods that have not been modified
 
66
since the last major version increment.
 
67
.PP
 
68
The image and changes files contain the state of a user's Squeak
 
69
session, which is persistent between consecutive sessions.  Private
 
70
copies of these files are therefore normally required.  The
 
71
.B inisqueak
 
72
script checks that the local Squeak installation appears sane, and then
 
73
copies the required files to the current
 
74
working directory.
 
75
If
 
76
.B inisqueak
 
77
encounters no problems, it will finish by running
 
78
.B squeak
 
79
to start a Squeak session using the newly copied image and changes files.
 
80
.PP
 
81
.B inisqueak
 
82
should be run
 
83
.I once\c
 
84
\&, when using Squeak for the first time, to create a new 'personal'
 
85
Squeak session.  Afterwards,
 
86
.B squeak
 
87
should be run each time that session is to be resumed.
 
88
.PP
 
89
.SH INVOCATION
 
90
.B inisqueak
 
91
has no options or arguments.
 
92
Simply 'cd' to the directory that is to contain the working
 
93
copies of the image and changes files, then run it.
 
94
.PP
 
95
.B squeak
 
96
accepts various
 
97
.I options
 
98
(described below), and then an optional
 
99
.I image
 
100
name (which must not begin with a minus sign '\-').  If an
 
101
.I image
 
102
name is given on the command line then
 
103
.B squeak
 
104
tries to run that image.  Otherwise
 
105
.B squeak
 
106
checks the environment variable
 
107
.B SQUEAK_IMAGE
 
108
and, if it is set, uses its value as the name of the image to run.
 
109
Otherwise 
 
110
.B squeak
 
111
looks for an image called 'squeak.image' in the current directory.
 
112
If the image file does not exist then
 
113
.B squeak
 
114
prints a message indicating which image file it failed to find and then
 
115
exits.
 
116
If the extension '.image' is missing in the
 
117
.I image
 
118
argument or in the value of the
 
119
.B SQUEAK_IMAGE
 
120
variable, it will be appended automatically.
 
121
.PP
 
122
The
 
123
.I image
 
124
argument can be followed by a
 
125
.I script
 
126
name.  This is the name of a 'document' that should contain
 
127
Smalltalk code to be executed on startup.  The document can be either
 
128
the name of a file or a URL starting with 'http:'.
 
129
Any
 
130
.I argument\c
 
131
s that appear after the
 
132
.I script
 
133
name are ignored, but are made available to the
 
134
.I script
 
135
from within Squeak via the method
 
136
.B getSystemAttribute:\c
 
137
\&.  (See the section
 
138
.B SCRIPTS
 
139
below.)
 
140
.PP
 
141
If
 
142
.I image
 
143
is given as '--' then
 
144
.B squeak
 
145
immediately stops argument processing (and behaves as if
 
146
.I image
 
147
was not specified).  This is useful to specify a
 
148
.I script
 
149
(possibly with script arguments) without specifying an explicit
 
150
.I image\c
 
151
\&.
 
152
.SH OPTIONS
 
153
Command line options fall into two categories: 'common' options
 
154
that are recognised by the base VM and 'specific' options that are
 
155
tied to a particular display or sound driver.  Common options will
 
156
always be recognised by
 
157
.B squeak\c
 
158
, whereas a given specific option will be recognised only after
 
159
.B squeak
 
160
has loaded the driver to which it relates.  Refer to the '-vm'
 
161
option below for more details.
 
162
.PP
 
163
The common options recognised by
 
164
.B squeak
 
165
are as follows:
 
166
.TP
 
167
.BI "\-encoding " "enc"
 
168
specifies the internal character encoding to be used by Squeak.  This
 
169
affects the translation that the VM performs when importing text (from
 
170
the keyboard or via 'paste' from an external selection) or exporting
 
171
text (pasting text from Squeak to another application, or when
 
172
generating filenames containing special characters).  In other words,
 
173
it affects the correspondence between what Squeak displays on the
 
174
screen and what it sends to (or receives from) external applications.
 
175
The correct value depends on the way Squeak's internal fonts are
 
176
encoded.  Current images are delivered with traditional Macintosh
 
177
\&'New York' fonts that use
 
178
.B Mac Roman
 
179
encoding, and so this is the default internal encoding.  If other
 
180
fonts (from X11 or elsewhere) are imported into the image and used as
 
181
system fonts then the this default translation will give incorrect
 
182
results for diacritical marks and special characters.  In such cases
 
183
the
 
184
.B \-encoding
 
185
option can be used to change the internal encoding, for example
 
186
.sp
 
187
.nf
 
188
\ \ \ \ \-encoding ISO-8859-15
 
189
.fi
 
190
.sp
 
191
(aka
 
192
.B Latin9\c
 
193
) which would be appropriate for many of the fonts designed for
 
194
European languages.
 
195
.TP
 
196
.B \-help
 
197
prints a short summary of the command-line syntax, options and
 
198
available drivers, then exits.
 
199
.TP
 
200
.BI "-memory " "size"[mk]
 
201
requests that a fixed heap of
 
202
.I size
 
203
bytes be allocated for the Squeak image.  If the suffix `\c
 
204
.B k\c
 
205
\&' is given then the argument is expressed in kilobytes.  If
 
206
the suffux `\c
 
207
.B m\c
 
208
\&' is given then the argument is expressed in megabytes.  This option
 
209
SHOULD NOT be used, unless there is a good reason to do so, since it
 
210
places an arbitrary limit on Squeak's object memory size.
 
211
.TP
 
212
.BI "-mmap " "size"[mk]
 
213
requests that a variable heap of at most
 
214
.I size
 
215
bytes be allocated.  (The suffixes are as described for the
 
216
\&'\-memory' option.)
 
217
.B squeak
 
218
will initially allocate a heap that is large enough to hold the image,
 
219
with a small amount of headroom.  If at any time Squeak requires more
 
220
memory for its image then additional space will be allocated
 
221
dynamically.  Likewise, when memory is no longer needed it will
 
222
deallocated and returned to the system.  The
 
223
.I size
 
224
argument places an upper limit on how big the heap can grow in this
 
225
fashion.  
 
226
.B squeak
 
227
uses a dynamic heap by default with the maximum size set to 75% of the
 
228
available virtual memory or 1 gigabyte, whichever is smaller.
 
229
.TP
 
230
.B \-noevents
 
231
disables the new (image 2.8 and later) event-driven input mechanism.
 
232
This option is only useful for testing backwards compatibility with
 
233
older images and should not be used.
 
234
.TP
 
235
.B \-notimer
 
236
disables the use of the interval timer for keeping track of low-resolution
 
237
time.  (If you are having problems with file, sound or socket i/o reporting
 
238
`interrupted system call' then setting this flag might help.)
 
239
.TP
 
240
.BI "\-pathenc " "enc"
 
241
specifies the external character encoding to be used by Squeak when accessing the filesystem
 
242
(file and directory pathnames).  The correct value depends on the local platform's characteristics.
 
243
If no encoding conversion should be performed then this should be set to the same encoding
 
244
as Squeak uses internally (see the
 
245
.I \-encoding
 
246
option).  Otherwise
 
247
.B ISO-8859-15
 
248
(aka
 
249
.B Latin9\c
 
250
) might make sense on a filesystem supporting 8\-bit characters, and
 
251
.B UTF-8
 
252
for filesystems that use Unicode-based pathnames.  The default is
 
253
.B UTF-8
 
254
which is correct for Mac OS X and very recent GNU/Linux distributions,
 
255
and which (in an ideal world) will eventually be adopted by all Unix
 
256
variants.
 
257
.TP
 
258
.BI "-plugins " "path"
 
259
specifies an alternative location for external plugins (collections of
 
260
named primitives) and drivers (for display and sound).  The
 
261
.I path
 
262
argument contains a pattern in which any occurrences of `\c
 
263
.B %n\c
 
264
\&' will be replaced by the name of the plugin or driver being loaded.
 
265
The
 
266
.I path
 
267
can name either a directory or the plugin itself and can be absolute or
 
268
relative (to the directory in which
 
269
.B squeak
 
270
was run).  If a plugin or driver cannot be found in the location
 
271
specified by
 
272
.I path
 
273
then the search continues in the default locations.
 
274
.TP
 
275
.BI "\-textenc " "enc"
 
276
specifies the external character encoding to be used by Squeak when
 
277
exchanging clipboard text with other applications.  The default is
 
278
.B UTF-8
 
279
on Mac OS X and
 
280
.B ISO-8859-15
 
281
(aka
 
282
.B Latin9\c
 
283
) on other Unix systems.  Note that X11 applications requesting the
 
284
selection converted to
 
285
.B UTF8_STRING
 
286
data will (correctly) receive the clipboard text encoded as
 
287
.B UTF-8\c
 
288
, regardless of this setting.
 
289
.sp
 
290
Squeak recognises a subset of the encoding names defined by the IANA.
 
291
(If you prefer to use the international currency symbol rather than
 
292
the Euro symbol in external text then you might want to set this to
 
293
.B ISO-8859-1\c
 
294
, aka
 
295
.B Latin1\c
 
296
\&.)
 
297
.TP
 
298
.B \-version
 
299
prints three or more lines of version information, as follows:
 
300
.RS
 
301
.TP
 
302
\ \ \ \(bu
 
303
the architecture configured for the virtual machine at compile time,
 
304
the compilation `sequence number', the time and date of compilation,
 
305
and the name (and version, if known) of the compiler that was used to
 
306
compile
 
307
.B squeak\c
 
308
;
 
309
.TP
 
310
\ \ \ \(bu
 
311
the complete
 
312
.BR uname (1)
 
313
information for the host on which the virtual machine was compiled;
 
314
.TP
 
315
\ \ \ \(bu
 
316
the default installed location for plugins and drivers;
 
317
.PP
 
318
After printing the above, the virtual machine exits.
 
319
.RE
 
320
.TP
 
321
.BI "\-vm " "driver"
 
322
asks
 
323
.B squeak
 
324
to load a sound/display driver.  For each supported device there is a
 
325
corresponding driver that
 
326
.B squeak
 
327
loads during initialisation.  Unless told otherwise,
 
328
.B squeak
 
329
will figure out sensible default drivers to load.  This choice can be
 
330
overridden using this option.  The
 
331
.I driver
 
332
argument is a list of one or more 'assignments' of the form
 
333
.sp
 
334
\ \ \ \ 
 
335
.I class\c
 
336
=\c
 
337
.I device
 
338
.sp
 
339
separated by spaces or commas.  The supported combinations are currently:
 
340
.RS
 
341
.TP
 
342
.B \ \ \ display=X11
 
343
to display the Squeak window on a local or remote X Window System
 
344
server.
 
345
.TP
 
346
.B \ \ \ display=Quartz
 
347
to display on the local Mac OS X desktop.
 
348
.TP
 
349
.B \ \ \ display=none
 
350
to disable the display (and keyboard/mouse) entirely.  (This driver is
 
351
useful primarily for running 'server' applications in Squeak.)
 
352
.TP
 
353
.B \ \ \ sound=OSS
 
354
provides sound input and output via the Open Sound System.  (If you
 
355
have a device called '/dev/dsp' then this is likely the one you
 
356
want.)
 
357
.TP
 
358
.B \ \ \ sound=MacOSX
 
359
provides sound input/output via Core Audio on Mac OS X.
 
360
.TP
 
361
.B \ \ \ sound=NAS
 
362
provides sound i/o via the Network Audio System.
 
363
.TP
 
364
.B \ \ \ sound=Sun
 
365
provides sound on Sun Microsystems hardware.
 
366
.TP
 
367
.B \ \ \ sound=none
 
368
disables sound entirely.
 
369
.B squeak
 
370
will not attempt to play or record sounds when this driver is loaded.
 
371
.RE
 
372
.PP
 
373
.RS
 
374
Note that only those drivers relevant to the local platform will be
 
375
available.  Attempting to load an unsupported driver will cause
 
376
.B squeak
 
377
to exit with an error message.  A list of available drivers is printed
 
378
by the '-help' option.  If a particular driver cannot load system
 
379
libraries on which it depends then it will neither be listed nor
 
380
be available to load at runtime.
 
381
.RE
 
382
.PP
 
383
.RS
 
384
Note also that on Mac OS X both the X11 and Quartz display drivers are
 
385
supported, although the former will refuse to load if the X11 client
 
386
libraries are not installed on the local machine.  The Quartz driver
 
387
will happily load (and Squeak will run as a fully-fledged application)
 
388
even when
 
389
.B squeak
 
390
is invoked from the command line.  Exercise caution when logged into
 
391
Mac OS X from another machine: forgetting to set DISPLAY before trying
 
392
to run
 
393
.B squeak
 
394
on the remote display could cause embarrassement.
 
395
.RE
 
396
.PP
 
397
Options specific to the X11 display driver are as follows:
 
398
.TP
 
399
.BI "\-browserWindow " "id"
 
400
specifies the
 
401
.I id
 
402
of the window that
 
403
.B squeak
 
404
should use for its display.  This option is intended for use when Squeak is
 
405
running as a web browser plugin.
 
406
.TP
 
407
.BI "\-display " "server"
 
408
specifies that Squeak should connect to the given display
 
409
.I server 
 
410
instead of looking in the environment variable
 
411
.B
 
412
DISPLAY
 
413
(the default behaviour) to find the name of the server to use.
 
414
.TP
 
415
.BI "\-cmdmod " "N"
 
416
tells the VM to map modifier key
 
417
.I N
 
418
on the keyboard to the modifier code that the image expects for the Command key.
 
419
.TP
 
420
.BI "\-optmod " "N"
 
421
tells the VM to map modifier key
 
422
.I N
 
423
on the keyboard to the modifier code that the image expects for the Option key.
 
424
.TP
 
425
.B \-compositioninput
 
426
enables support for an overlay window in which individual characters
 
427
(e.g., Japanese hiragana) are composed before being interpreted as a
 
428
single character (e.g., Japanese kanji) by the image.
 
429
.TP
 
430
.BI "\-xicfont " "font"
 
431
tells the VM to use the named
 
432
.I font
 
433
within the composition overlay window.
 
434
.TP
 
435
.B \-fullscreen
 
436
causes the Squeak window to occupy as much of the screen area as possible.
 
437
Implies '\c
 
438
.B \-notitle\c
 
439
\&'.
 
440
.TP
 
441
.B \-headless
 
442
disables the graphical display and mouse/keyboard input.  This mode of
 
443
operation is useful primarily for servers.
 
444
.TP
 
445
.B \-iconic
 
446
asks the window manager to iconify the Squeak window at startup.
 
447
.TP
 
448
.B \-lazy
 
449
causes Squeak to `snooze' whenever the main winodw is unmapped.  This can
 
450
be used if Squeak appears to be using consuming CPU time while idling (which should
 
451
not normally be the case).  Note that if this option is in effect, when the
 
452
Squeak window is unmapped
 
453
.B squeak
 
454
will not respond to any external stimuli (other than to provide the X
 
455
selection to requestors, when Squeak is the owner).
 
456
.TP
 
457
.B \-mapdelbs
 
458
maps the Delete key onto Backspace.  Backspace deletes the character to the left
 
459
of the cursor and Delete normally deletes the character
 
460
to the right of the cursor.  With this option, Deletes will behave like
 
461
Backspace.  The behaviour of Backspace is not changed.
 
462
.TP
 
463
.B \-noxdnd
 
464
disables support for the X drag-and-drop protocol.
 
465
.TP
 
466
.B \-nointl
 
467
disables the handling of dead keys on international keyboards.
 
468
Without this option, dead key handling is enabled if either
 
469
.B LC_ALL
 
470
or
 
471
.B LC_CTYPE
 
472
is set in the environment.
 
473
.TP
 
474
.B \-notitle
 
475
disables the title bar on the Squeak window (if the window manager supports it).
 
476
This option is implied by '\c
 
477
.B \-fullscreen\c
 
478
\&'.
 
479
.TP
 
480
.B \-swapbtn
 
481
swaps the yellow and blue buttons.   (Traditionally, the red button is on
 
482
the left, yellow in the middle and blue on the right.  The colourful names
 
483
come from the Xerox Alto on which Smalltalk was first implemented.)
 
484
Squeak normally maps X buttons 1, 2 and 3 to the
 
485
.B red\c
 
486
, 
 
487
.B yellow
 
488
and 
 
489
.B blue
 
490
buttons, in that order.  With this option, it maps X buttons
 
491
1, 2 and 3 to the
 
492
.B red\c
 
493
, 
 
494
.B blue
 
495
and
 
496
.B yellow
 
497
buttons.)
 
498
.TP
 
499
.B \-xasync
 
500
causes Squeak to use asynchronous display updates.  The virtual machine normally
 
501
flushes and synchronises the display connection at regular intervals.  Using this
 
502
option disables synchronisation, which will be performed only when the image
 
503
explicitly requests it.
 
504
.TP
 
505
.B \-xshm
 
506
enables the use of the X Shared Memory extension on servers that support it.
 
507
This can dramatically improve display performance, but works only when
 
508
Squeak is running on the server.
 
509
.PP
 
510
Options specific to the FBDev display driver are as follows:
 
511
.TP
 
512
.BI "\-fbdev " "device"
 
513
Use the given framebuffer
 
514
.I device
 
515
instead of the default '/dev/fb0'.
 
516
.TP
 
517
.BI "\-kbmap " "mapfile"
 
518
Load the keyboard map from the given
 
519
.I mapfile
 
520
instead of reading it from the running kernel.
 
521
Note that
 
522
.B squeak
 
523
cannot (currently) read compressed or 'shorthand'
 
524
map files (as found in /usr/share/keymaps or /lib/kbd/keymaps).
 
525
To generate a keymap file usable by
 
526
.B squeak\c
 
527
\&, execute the following program from the console:
 
528
.sp
 
529
\ \ \ \ dumpkeys -f -n --keys-only > key.map
 
530
.sp
 
531
If
 
532
.B squeak
 
533
encounters a problem while trying to load
 
534
.I mapfile\c
 
535
\&, it will print an error message and exit.
 
536
See
 
537
.BR keymaps (5)
 
538
for more information about the keymap file format.  The programs
 
539
.BR dumpkeys (1)\c
 
540
,
 
541
.BR loadkeys (1)\c
 
542
, and
 
543
.BR showkey (1)
 
544
can be used to modify the keyboard map before creating a keymap file
 
545
for
 
546
.B squeak\c
 
547
\&.
 
548
.TP
 
549
.BI "\-msdev " "device"
 
550
Use the given mouse
 
551
.I device
 
552
instead of the default.  The default is to try
 
553
\&'/dev/psaux', '/dev/input/mice' and '/dev/adbmouse',
 
554
in that order, and to use the first one that has a physical device attached.
 
555
.TP
 
556
.BI "\-msproto " "protocol"
 
557
Use the given mouse
 
558
.I protocol
 
559
instead of the default.  The supported protocols are 'ps2' and 'adb'.
 
560
The default is 'ps2' for mice attached to '/dev/psaux' or '/dev/input/mice',
 
561
and 'adb' for mice attached to '/dev/adbmouse'.
 
562
.TP
 
563
.B \-vtlock
 
564
Disallows VT switching, regardless of whether the request comes from
 
565
the keyboard or from another program such as
 
566
.BR chvt (1)\c
 
567
\&.
 
568
.TP
 
569
.B \-vtswitch
 
570
Enables keyboard VT switching.  Note that this option is effectively
 
571
disabled if the '\c
 
572
.B \-vtlock\c
 
573
\&' option is also enabled.
 
574
.PP
 
575
Options specific to the OSS and MacOSX sound drivers are as follows:
 
576
.TP
 
577
.B \-nomixer
 
578
disables the primitives that change mixer (sound) settings.  If you
 
579
prefer that Squeak leave these alone (they are, after all, really the
 
580
reponsibility of whichever mixer program or sound control panel you
 
581
use) then this option is for you.
 
582
.PP
 
583
Options specific to the ALSA sound driver are as follows:
 
584
.TP
 
585
.BI "\-capture " "device"
 
586
Uses the named input
 
587
.I device
 
588
for sound capture.
 
589
.TP
 
590
.BI "\-playback " "device"
 
591
Uses the named output
 
592
.I device
 
593
for sound playback.
 
594
.PP
 
595
Several common options are deprecated and are provided only for
 
596
backward compatibility.  These options should not be used and will be
 
597
removed in a future release:
 
598
.TP
 
599
.BI "\-display " "dpy"
 
600
is equivalent to '\-vm display=X11 \-display
 
601
.I dpy\c
 
602
\&'.
 
603
.TP
 
604
.B \-headless
 
605
is equivalent to '\-vm display=X11 \-headless'.
 
606
.TP
 
607
.B \-nodisplay
 
608
is equivalent to '\-vm display=none'.
 
609
.TP
 
610
.B \-nosound
 
611
is equivalent to '\-vm sound=none'.
 
612
.TP
 
613
.B \-quartz
 
614
is equivalent to '-vm display=Quartz'.
 
615
.SH ENVIRONMENT
 
616
Many of the options that can be set on the command line can
 
617
also be set from environment variables.
 
618
.TP
 
619
.B SQUEAK_ASYNC
 
620
if set in the environment then equivalent to the '\c
 
621
.B \-xasync\c
 
622
\&' flag.  (The value is ignored.)
 
623
.TP
 
624
.B SQUEAK_CAPTURE
 
625
see '\c
 
626
.B \-capture\c
 
627
\&'.
 
628
.TP
 
629
.B SQUEAK_COMPOSITIONINPUT
 
630
if set in the environment then equivalent to the '\c
 
631
.B \-compositioninput\c
 
632
\&' flag.  (The value is ignored.)
 
633
.TP
 
634
.B SQUEAK_ENCODING
 
635
the name of the internal character encoding used by Squeak.  Equivalent to giving the '\c
 
636
.B \-encoding\c
 
637
\&' command-line option if set.
 
638
.TP
 
639
.B SQUEAK_FBDEV
 
640
the name of the framebuffer device to use when running on the console.  See the '\c
 
641
.B \-fbdev\c
 
642
\&' option.
 
643
.TP
 
644
.B SQUEAK_FULLSCREEN
 
645
equivalent to '\c
 
646
.B \-fullscreen\c
 
647
\&' if set.
 
648
.TP
 
649
.B SQUEAK_ICONIC
 
650
equivalent to the '\c
 
651
.B \-iconic\c
 
652
\&' flag.
 
653
.TP
 
654
.B SQUEAK_IMAGE
 
655
the name of the image file to execute if no
 
656
.I image
 
657
argument is given on the command line.
 
658
.TP
 
659
.B SQUEAK_KBMAP
 
660
the name of the keymap file to use when running on the console.  See the '\c
 
661
.B \-kbmap\c
 
662
\&' option.
 
663
.TP
 
664
.B SQUEAK_LAZY
 
665
equivalent to the '\c
 
666
.B \-lazy\c
 
667
\&' flag.
 
668
.TP
 
669
.B SQUEAK_MAPDELBS
 
670
equivalent to the '\c
 
671
.B \-mapdelbs\c
 
672
\&' flag.
 
673
.TP
 
674
.B SQUEAK_MEMORY
 
675
the initial size of the heap, with optional 'k' or 'm' suffix.  Equivalent
 
676
to the '\c
 
677
.BI "-memory " size [km]\c
 
678
\&' flag.
 
679
.TP
 
680
.B SQUEAK_MSDEV
 
681
the name of the mouse device to use when running on the console.  See the '\c
 
682
.B \-msdev\c
 
683
\&' option.
 
684
.TP
 
685
.B SQUEAK_MSPROTO
 
686
the name of the mouse protocl to use when running on the console.  See the '\c
 
687
.B \-msproto\c
 
688
\&' option.
 
689
.TP
 
690
.B SQUEAK_VTLOCK
 
691
if set then equivalent to specifying the '\c
 
692
.B \-vtlock\c
 
693
\&' option on the command line.
 
694
.TP
 
695
.B SQUEAK_VTSWITCH
 
696
if set then equivalent to specifying the '\c
 
697
.B \-vtswitch\c
 
698
\&' option on the command line.
 
699
.TP
 
700
.B SQUEAK_NOEVENTS
 
701
if set, equivalent to '\c
 
702
.B \-noevents\c
 
703
\&'.
 
704
.TP
 
705
.B SQUEAK_NOINTL
 
706
equivalent to '\c
 
707
.B \-nointl\c
 
708
\&' if set.
 
709
.TP
 
710
.B SQUEAK_NOMIXER
 
711
equivalent to '\c
 
712
.B \-nomixer\c
 
713
\&' if set.
 
714
.TP
 
715
.B SQUEAK_NOTIMER
 
716
equivalent to '\c
 
717
.B \-notimer\c
 
718
\&' if set.
 
719
.TP
 
720
.B SQUEAK_NOTITLE
 
721
if set, equivalent to '\c
 
722
.B \-notitle\c
 
723
\&'.
 
724
.TP
 
725
.B SQUEAK_PATHENC
 
726
the name of the character encoding used to construct file and directory names.
 
727
Equivalent to giving the '\c
 
728
.B \-pathenc\c
 
729
\&' command-line option if set.
 
730
.TP
 
731
.B SQUEAK_PLAYBACK
 
732
see '\c
 
733
.B \-playback\c
 
734
\&'.
 
735
.TP
 
736
.B SQUEAK_PLUGINS
 
737
see '\c
 
738
.B \-plugins\c
 
739
\&'.
 
740
.TP
 
741
.B SQUEAK_SWAPBTN
 
742
equivalent to '\c
 
743
.B \-swapbtn\c
 
744
\&' if set.
 
745
.TP
 
746
.B SQUEAK_TEXTENC
 
747
the name of the character encoding used to copy/paste text from/to external applications.
 
748
Equivalent to giving the '\c
 
749
.B \-textenc\c
 
750
\&' command-line option if set.
 
751
.TP
 
752
.B SQUEAK_VM
 
753
contains the names of one or more drivers to be loaded during initialisation.
 
754
See the '\c
 
755
.B \-vm\c
 
756
\&' option for details.
 
757
.TP
 
758
.B SQUEAK_XICFONT
 
759
if set in the environment then it provides a default name for the composition overlay font; see the '\c
 
760
.B \-xicfont\c
 
761
\&' flag.
 
762
.TP
 
763
.B SQUEAK_XSHM
 
764
equivalent to '\c
 
765
.B \-xshm\c
 
766
\&'.
 
767
.PP
 
768
If an environment variable and a command-line option conflict over a
 
769
particular value then normally the value in the command line takes
 
770
precedence.  The exception to this rule is the '\-vm' option.
 
771
Environment variables are processed before command-line arguments and
 
772
\&'\-vm' cannnot be used to unload a driver that was loaded while
 
773
processing the contents of 'SQUEAK_VM'.
 
774
.PP
 
775
.B squeak
 
776
also checks the environment for
 
777
.B LC_ALL
 
778
and
 
779
.B LC_CTYPE\c
 
780
\&.  If either of these variables is set then support for
 
781
international keyboards (including dead keys for diacritical marks) is
 
782
enabled.  To prevent this support being enabled even when one or both
 
783
of these variables is set, use the '\-nointl' option (or set
 
784
.B SQUEAK_NOINTL
 
785
in the environment).  For example, to start
 
786
.B squeak
 
787
with support for dead keys on Spanish keyboards, with Latin-1 encoding
 
788
of external characters and the default MacRoman internal font
 
789
encoding, run
 
790
.B squeak
 
791
like this:
 
792
.sp
 
793
.RS
 
794
.nf
 
795
export LC_CTYPE=es_ES
 
796
export SQUEAK_TEXTENC=latin1
 
797
squeak
 
798
.fi
 
799
.RE
 
800
.SH SCRIPTS
 
801
Squeak can load and execute a 'script' file containing Smalltalk code at
 
802
startup.  The name of the file should be given as the
 
803
.I script
 
804
argument to
 
805
.B squeak\c
 
806
\&.
 
807
For example, assuming that the image 'foo.image'
 
808
contains an open Transcript window, then the following represents
 
809
the 'hello world' program for Squeak:
 
810
.sp
 
811
.RS
 
812
.nf
 
813
Transcript cr; show: 'Hello, world'.
 
814
.fi
 
815
.RE
 
816
.sp
 
817
If this script is in a file called 'hello.sq', then it could be run like this:
 
818
.sp
 
819
.RS
 
820
.nf
 
821
squeak foo.image hello.sq
 
822
.fi
 
823
.RE
 
824
.PP
 
825
It is also possible to make 'self interpreting' scripts by adding an 'interpreter
 
826
line' to the start of the script.  The 'hello.sq' file could be changed to
 
827
.sp
 
828
.RS
 
829
.nf
 
830
#![bindir]/squeak --
 
831
Transcript cr; show: 'Hello, world'.
 
832
.fi
 
833
.RE
 
834
.sp
 
835
and then made executable with
 
836
.sp
 
837
.RS
 
838
.nf
 
839
chmod +x hello.sq
 
840
.fi
 
841
.RE
 
842
.sp
 
843
and then invoked by running the script file directly:
 
844
.sp
 
845
.RS
 
846
.nf
 
847
SQUEAK_IMAGE="foo.image"
 
848
export SQUEAK_IMAGE
 
849
\&./hello.sq
 
850
.fi
 
851
.RE
 
852
.PP
 
853
If any
 
854
.I argument\c
 
855
s are present after the
 
856
.I script
 
857
name then they can be retrieved from within the script using the method
 
858
.sp
 
859
.RS
 
860
.nf
 
861
Smalltalk getSystemAttribute: \c
 
862
.I n
 
863
.fi
 
864
.RE
 
865
.sp
 
866
where
 
867
.I n
 
868
is the index of the argument, starting at 3 for the first argument.  (See the
 
869
method comment for
 
870
.sp
 
871
.RS
 
872
.nf
 
873
SystemDictionary>>getSystemAttribute:
 
874
.fi
 
875
.RE
 
876
.sp
 
877
in the image for an explanation of the meanings of the indices.)
 
878
.PP
 
879
As an example of this, here is the 'echo' program written as a Squeak script:
 
880
.sp
 
881
.RS
 
882
.nf
 
883
#![bindir]/squeak --
 
884
"Echo arguments to the Transcript."
 
885
| i a |
 
886
i := 2.
 
887
[(a := Smalltalk getSystemAttribute: (i := i + 1))
 
888
    notNil]
 
889
  whileTrue: [Transcript space; show: a].
 
890
.fi
 
891
.RE
 
892
.sp
 
893
When run as
 
894
.sp
 
895
.RS
 
896
.nf
 
897
\&./echo.sq one two three
 
898
.fi
 
899
.RE
 
900
.sp
 
901
this would print 'one two three' in the Transcript window.
 
902
.SH DIAGNOSTICS
 
903
.TP
 
904
.B inisqueak
 
905
prints several informational messages while doing its stuff.  If it encounters
 
906
a problem it prints an appropriate message before bailing out.  The messages
 
907
should be self-explanatory.
 
908
.TP
 
909
.B squeak
 
910
normally does not print anything at all.  If it prints something then there
 
911
is a problem.  The messages should be self-explanatory.
 
912
.\" .PP
 
913
.\" Sending
 
914
.\" .B squeak
 
915
.\" a SIGHUP or SIGQUIT signal will cause it dump the executing image into
 
916
.\" the working directy and then exit.  Both of these should be
 
917
.\" considered 'last resort' measures to save an image that contains
 
918
.\" valuable recent changes.  SIGHUP is synchronous (it works when the VM
 
919
.\" is in a known state) and the chances of obtaining a working image are
 
920
.\" fairly good, but it relies on the event polling loop being called.
 
921
.\" SIGQUIT is asynchronous, and the chances of recovering a working image
 
922
.\" after using it are fairly poor.  In either case, when restaring the
 
923
.\" "dumped" image, the first think that should be done is to execute
 
924
.\" .sp
 
925
.\" .RS
 
926
.\" .nf
 
927
.\" Smalltalk processStartUpList: true
 
928
.\" .fi
 
929
.\" .RE
 
930
.\" .sp
 
931
.\" in a workspace.  Recover what is needed from the image, then destroy
 
932
.\" the image (whose integrity should certainly not be trusted).
 
933
.SH FILES
 
934
.I [imgdir]/SqueakV[major].sources
 
935
.RS
 
936
Shared system sources file for the Squeak image.  There must be a
 
937
copy of (or link to) this file in the working directory when running
 
938
.B squeak\c
 
939
\&.
 
940
.RE
 
941
.sp
 
942
.I [imgdir]/Squeak*.image
 
943
.I [imgdir]/Squeak*.changes
 
944
.RS
 
945
Distributed image and changes files holding a `shapshot' of a
 
946
live Squeak session.  (The contents of these files change during a
 
947
session, and so private copies should always be made before running
 
948
.B squeak
 
949
for the first time.  See
 
950
.BR inisqueak (1)\c
 
951
).
 
952
.RE
 
953
.sp
 
954
.I ./SqueakV[major].sources
 
955
.RS
 
956
A link to the system sources file.
 
957
.RE
 
958
.sp
 
959
.IR ./ name .image
 
960
.br
 
961
.IR ./ name .changes
 
962
.RS
 
963
Private copies of image and changes files.
 
964
.RE
 
965
.sp
 
966
.I [plgdir]/*.so
 
967
.br
 
968
.I [plgdir]/*.la
 
969
.RS
 
970
Virtual machine 'plugins' (containing primitives that are loaded on
 
971
demand) and drivers (for different types of display and sound
 
972
hardware).
 
973
.RE
 
974
.sp
 
975
.I [bindir]/squeak
 
976
.br
 
977
.I [bindir]/inisqueak
 
978
.RS
 
979
The Squeak virtual machine and personal image installer script.
 
980
.RE
 
981
.sp
 
982
.I [mandir]/squeak.1
 
983
.RS
 
984
This manual page.
 
985
.RE
 
986
.sp
 
987
.I [docdir]/*
 
988
.RS
 
989
Miscellaneous documentation.
 
990
.RE
 
991
.SH NOTES
 
992
This manual page documents version [version] of Unix Squeak.  It may
 
993
not be appropriate for any other version.
 
994
.PP
 
995
The image and changes files containing a saved Squeak session are
 
996
intimately related.  They should always be used together, never be
 
997
separated, and under no circumstances should an image be run with a
 
998
changes file that has been used with a different image.  Failure to
 
999
adhere to the above could cause the source code for the methods in the
 
1000
image to become garbled and impossible to retrieve.
 
1001
.PP
 
1002
The Unix Squeak virtual machine fully supports OpenGL in both the X11
 
1003
and Quartz display drivers.  Open Croquet will run just fine with
 
1004
either of these drivers (and many Mac OS X users will even have the
 
1005
choice of which driver to use :).
 
1006
.SH BUGS
 
1007
If a 'binary' option is enabled by an environment variable, there is no
 
1008
way to disable it on the command line.
 
1009
.PP
 
1010
Similarly, drivers specified in the
 
1011
.I SQUEAK_VM
 
1012
environment variable cannot be overridden by passing options on the
 
1013
command line.
 
1014
.PP
 
1015
.B squeak
 
1016
should never crash.  In the unlikely event that it does crash, or
 
1017
prints any kind of message that
 
1018
.I does not
 
1019
appear to be caused by incorrect arguments or illegal operations from
 
1020
within a Squeak program, please send a bug report to:
 
1021
<ian.piumarta@squeakland.org>.  (Do not send bug reports to the
 
1022
general-purpose 'squeak-dev' mailing list.  They will not be read.  If
 
1023
you feel you must post a bug report to a mailing list, send it to the
 
1024
Squeak 'vm-dev' mailing list in addition to the above email address.)
 
1025
.SH AUTHOR
 
1026
This manual page was written by Ian Piumarta.
 
1027
.SH SEE ALSO
 
1028
Dan Ingalls, Ted Kaehler, John Maloney, Scott Wallace and Alan Kay, \c
 
1029
.I Back to the Future: The Story of Squeak, A Practical Smalltalk Written in Itself\c
 
1030
\&.  Proc. OOPSLA'97.
 
1031
.PP
 
1032
The official Squeak home page:
 
1033
.RS
 
1034
.B http://squeak.org
 
1035
.RE
 
1036
.PP
 
1037
The general-purpose 'squeak-dev' mailing list (not for VM-related bug reports):
 
1038
.RS
 
1039
.B http://lists.squeakfoundation.org/listinfo/squeak-dev
 
1040
.RE
 
1041
.PP
 
1042
The Squeak 'vm-dev' mailing list (amongst others):
 
1043
.RS
 
1044
.B http://discuss.squeakfoundation.org/
 
1045
.RE
 
1046
.PP
 
1047
The latest source and binary distributions of Unix Squeak:
 
1048
.RS
 
1049
.B http://squeakvm.org/unix
 
1050
.RE
 
1051
.\".PP
 
1052
.\"The list of IANA-registered character encoding names, of which a proper subset is recognised by Squeak:
 
1053
.\".RS
 
1054
.\".B http://www.iana.org/assignments/character-sets
 
1055
.\".RE