SQUEAK(1)

NAME
squeak, inisqueak - 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 argument s 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 behaves as if image was not specified. This is useful to specify a script without specifying an explicit image .

OPTIONS
The complete list of options is 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.

-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.

-help
    prints a short summary of the command-line syntax and available options, then exits.

-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 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.

-memory size[mk]
    requests that an initial heap of size bytes be allocated. 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. The default heap size is 20 megabytes.

-noevents
    disables the new (image 2.8 and later) event-driven input mechanism. This option is only intended for testing backwards compatibility in the VM and image.

-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 you use) then this option is for you.

-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.)

-notitle
    disables the title bar on the Squeak window (if the window manager supports it). This option is implied by `-fullscreen '.

-plugins path
    specifies an alternative location for external plugins (collections of named primitives). The path argument contains a pattern in which any occurrences of `%n ' will be replaced by the name of the plugin 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 cannot be found in the location specified by path then the search continues in the default locations.

-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.)

-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', `XShm' if shared memory support is enabled, 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 of loadable modules;

    •   a list of all modules that are compiled internally in the virtual machine.

    After printing the above, the virtual machine exits.

-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.

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_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_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_NOEVENTS
    if set, equivalent to `-noevents '.

SQUEAK_NOMIXER
    equivalent to `-nomixer ' if set.

SQUEAK_NOTIMER
    equivalent to `-notimer ' if set.

SQUEAK_NOTITLE
    if set, equivalent to `-notitle '.

SQUEAK_PLUGINS
    see `-plugins '.

SQUEAK_SWAPBTN
    equivalent to `-swapbtn ' if set.

SQUEAK_XSHM
    equivalent to `-xshm '.

If both an environment variable and a command-line flag give values for the same option, the value in the command line takes precedence.

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 argument s 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/share/squeak/SqueakV3.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/share/squeak/Squeak*.image /usr/local/share/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) ).

./SqueakV3.sources
    A link to the system sources file.

./name.image
./name.changes
    Private copies of image and changes files.

/usr/local/share/squeak/3.4-1/*.so
/usr/local/share/squeak/3.4-1/*.la
    Virtual machine `plugin modules', containing primitives that are loaded on demand.

/usr/local/bin/squeak
/usr/local/bin/inisqueak
    The Squeak virtual machine and personal image installer script.

/usr/local/man/squeak.1
    This manual page.

/usr/local/share/doc/squeak/*
    Miscellaneous documentation.

NOTES
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.

BUGS
If a `binary' option is enabled by an environment variable, there is no way to disable it on the command line.

squeak should never crash. In the unlikely event that it does crash (which is a remote possibility with the unstable development versions), 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@inria.fr>.

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 archives of the Squeak mailing list:
    http://squeak.cs.uiuc.edu/mail/squeak

The latest version of Unix Squeak:
    http://www-sor.inria.fr/~piumarta/squeak