1SQUEAK(1) Squeak Smalltalk System SQUEAK(1)
2
6 squeak, inisqueak - Unix Squeak virtual machine and installer
7
9 inisqueak
10 squeak [ option... ] [ image ] [ script [ argument... ] ]
11
13 squeak is the virtual machine for the Squeak Smalltalk system. It
14 requires three files to operate correctly: an image file containing a
15 `snapshot' of a live Squeak session, a changes file containing the
16 source code for modified methods in the image, and a copy of (or a link
17 to) a shared system sources file containing the source code for methods
18 that have not been modified since the last major version increment.
19 The image and changes files contain the state of a user's Squeak ses‐
21 sion, which is persistent between consecutive sessions. Private copies
22 of these files are therefore normally required. The inisqueak script
23 checks that the local Squeak installation appears sane, and then copies
24 the required files to the current working directory. If inisqueak
25 encounters no problems, it will finish by running squeak to start a
26 Squeak session using the newly copied image and changes files.
27 inisqueak should be run once, when using Squeak for the first time, to
29 create a new 'personal' Squeak session. Afterwards, squeak should be
30 run each time that session is to be resumed.
31
33 inisqueak has no options or arguments. Simply 'cd' to the directory
34 that is to contain the working copies of the image and changes files,
35 then run it.
36 squeak accepts various options (described below), and then an optional
38 image name (which must not begin with a minus sign '-'). If an image
39 name is given on the command line then squeak tries to run that image.
40 Otherwise squeak checks the environment variable SQUEAK_IMAGE and, if
41 it is set, uses its value as the name of the image to run. Otherwise
42 squeak looks for an image called 'squeak.image' in the current direc‐
43 tory. If the image file does not exist then squeak prints a message
44 indicating which image file it failed to find and then exits. If the
45 extension '.image' is missing in the image argument or in the value of
46 the SQUEAK_IMAGE variable, it will be appended automatically.
47 The image argument can be followed by a script name. This is the name
49 of a 'document' that should contain Smalltalk code to be executed on
50 startup. The document can be either the name of a file or a URL start‐
51 ing with 'http:'. Any arguments that appear after the script name are
52 ignored, but are made available to the script from within Squeak via
53 the method getSystemAttribute:. (See the section SCRIPTS below.)
54 If image is given as '--' then squeak immediately stops argument pro‐
56 cessing (and behaves as if image was not specified). This is useful to
57 specify a script (possibly with script arguments) without specifying an
58 explicit image.
59
61 Command line options fall into two categories: 'common' options that
62 are recognised by the base VM and 'specific' options that are tied to a
63 particular display or sound driver. Common options will always be
64 recognised by squeak, whereas a given specific option will be recog‐
65 nised only after squeak has loaded the driver to which it relates.
66 Refer to the '-vm' option below for more details.
67 The common options recognised by squeak are as follows:
69 -encoding enc
71 specifies the internal character encoding to be used by Squeak.
72 This affects the translation that the VM performs when importing
73 text (from the keyboard or via 'paste' from an external selec‐
74 tion) or exporting text (pasting text from Squeak to another
75 application, or when generating filenames containing special
76 characters). In other words, it affects the correspondence
77 between what Squeak displays on the screen and what it sends to
78 (or receives from) external applications. The correct value
79 depends on the way Squeak's internal fonts are encoded. Current
80 images are delivered with traditional Macintosh 'New York' fonts
81 that use Mac Roman encoding, and so this is the default internal
82 encoding. If other fonts (from X11 or elsewhere) are imported
83 into the image and used as system fonts then the this default
84 translation will give incorrect results for diacritical marks
85 and special characters. In such cases the -encoding option can
86 be used to change the internal encoding, for example
87 -encoding ISO-8859-15
89 (aka Latin9) which would be appropriate for many of the fonts
91 designed for European languages.
92 -help prints a short summary of the command-line syntax, options and
94 available drivers, then exits.
95 -memory size[mk]
97 requests that a fixed heap of size bytes be allocated for the
98 Squeak image. If the suffix `k' is given then the argument is
99 expressed in kilobytes. If the suffux `m' is given then the
100 argument is expressed in megabytes. This option SHOULD NOT be
101 used, unless there is a good reason to do so, since it places an
102 arbitrary limit on Squeak's object memory size.
103 -mmap size[mk]
105 requests that a variable heap of at most size bytes be allo‐
106 cated. (The suffixes are as described for the '-memory'
107 option.) squeak will initially allocate a heap that is large
108 enough to hold the image, with a small amount of headroom. If
109 at any time Squeak requires more memory for its image then addi‐
110 tional space will be allocated dynamically. Likewise, when mem‐
111 ory is no longer needed it will deallocated and returned to the
112 system. The size argument places an upper limit on how big the
113 heap can grow in this fashion. squeak uses a dynamic heap by
114 default with the maximum size set to 75% of the available vir‐
115 tual memory or 1 gigabyte, whichever is smaller.
116 -noevents
118 disables the new (image 2.8 and later) event-driven input mecha‐
119 nism. This option is only useful for testing backwards compati‐
120 bility with older images and should not be used.
121 -notimer
123 disables the use of the interval timer for keeping track of low-
124 resolution time. (If you are having problems with file, sound
125 or socket i/o reporting `interrupted system call' then setting
126 this flag might help.)
127 -pathenc enc
129 specifies the external character encoding to be used by Squeak
130 when accessing the filesystem (file and directory pathnames).
131 The correct value depends on the local platform's characteris‐
132 tics. If no encoding conversion should be performed then this
133 should be set to the same encoding as Squeak uses internally
134 (see the -encoding option). Otherwise ISO-8859-15 (aka Latin9)
135 might make sense on a filesystem supporting 8-bit characters,
136 and UTF-8 for filesystems that use Unicode-based pathnames. The
137 default is UTF-8 which is correct for Mac OS X and very recent
138 GNU/Linux distributions, and which (in an ideal world) will
139 eventually be adopted by all Unix variants.
140 -plugins path
142 specifies an alternative location for external plugins (collec‐
143 tions of named primitives) and drivers (for display and sound).
144 The path argument contains a pattern in which any occurrences of
145 `%n' will be replaced by the name of the plugin or driver being
146 loaded. The path can name either a directory or the plugin
147 itself and can be absolute or relative (to the directory in
148 which squeak was run). If a plugin or driver cannot be found in
149 the location specified by path then the search continues in the
150 default locations.
151 -textenc enc
153 specifies the external character encoding to be used by Squeak
154 when exchanging clipboard text with other applications. The
155 default is UTF-8 on Mac OS X and ISO-8859-15 (aka Latin9) on
156 other Unix systems. Note that X11 applications requesting the
157 selection converted to UTF8_STRING data will (correctly) receive
158 the clipboard text encoded as UTF-8, regardless of this setting.
159 Squeak recognises a subset of the encoding names defined by the
161 IANA. (If you prefer to use the international currency symbol
162 rather than the Euro symbol in external text then you might want
163 to set this to ISO-8859-1, aka Latin1.)
164 -version
166 prints three or more lines of version information, as follows:
167 · the architecture configured for the virtual machine at
169 compile time, the compilation `sequence number', the time
170 and date of compilation, and the name (and version, if
171 known) of the compiler that was used to compile squeak;
172 · the complete uname(1) information for the host on which
174 the virtual machine was compiled;
175 · the default installed location for plugins and drivers;
177 After printing the above, the virtual machine exits.
179 -vm driver
181 asks squeak to load a sound/display driver. For each supported
182 device there is a corresponding driver that squeak loads during
183 initialisation. Unless told otherwise, squeak will figure out
184 sensible default drivers to load. This choice can be overridden
185 using this option. The driver argument is a list of one or more
186 'assignments' of the form
187 class=device
189 separated by spaces or commas. The supported combinations are
191 currently:
192 display=X11
194 to display the Squeak window on a local or remote X Win‐
195 dow System server.
196 display=Quartz
198 to display on the local Mac OS X desktop.
199 display=none
201 to disable the display (and keyboard/mouse) entirely.
202 (This driver is useful primarily for running 'server'
203 applications in Squeak.)
204 sound=OSS
206 provides sound input and output via the Open Sound Sys‐
207 tem. (If you have a device called '/dev/dsp' then this
208 is likely the one you want.)
209 sound=MacOSX
211 provides sound input/output via Core Audio on Mac OS X.
212 sound=NAS
214 provides sound i/o via the Network Audio System.
215 sound=Sun
217 provides sound on Sun Microsystems hardware.
218 sound=none
220 disables sound entirely. squeak will not attempt to play
221 or record sounds when this driver is loaded.
222 Note that only those drivers relevant to the local platform will
224 be available. Attempting to load an unsupported driver will
225 cause squeak to exit with an error message. A list of available
226 drivers is printed by the '-help' option. If a particular
227 driver cannot load system libraries on which it depends then it
228 will neither be listed nor be available to load at runtime.
229 Note also that on Mac OS X both the X11 and Quartz display driv‐
231 ers are supported, although the former will refuse to load if
232 the X11 client libraries are not installed on the local machine.
233 The Quartz driver will happily load (and Squeak will run as a
234 fully-fledged application) even when squeak is invoked from the
235 command line. Exercise caution when logged into Mac OS X from
236 another machine: forgetting to set DISPLAY before trying to run
237 squeak on the remote display could cause embarrassement.
238 Options specific to the X11 display driver are as follows:
240 -browserWindow id
242 specifies the id of the window that squeak should use for its
243 display. This option is intended for use when Squeak is running
244 as a web browser plugin.
245 -display server
247 specifies that Squeak should connect to the given display server
248 instead of looking in the environment variable DISPLAY (the
249 default behaviour) to find the name of the server to use.
250 -cmdmod N
252 tells the VM to map modifier key N on the keyboard to the modi‐
253 fier code that the image expects for the Command key.
254 -optmod N
256 tells the VM to map modifier key N on the keyboard to the modi‐
257 fier code that the image expects for the Option key.
258 -compositioninput
260 enables support for an overlay window in which individual char‐
261 acters (e.g., Japanese hiragana) are composed before being
262 interpreted as a single character (e.g., Japanese kanji) by the
263 image.
264 -xicfont font
266 tells the VM to use the named font within the composition over‐
267 lay window.
268 -fullscreen
270 causes the Squeak window to occupy as much of the screen area as
271 possible. Implies '-notitle'.
272 -headless
274 disables the graphical display and mouse/keyboard input. This
275 mode of operation is useful primarily for servers.
276 -iconic
278 asks the window manager to iconify the Squeak window at startup.
279 -lazy causes Squeak to `snooze' whenever the main winodw is unmapped.
281 This can be used if Squeak appears to be using consuming CPU
282 time while idling (which should not normally be the case). Note
283 that if this option is in effect, when the Squeak window is
284 unmapped squeak will not respond to any external stimuli (other
285 than to provide the X selection to requestors, when Squeak is
286 the owner).
287 -mapdelbs
289 maps the Delete key onto Backspace. Backspace deletes the char‐
290 acter to the left of the cursor and Delete normally deletes the
291 character to the right of the cursor. With this option, Deletes
292 will behave like Backspace. The behaviour of Backspace is not
293 changed.
294 -noxdnd
296 disables support for the X drag-and-drop protocol.
297 -nointl
299 disables the handling of dead keys on international keyboards.
300 Without this option, dead key handling is enabled if either
301 LC_ALL or LC_CTYPE is set in the environment.
302 -notitle
304 disables the title bar on the Squeak window (if the window man‐
305 ager supports it). This option is implied by '-fullscreen'.
306 -swapbtn
308 swaps the yellow and blue buttons. (Traditionally, the red
309 button is on the left, yellow in the middle and blue on the
310 right. The colourful names come from the Xerox Alto on which
311 Smalltalk was first implemented.) Squeak normally maps X but‐
312 tons 1, 2 and 3 to the red, yellow and blue buttons, in that
313 order. With this option, it maps X buttons 1, 2 and 3 to the
314 red, blue and yellow buttons.)
315 -xasync
317 causes Squeak to use asynchronous display updates. The virtual
318 machine normally flushes and synchronises the display connection
319 at regular intervals. Using this option disables synchronisa‐
320 tion, which will be performed only when the image explicitly
321 requests it.
322 -xshm enables the use of the X Shared Memory extension on servers that
324 support it. This can dramatically improve display performance,
325 but works only when Squeak is running on the server.
326 Options specific to the FBDev display driver are as follows:
328 -fbdev device
330 Use the given framebuffer device instead of the default
331 '/dev/fb0'.
332 -kbmap mapfile
334 Load the keyboard map from the given mapfile instead of reading
335 it from the running kernel. Note that squeak cannot (currently)
336 read compressed or 'shorthand' map files (as found in
337 /usr/share/keymaps or /lib/kbd/keymaps). To generate a keymap
338 file usable by squeak, execute the following program from the
339 console:
340 dumpkeys -f -n --keys-only > key.map
342 If squeak encounters a problem while trying to load mapfile, it
344 will print an error message and exit. See keymaps(5) for more
345 information about the keymap file format. The programs dump‐
346 keys(1), loadkeys(1), and showkey(1) can be used to modify the
347 keyboard map before creating a keymap file for squeak.
348 -msdev device
350 Use the given mouse device instead of the default. The default
351 is to try '/dev/psaux', '/dev/input/mice' and '/dev/adbmouse',
352 in that order, and to use the first one that has a physical
353 device attached.
354 -msproto protocol
356 Use the given mouse protocol instead of the default. The sup‐
357 ported protocols are 'ps2' and 'adb'. The default is 'ps2' for
358 mice attached to '/dev/psaux' or '/dev/input/mice', and 'adb'
359 for mice attached to '/dev/adbmouse'.
360 -vtlock
362 Disallows VT switching, regardless of whether the request comes
363 from the keyboard or from another program such as chvt(1).
364 -vtswitch
366 Enables keyboard VT switching. Note that this option is effec‐
367 tively disabled if the '-vtlock' option is also enabled.
368 Options specific to the OSS and MacOSX sound drivers are as follows:
370 -nomixer
372 disables the primitives that change mixer (sound) settings. If
373 you prefer that Squeak leave these alone (they are, after all,
374 really the reponsibility of whichever mixer program or sound
375 control panel you use) then this option is for you.
376 Options specific to the ALSA sound driver are as follows:
378 -capture device
380 Uses the named input device for sound capture.
381 -playback device
383 Uses the named output device for sound playback.
384 Several common options are deprecated and are provided only for back‐
386 ward compatibility. These options should not be used and will be
387 removed in a future release:
388 -display dpy
390 is equivalent to '-vm display=X11 -display dpy'.
391 -headless
393 is equivalent to '-vm display=X11 -headless'.
394 -nodisplay
396 is equivalent to '-vm display=none'.
397 -nosound
399 is equivalent to '-vm sound=none'.
400 -quartz
402 is equivalent to '-vm display=Quartz'.
403
405 Many of the options that can be set on the command line can also be set
406 from environment variables.
407 SQUEAK_ASYNC
409 if set in the environment then equivalent to the '-xasync' flag.
410 (The value is ignored.)
411 SQUEAK_CAPTURE
413 see '-capture'.
414 SQUEAK_COMPOSITIONINPUT
416 if set in the environment then equivalent to the '-composition‐
417 input' flag. (The value is ignored.)
418 SQUEAK_ENCODING
420 the name of the internal character encoding used by Squeak.
421 Equivalent to giving the '-encoding' command-line option if set.
422 SQUEAK_FBDEV
424 the name of the framebuffer device to use when running on the
425 console. See the '-fbdev' option.
426 SQUEAK_FULLSCREEN
428 equivalent to '-fullscreen' if set.
429 SQUEAK_ICONIC
431 equivalent to the '-iconic' flag.
432 SQUEAK_IMAGE
434 the name of the image file to execute if no image argument is
435 given on the command line.
436 SQUEAK_KBMAP
438 the name of the keymap file to use when running on the console.
439 See the '-kbmap' option.
440 SQUEAK_LAZY
442 equivalent to the '-lazy' flag.
443 SQUEAK_MAPDELBS
445 equivalent to the '-mapdelbs' flag.
446 SQUEAK_MEMORY
448 the initial size of the heap, with optional 'k' or 'm' suffix.
449 Equivalent to the '-memory size[km]' flag.
450 SQUEAK_MSDEV
452 the name of the mouse device to use when running on the console.
453 See the '-msdev' option.
454 SQUEAK_MSPROTO
456 the name of the mouse protocl to use when running on the con‐
457 sole. See the '-msproto' option.
458 SQUEAK_VTLOCK
460 if set then equivalent to specifying the '-vtlock' option on the
461 command line.
462 SQUEAK_VTSWITCH
464 if set then equivalent to specifying the '-vtswitch' option on
465 the command line.
466 SQUEAK_NOEVENTS
468 if set, equivalent to '-noevents'.
469 SQUEAK_NOINTL
471 equivalent to '-nointl' if set.
472 SQUEAK_NOMIXER
474 equivalent to '-nomixer' if set.
475 SQUEAK_NOTIMER
477 equivalent to '-notimer' if set.
478 SQUEAK_NOTITLE
480 if set, equivalent to '-notitle'.
481 SQUEAK_PATHENC
483 the name of the character encoding used to construct file and
484 directory names. Equivalent to giving the '-pathenc' command-
485 line option if set.
486 SQUEAK_PLAYBACK
488 see '-playback'.
489 SQUEAK_PLUGINS
491 see '-plugins'.
492 SQUEAK_SWAPBTN
494 equivalent to '-swapbtn' if set.
495 SQUEAK_TEXTENC
497 the name of the character encoding used to copy/paste text
498 from/to external applications. Equivalent to giving the '-tex‐
499 tenc' command-line option if set.
500 SQUEAK_VM
502 contains the names of one or more drivers to be loaded during
503 initialisation. See the '-vm' option for details.
504 SQUEAK_XICFONT
506 if set in the environment then it provides a default name for
507 the composition overlay font; see the '-xicfont' flag.
508 SQUEAK_XSHM
510 equivalent to '-xshm'.
511 If an environment variable and a command-line option conflict over a
513 particular value then normally the value in the command line takes
514 precedence. The exception to this rule is the '-vm' option. Environ‐
515 ment variables are processed before command-line arguments and '-vm'
516 cannnot be used to unload a driver that was loaded while processing the
517 contents of 'SQUEAK_VM'.
518 squeak also checks the environment for LC_ALL and LC_CTYPE. If either
520 of these variables is set then support for international keyboards
521 (including dead keys for diacritical marks) is enabled. To prevent
522 this support being enabled even when one or both of these variables is
523 set, use the '-nointl' option (or set SQUEAK_NOINTL in the environ‐
524 ment). For example, to start squeak with support for dead keys on
525 Spanish keyboards, with Latin-1 encoding of external characters and the
526 default MacRoman internal font encoding, run squeak like this:
527 export LC_CTYPE=es_ES
529 export SQUEAK_TEXTENC=latin1
530 squeak
531
533 Squeak can load and execute a 'script' file containing Smalltalk code
534 at startup. The name of the file should be given as the script argu‐
535 ment to squeak. For example, assuming that the image 'foo.image' con‐
536 tains an open Transcript window, then the following represents the
537 'hello world' program for Squeak:
538 Transcript cr; show: 'Hello, world'.
540 If this script is in a file called 'hello.sq', then it could be run
542 like this:
543 squeak foo.image hello.sq
545 It is also possible to make 'self interpreting' scripts by adding an
547 'interpreter line' to the start of the script. The 'hello.sq' file
548 could be changed to
549 #!/usr/bin/squeak --
551 Transcript cr; show: 'Hello, world'.
552 and then made executable with
554 chmod +x hello.sq
556 and then invoked by running the script file directly:
558 SQUEAK_IMAGE="foo.image"
560 export SQUEAK_IMAGE
561 ./hello.sq
562 If any arguments are present after the script name then they can be
564 retrieved from within the script using the method
565 Smalltalk getSystemAttribute: n
567 where n is the index of the argument, starting at 3 for the first argu‐
569 ment. (See the method comment for
570 SystemDictionary>>getSystemAttribute:
572 in the image for an explanation of the meanings of the indices.)
574 As an example of this, here is the 'echo' program written as a Squeak
576 script:
577 #!/usr/bin/squeak --
579 "Echo arguments to the Transcript."
580 | i a |
581 i := 2.
582 [(a := Smalltalk getSystemAttribute: (i := i + 1))
583 notNil]
584 whileTrue: [Transcript space; show: a].
585 When run as
587 ./echo.sq one two three
589 this would print 'one two three' in the Transcript window.
591
593 inisqueak
594 prints several informational messages while doing its stuff. If
595 it encounters a problem it prints an appropriate message before
596 bailing out. The messages should be self-explanatory.
597 squeak normally does not print anything at all. If it prints something
599 then there is a problem. The messages should be self-explana‐
600 tory.
601
603 /usr/share/squeak/SqueakV3.sources
604 Shared system sources file for the Squeak image. There must be
605 a copy of (or link to) this file in the working directory when
606 running squeak.
607 /usr/share/squeak/Squeak*.image /usr/share/squeak/Squeak*.changes
609 Distributed image and changes files holding a `shapshot' of a
610 live Squeak session. (The contents of these files change during
611 a session, and so private copies should always be made before
612 running squeak for the first time. See inisqueak(1)).
613 ./SqueakV3.sources
615 A link to the system sources file.
616 ./name.image
618 ./name.changes
619 Private copies of image and changes files.
620 /usr/lib64/squeak/3.10-5/*.so
622 /usr/lib64/squeak/3.10-5/*.la
623 Virtual machine 'plugins' (containing primitives that are loaded
624 on demand) and drivers (for different types of display and sound
625 hardware).
626 /usr/bin/squeak
628 /usr/bin/inisqueak
629 The Squeak virtual machine and personal image installer script.
630 /usr/share/man/squeak.1
632 This manual page.
633 /usr/doc/squeak/*
635 Miscellaneous documentation.
636
638 This manual page documents version 3.10-5 of Unix Squeak. It may not
639 be appropriate for any other version.
640 The image and changes files containing a saved Squeak session are inti‐
642 mately related. They should always be used together, never be sepa‐
643 rated, and under no circumstances should an image be run with a changes
644 file that has been used with a different image. Failure to adhere to
645 the above could cause the source code for the methods in the image to
646 become garbled and impossible to retrieve.
647 The Unix Squeak virtual machine fully supports OpenGL in both the X11
649 and Quartz display drivers. Open Croquet will run just fine with
650 either of these drivers (and many Mac OS X users will even have the
651 choice of which driver to use :).
652
654 If a 'binary' option is enabled by an environment variable, there is no
655 way to disable it on the command line.
656 Similarly, drivers specified in the SQUEAK_VM environment variable can‐
658 not be overridden by passing options on the command line.
659 squeak should never crash. In the unlikely event that it does crash,
661 or prints any kind of message that does not appear to be caused by
662 incorrect arguments or illegal operations from within a Squeak program,
663 please send a bug report to: <ian.piumarta@squeakland.org>. (Do not
664 send bug reports to the general-purpose 'squeak-dev' mailing list.
665 They will not be read. If you feel you must post a bug report to a
666 mailing list, send it to the Squeak 'vm-dev' mailing list in addition
667 to the above email address.)
668
670 This manual page was written by Ian Piumarta.
671
673 Dan Ingalls, Ted Kaehler, John Maloney, Scott Wallace and Alan Kay,
674 Back to the Future: The Story of Squeak, A Practical Smalltalk Written
675 in Itself. Proc. OOPSLA'97.
676 The official Squeak home page:
678 http://squeak.org
679 The general-purpose 'squeak-dev' mailing list (not for VM-related bug
681 reports):
682 http://lists.squeakfoundation.org/listinfo/squeak-dev
683 The Squeak 'vm-dev' mailing list (amongst others):
685 http://discuss.squeakfoundation.org/
686 The latest source and binary distributions of Unix Squeak:
688 http://squeak.hpl.hp.com/~piumarta/squeak
689Squeak Smalltalk System SQUEAK(1)