DragonFly On-Line Manual Pages
SQUEAK(1) Squeak Smalltalk System SQUEAK(1)
NAME
squeak, inisqueak - Unix Squeak virtual machine and installer
SYNOPSIS
inisqueak
squeak [ option... ] [ image ] [ script [ argument... ] ]
DESCRIPTION
squeak is the virtual machine for the Squeak Smalltalk system. It
requires three files to operate correctly: an image file containing a
`snapshot' of a live Squeak session, a changes file containing the
source code for modified methods in the image, and a copy of (or a link
to) a shared system sources file containing the source code for methods
that have not been modified since the last major version increment.
The image and changes files contain the state of a user's Squeak
session, which is persistent between consecutive sessions. Private
copies of these files are therefore normally required. The inisqueak
script checks that the local Squeak installation appears sane, and then
copies the required files to the current working directory. If
inisqueak encounters no problems, it will finish by running squeak to
start a Squeak session using the newly copied image and changes files.
inisqueak should be run once, when using Squeak for the first time, to
create a new 'personal' Squeak session. Afterwards, squeak should be
run each time that session is to be resumed.
INVOCATION
inisqueak has no options or arguments. Simply 'cd' to the directory
that is to contain the working copies of the image and changes files,
then run it.
squeak accepts various options (described below), and then an optional
image name (which must not begin with a minus sign '-'). If an image
name is given on the command line then squeak tries to run that image.
Otherwise squeak checks the environment variable SQUEAK_IMAGE and, if
it is set, uses its value as the name of the image to run. Otherwise
squeak looks for an image called 'squeak.image' in the current
directory. If the image file does not exist then squeak prints a
message indicating which image file it failed to find and then exits.
If the extension '.image' is missing in the image argument or in the
value of the SQUEAK_IMAGE variable, it will be appended automatically.
The image argument can be followed by a script name. This is the name
of a 'document' that should contain Smalltalk code to be executed on
startup. The document can be either the name of a file or a URL
starting with 'http:'. Any arguments that appear after the script name
are ignored, but are made available to the script from within Squeak
via the method getSystemAttribute:. (See the section SCRIPTS below.)
If image is given as '--' then squeak immediately stops argument
processing (and behaves as if image was not specified). This is useful
to specify a script (possibly with script arguments) without specifying
an explicit image.
OPTIONS
Command line options fall into two categories: 'common' options that
are recognised by the base VM and 'specific' options that are tied to a
particular display or sound driver. Common options will always be
recognised by squeak, whereas a given specific option will be
recognised only after squeak has loaded the driver to which it relates.
Refer to the '-vm' option below for more details.
The common options recognised by squeak are as follows:
-encoding enc
specifies the internal character encoding to be used by Squeak.
This affects the translation that the VM performs when importing
text (from the keyboard or via 'paste' from an external
selection) or exporting text (pasting text from Squeak to
another application, or when generating filenames containing
special characters). In other words, it affects the
correspondence between what Squeak displays on the screen and
what it sends to (or receives from) external applications. The
correct value depends on the way Squeak's internal fonts are
encoded. Current images are delivered with traditional
Macintosh 'New York' fonts that use Mac Roman encoding, and so
this is the default internal encoding. If other fonts (from X11
or elsewhere) are imported into the image and used as system
fonts then the this default translation will give incorrect
results for diacritical marks and special characters. In such
cases the -encoding option can be used to change the internal
encoding, for example
-encoding ISO-8859-15
(aka Latin9) which would be appropriate for many of the fonts
designed for European languages.
-help prints a short summary of the command-line syntax, options and
available drivers, then exits.
-memory size[mk]
requests that a fixed heap of size bytes be allocated for the
Squeak image. If the suffix `k' is given then the argument is
expressed in kilobytes. If the suffux `m' is given then the
argument is expressed in megabytes. This option SHOULD NOT be
used, unless there is a good reason to do so, since it places an
arbitrary limit on Squeak's object memory size.
-mmap size[mk]
requests that a variable heap of at most size bytes be
allocated. (The suffixes are as described for the '-memory'
option.) squeak will initially allocate a heap that is large
enough to hold the image, with a small amount of headroom. If
at any time Squeak requires more memory for its image then
additional space will be allocated dynamically. Likewise, when
memory is no longer needed it will deallocated and returned to
the system. The size argument places an upper limit on how big
the heap can grow in this fashion. squeak uses a dynamic heap
by default with the maximum size set to 75% of the available
virtual memory or 1 gigabyte, whichever is smaller.
-noevents
disables the new (image 2.8 and later) event-driven input
mechanism. This option is only useful for testing backwards
compatibility with older images and should not be used.
-notimer
disables the use of the interval timer for keeping track of low-
resolution time. (If you are having problems with file, sound
or socket i/o reporting `interrupted system call' then setting
this flag might help.)
-pathenc enc
specifies the external character encoding to be used by Squeak
when accessing the filesystem (file and directory pathnames).
The correct value depends on the local platform's
characteristics. If no encoding conversion should be performed
then this should be set to the same encoding as Squeak uses
internally (see the -encoding option). Otherwise ISO-8859-15
(aka Latin9) might make sense on a filesystem supporting 8-bit
characters, and UTF-8 for filesystems that use Unicode-based
pathnames. The default is UTF-8 which is correct for Mac OS X
and very recent GNU/Linux distributions, and which (in an ideal
world) will eventually be adopted by all Unix variants.
-plugins path
specifies an alternative location for external plugins
(collections of named primitives) and drivers (for display and
sound). The path argument contains a pattern in which any
occurrences of `%n' will be replaced by the name of the plugin
or driver being loaded. The path can name either a directory or
the plugin itself and can be absolute or relative (to the
directory in which squeak was run). If a plugin or driver
cannot be found in the location specified by path then the
search continues in the default locations.
-textenc enc
specifies the external character encoding to be used by Squeak
when exchanging clipboard text with other applications. The
default is UTF-8 on Mac OS X and ISO-8859-15 (aka Latin9) on
other Unix systems. Note that X11 applications requesting the
selection converted to UTF8_STRING data will (correctly) receive
the clipboard text encoded as UTF-8, regardless of this setting.
Squeak recognises a subset of the encoding names defined by the
IANA. (If you prefer to use the international currency symbol
rather than the Euro symbol in external text then you might want
to set this to ISO-8859-1, aka Latin1.)
-version
prints three or more lines of version information, as follows:
o the architecture configured for the virtual machine at
compile time, the compilation `sequence number', the time
and date of compilation, and the name (and version, if
known) of the compiler that was used to compile squeak;
o the complete uname(1) information for the host on which
the virtual machine was compiled;
o the default installed location for plugins and drivers;
After printing the above, the virtual machine exits.
-vm driver
asks squeak to load a sound/display driver. For each supported
device there is a corresponding driver that squeak loads during
initialisation. Unless told otherwise, squeak will figure out
sensible default drivers to load. This choice can be overridden
using this option. The driver argument is a list of one or more
'assignments' of the form
class=device
separated by spaces or commas. The supported combinations are
currently:
display=X11
to display the Squeak window on a local or remote X
Window System server.
display=Quartz
to display on the local Mac OS X desktop.
display=none
to disable the display (and keyboard/mouse) entirely.
(This driver is useful primarily for running 'server'
applications in Squeak.)
sound=OSS
provides sound input and output via the Open Sound
System. (If you have a device called '/dev/dsp' then
this is likely the one you want.)
sound=MacOSX
provides sound input/output via Core Audio on Mac OS X.
sound=NAS
provides sound i/o via the Network Audio System.
sound=Sun
provides sound on Sun Microsystems hardware.
sound=none
disables sound entirely. squeak will not attempt to play
or record sounds when this driver is loaded.
Note that only those drivers relevant to the local platform will
be available. Attempting to load an unsupported driver will
cause squeak to exit with an error message. A list of available
drivers is printed by the '-help' option. If a particular
driver cannot load system libraries on which it depends then it
will neither be listed nor be available to load at runtime.
Note also that on Mac OS X both the X11 and Quartz display
drivers are supported, although the former will refuse to load
if the X11 client libraries are not installed on the local
machine. The Quartz driver will happily load (and Squeak will
run as a fully-fledged application) even when squeak is invoked
from the command line. Exercise caution when logged into Mac OS
X from another machine: forgetting to set DISPLAY before trying
to run squeak on the remote display could cause embarrassement.
Options specific to the X11 display driver are as follows:
-browserWindow id
specifies the id of the window that squeak should use for its
display. This option is intended for use when Squeak is running
as a web browser plugin.
-display server
specifies that Squeak should connect to the given display server
instead of looking in the environment variable DISPLAY (the
default behaviour) to find the name of the server to use.
-cmdmod N
tells the VM to map modifier key N on the keyboard to the
modifier code that the image expects for the Command key.
-optmod N
tells the VM to map modifier key N on the keyboard to the
modifier code that the image expects for the Option key.
-compositioninput
enables support for an overlay window in which individual
characters (e.g., Japanese hiragana) are composed before being
interpreted as a single character (e.g., Japanese kanji) by the
image.
-xicfont font
tells the VM to use the named font within the composition
overlay window.
-fullscreen
causes the Squeak window to occupy as much of the screen area as
possible. Implies '-notitle'.
-headless
disables the graphical display and mouse/keyboard input. This
mode of operation is useful primarily for servers.
-iconic
asks the window manager to iconify the Squeak window at startup.
-lazy causes Squeak to `snooze' whenever the main winodw is unmapped.
This can be used if Squeak appears to be using consuming CPU
time while idling (which should not normally be the case). Note
that if this option is in effect, when the Squeak window is
unmapped squeak will not respond to any external stimuli (other
than to provide the X selection to requestors, when Squeak is
the owner).
-mapdelbs
maps the Delete key onto Backspace. Backspace deletes the
character to the left of the cursor and Delete normally deletes
the character to the right of the cursor. With this option,
Deletes will behave like Backspace. The behaviour of Backspace
is not changed.
-noxdnd
disables support for the X drag-and-drop protocol.
-nointl
disables the handling of dead keys on international keyboards.
Without this option, dead key handling is enabled if either
LC_ALL or LC_CTYPE is set in the environment.
-notitle
disables the title bar on the Squeak window (if the window
manager supports it). This option is implied by '-fullscreen'.
-swapbtn
swaps the yellow and blue buttons. (Traditionally, the red
button is on the left, yellow in the middle and blue on the
right. The colourful names come from the Xerox Alto on which
Smalltalk was first implemented.) Squeak normally maps X
buttons 1, 2 and 3 to the red, yellow and blue buttons, in that
order. With this option, it maps X buttons 1, 2 and 3 to the
red, blue and yellow buttons.)
-xasync
causes Squeak to use asynchronous display updates. The virtual
machine normally flushes and synchronises the display connection
at regular intervals. Using this option disables
synchronisation, which will be performed only when the image
explicitly requests it.
-xshm enables the use of the X Shared Memory extension on servers that
support it. This can dramatically improve display performance,
but works only when Squeak is running on the server.
Options specific to the FBDev display driver are as follows:
-fbdev device
Use the given framebuffer device instead of the default
'/dev/fb0'.
-kbmap mapfile
Load the keyboard map from the given mapfile instead of reading
it from the running kernel. Note that squeak cannot (currently)
read compressed or 'shorthand' map files (as found in
/usr/share/keymaps or /lib/kbd/keymaps). To generate a keymap
file usable by squeak, execute the following program from the
console:
dumpkeys -f -n --keys-only > key.map
If squeak encounters a problem while trying to load mapfile, it
will print an error message and exit. See keymaps(5) for more
information about the keymap file format. The programs
dumpkeys(1), loadkeys(1), and showkey(1) can be used to modify
the keyboard map before creating a keymap file for squeak.
-msdev device
Use the given mouse device instead of the default. The default
is to try '/dev/psaux', '/dev/input/mice' and '/dev/adbmouse',
in that order, and to use the first one that has a physical
device attached.
-msproto protocol
Use the given mouse protocol instead of the default. The
supported protocols are 'ps2' and 'adb'. The default is 'ps2'
for mice attached to '/dev/psaux' or '/dev/input/mice', and
'adb' for mice attached to '/dev/adbmouse'.
-vtlock
Disallows VT switching, regardless of whether the request comes
from the keyboard or from another program such as chvt(1).
-vtswitch
Enables keyboard VT switching. Note that this option is
effectively disabled if the '-vtlock' option is also enabled.
Options specific to the OSS and MacOSX sound drivers are as follows:
-nomixer
disables the primitives that change mixer (sound) settings. If
you prefer that Squeak leave these alone (they are, after all,
really the reponsibility of whichever mixer program or sound
control panel you use) then this option is for you.
Options specific to the ALSA sound driver are as follows:
-capture device
Uses the named input device for sound capture.
-playback device
Uses the named output device for sound playback.
Several common options are deprecated and are provided only for
backward compatibility. These options should not be used and will be
removed in a future release:
-display dpy
is equivalent to '-vm display=X11 -display dpy'.
-headless
is equivalent to '-vm display=X11 -headless'.
-nodisplay
is equivalent to '-vm display=none'.
-nosound
is equivalent to '-vm sound=none'.
-quartz
is equivalent to '-vm display=Quartz'.
ENVIRONMENT
Many of the options that can be set on the command line can also be set
from environment variables.
SQUEAK_ASYNC
if set in the environment then equivalent to the '-xasync' flag.
(The value is ignored.)
SQUEAK_CAPTURE
see '-capture'.
SQUEAK_COMPOSITIONINPUT
if set in the environment then equivalent to the
'-compositioninput' flag. (The value is ignored.)
SQUEAK_ENCODING
the name of the internal character encoding used by Squeak.
Equivalent to giving the '-encoding' command-line option if set.
SQUEAK_FBDEV
the name of the framebuffer device to use when running on the
console. See the '-fbdev' option.
SQUEAK_FULLSCREEN
equivalent to '-fullscreen' if set.
SQUEAK_ICONIC
equivalent to the '-iconic' flag.
SQUEAK_IMAGE
the name of the image file to execute if no image argument is
given on the command line.
SQUEAK_KBMAP
the name of the keymap file to use when running on the console.
See the '-kbmap' option.
SQUEAK_LAZY
equivalent to the '-lazy' flag.
SQUEAK_MAPDELBS
equivalent to the '-mapdelbs' flag.
SQUEAK_MEMORY
the initial size of the heap, with optional 'k' or 'm' suffix.
Equivalent to the '-memory size[km]' flag.
SQUEAK_MSDEV
the name of the mouse device to use when running on the console.
See the '-msdev' option.
SQUEAK_MSPROTO
the name of the mouse protocl to use when running on the
console. See the '-msproto' option.
SQUEAK_VTLOCK
if set then equivalent to specifying the '-vtlock' option on the
command line.
SQUEAK_VTSWITCH
if set then equivalent to specifying the '-vtswitch' option on
the command line.
SQUEAK_NOEVENTS
if set, equivalent to '-noevents'.
SQUEAK_NOINTL
equivalent to '-nointl' if set.
SQUEAK_NOMIXER
equivalent to '-nomixer' if set.
SQUEAK_NOTIMER
equivalent to '-notimer' if set.
SQUEAK_NOTITLE
if set, equivalent to '-notitle'.
SQUEAK_PATHENC
the name of the character encoding used to construct file and
directory names. Equivalent to giving the '-pathenc' command-
line option if set.
SQUEAK_PLAYBACK
see '-playback'.
SQUEAK_PLUGINS
see '-plugins'.
SQUEAK_SWAPBTN
equivalent to '-swapbtn' if set.
SQUEAK_TEXTENC
the name of the character encoding used to copy/paste text
from/to external applications. Equivalent to giving the
'-textenc' command-line option if set.
SQUEAK_VM
contains the names of one or more drivers to be loaded during
initialisation. See the '-vm' option for details.
SQUEAK_XICFONT
if set in the environment then it provides a default name for
the composition overlay font; see the '-xicfont' flag.
SQUEAK_XSHM
equivalent to '-xshm'.
If an environment variable and a command-line option conflict over a
particular value then normally the value in the command line takes
precedence. The exception to this rule is the '-vm' option.
Environment variables are processed before command-line arguments and
'-vm' cannnot be used to unload a driver that was loaded while
processing the contents of 'SQUEAK_VM'.
squeak also checks the environment for LC_ALL and LC_CTYPE. If either
of these variables is set then support for international keyboards
(including dead keys for diacritical marks) is enabled. To prevent
this support being enabled even when one or both of these variables is
set, use the '-nointl' option (or set SQUEAK_NOINTL in the
environment). For example, to start squeak with support for dead keys
on Spanish keyboards, with Latin-1 encoding of external characters and
the default MacRoman internal font encoding, run squeak like this:
export LC_CTYPE=es_ES
export SQUEAK_TEXTENC=latin1
squeak
SCRIPTS
Squeak can load and execute a 'script' file containing Smalltalk code
at startup. The name of the file should be given as the script
argument to squeak. For example, assuming that the image 'foo.image'
contains an open Transcript window, then the following represents the
'hello world' program for Squeak:
Transcript cr; show: 'Hello, world'.
If this script is in a file called 'hello.sq', then it could be run
like this:
squeak foo.image hello.sq
It is also possible to make 'self interpreting' scripts by adding an
'interpreter line' to the start of the script. The 'hello.sq' file
could be changed to
#!/usr/local/bin/squeak --
Transcript cr; show: 'Hello, world'.
and then made executable with
chmod +x hello.sq
and then invoked by running the script file directly:
SQUEAK_IMAGE="foo.image"
export SQUEAK_IMAGE
./hello.sq
If any arguments are present after the script name then they can be
retrieved from within the script using the method
Smalltalk getSystemAttribute: n
where n is the index of the argument, starting at 3 for the first
argument. (See the method comment for
SystemDictionary>>getSystemAttribute:
in the image for an explanation of the meanings of the indices.)
As an example of this, here is the 'echo' program written as a Squeak
script:
#!/usr/local/bin/squeak --
"Echo arguments to the Transcript."
| i a |
i := 2.
[(a := Smalltalk getSystemAttribute: (i := i + 1))
notNil]
whileTrue: [Transcript space; show: a].
When run as
./echo.sq one two three
this would print 'one two three' in the Transcript window.
DIAGNOSTICS
inisqueak
prints several informational messages while doing its stuff. If
it encounters a problem it prints an appropriate message before
bailing out. The messages should be self-explanatory.
squeak normally does not print anything at all. If it prints something
then there is a problem. The messages should be self-
explanatory.
FILES
/usr/local/lib/squeak/SqueakV4.sources
Shared system sources file for the Squeak image. There must be
a copy of (or link to) this file in the working directory when
running squeak.
/usr/local/lib/squeak/Squeak*.image
/usr/local/lib/squeak/Squeak*.changes
Distributed image and changes files holding a `shapshot' of a
live Squeak session. (The contents of these files change during
a session, and so private copies should always be made before
running squeak for the first time. See inisqueak(1)).
./SqueakV4.sources
A link to the system sources file.
./name.image
./name.changes
Private copies of image and changes files.
/usr/local/lib/squeak/4.10.2-2614/*.so
/usr/local/lib/squeak/4.10.2-2614/*.la
Virtual machine 'plugins' (containing primitives that are loaded
on demand) and drivers (for different types of display and sound
hardware).
/usr/local/bin/squeak
/usr/local/bin/inisqueak
The Squeak virtual machine and personal image installer script.
/usr/local/man/man1/squeak.1
This manual page.
/usr/local/share/doc/squeak-4.10.2-2614/*
Miscellaneous documentation.
NOTES
This manual page documents version 4.10.2-2614 of Unix Squeak. It may
not be appropriate for any other version.
The image and changes files containing a saved Squeak session are
intimately related. They should always be used together, never be
separated, and under no circumstances should an image be run with a
changes file that has been used with a different image. Failure to
adhere to the above could cause the source code for the methods in the
image to become garbled and impossible to retrieve.
The Unix Squeak virtual machine fully supports OpenGL in both the X11
and Quartz display drivers. Open Croquet will run just fine with
either of these drivers (and many Mac OS X users will even have the
choice of which driver to use :).
BUGS
If a 'binary' option is enabled by an environment variable, there is no
way to disable it on the command line.
Similarly, drivers specified in the SQUEAK_VM environment variable
cannot be overridden by passing options on the command line.
squeak should never crash. In the unlikely event that it does crash,
or prints any kind of message that does not appear to be caused by
incorrect arguments or illegal operations from within a Squeak program,
please send a bug report to: <ian.piumarta@squeakland.org>. (Do not
send bug reports to the general-purpose 'squeak-dev' mailing list.
They will not be read. If you feel you must post a bug report to a
mailing list, send it to the Squeak 'vm-dev' mailing list in addition
to the above email address.)
AUTHOR
This manual page was written by Ian Piumarta.
SEE ALSO
Dan Ingalls, Ted Kaehler, John Maloney, Scott Wallace and Alan Kay,
Back to the Future: The Story of Squeak, A Practical Smalltalk Written
in Itself. Proc. OOPSLA'97.
The official Squeak home page:
http://squeak.org
The general-purpose 'squeak-dev' mailing list (not for VM-related bug
reports):
http://lists.squeakfoundation.org/listinfo/squeak-dev
The Squeak 'vm-dev' mailing list (amongst others):
http://discuss.squeakfoundation.org/
The latest source and binary distributions of Unix Squeak:
http://squeakvm.org/unix
Squeak Smalltalk System SQUEAK(1)