SQUEAK(1)

💖 NAME 💖

squeak, inisqueak — Unix Squeak virtual machine and installer

okay so welcome to the SQUEAK(1) page, bestie — this is the manual for the Squeak Smalltalk System virtual machine and its installer, and we are going to get you fully caught up. no cap.

---

✨ SYNOPSIS ✨

inisqueak
squeak [ option... ] [ image ] [ script [ argument... ] ]

---

🦋 DESCRIPTION 🦋

squeak is the virtual machine for the Squeak Smalltalk system. it needs three files to operate correctly, and yes, all three matter:

• an image file containing a snapshot of a live Squeak session
• a changes file containing the source code for modified methods in the image
• 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, and that state is persistent between consecutive sessions. so yeah, private copies of these files are normally required — that's just how it is.

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. iconic setup behavior, honestly.

---

🌸 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. that's the whole vibe.

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. slay, no need to type it yourself.

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. very handy, very main character.

---

💅 OPTIONS 💅

command line options fall into two categories:

• 'common' options that are recognised by the base VM
• '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 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 suffix 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:
  • 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;
  • the complete uname(1) information for the host on which the virtual machine was compiled;
  • 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.

Ok so quick heads-up, bestie: only the drivers that actually match your local platform will even be available 💡 Attempting to load an unsupported driver will make squeak exit with an error message. A list of available drivers is printed by the -help option. And if a particular driver cannot load the system libraries it depends on, then it will neither be listed nor be available to load at runtime. Not me being dramatic, that’s just the vibe check.

Also note: 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 embarrassment. We’ve all been there, but let’s not 💀

---

✨ Options specific to the X11 display driver ✨

• -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.
• -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 window is unmapped. This can be used if Squeak appears to be 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.
• -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 🌈

• -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 🔊

• -nomixer — disables the primitives that change mixer (sound) settings. If you prefer that Squeak leave these alone (they are, after all, really the responsibility of whichever mixer program or sound control panel you use) then this option is for you.

💀 Deprecated common options 💀

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. It’s giving “choose your own config adventure” ✨

• SQUEAK_ASYNC — if set in the environment then equivalent to the -xasync 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 protocol 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_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_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 cannot 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 ✨

okay so Squeak can load and execute a script file full of Smalltalk code at startup, and honestly that's kind of iconic 💅. You just give the file name as the script argument to squeak. For example, say your image foo.image has an open Transcript window — then this is the whole 'hello world' program for Squeak:

Transcript cr; show: 'Hello, world'.

If that script lives in a file called hello.sq, you can run it like this:

squeak foo.image hello.sq

You can also make 'self interpreting' scripts by adding an 'interpreter line' to the start of the script 🔥. The hello.sq file could become:

#!/nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/bin/squeak --
Transcript cr; show: 'Hello, world'.

then make it executable with:

chmod +x hello.sq

and then invoke it by running the script file directly — yes bestie, directly:

SQUEAK_IMAGE="foo.image"
export SQUEAK_IMAGE
./hello.sq

If any arguments are present after the script name, you can get them from inside the script with this 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's the 'echo' program written as a Squeak script:

#!/nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/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. slay 💖

---

🩺 DIAGNOSTICS 🩺

• inisqueak — prints several informational messages while doing its stuff. If it hits 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 📁

• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/lib/squeak/SqueakV5.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.
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/lib/squeak/Squeak*.image
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/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).)
• ./SqueakV5.sources — A link to the system sources file.
• ./name.image
• ./name.changes — Private copies of image and changes files.
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/lib/squeak/5.0-202003021730/*.so
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/lib/squeak/5.0-202003021730/*.la — Virtual machine 'plugins' (containing primitives that are loaded on demand) and drivers (for different types of display and sound hardware).
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/bin/squeak
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/bin/inisqueak — The Squeak virtual machine and personal image installer script.
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/share/man/squeak.1 — This manual page.
• /nix/store/fj5j1m54hlds2npla4as2pixry1r801l-squeak-5.3-19459/doc/squeak/* — Miscellaneous documentation.

---

📝 NOTES 📝

This manual page documents version 5.0 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 😭. Like, do not do it.

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://squeak.hpl.hp.com/~piumarta/squeak

---

xoxo, bestie 💋 this was the Squeak Smalltalk System — page SQUEAK(1), dated the date chillin' in the footer — you're so welcome 💖✨