Welcome to Unix Squeak!
(Mac OS X edition)

# Preface

The help viewer is buggy (at least mine is). This document is more than a page long, but there's no scroll bar. To get a scroll bar, resize the window slightly.

# Introduction

This software is still very much in alpha test. This means that it will crash (frequently) at random times for no obvious reason. By continuing to use this software you agree implicitly to act as an alpha tester and hence to the following:

> Subsequent to any and all crashes you will send the contents of the file `Library/Logs/CrashReporter/squeak.crash.log` (relative to your home directory), along with a brief description of what you were doing at the time, by email to: `ian.piumarta@inria.fr` (If you can also concoct a recipe to reproduce the crash reliably then you'll [probably] win a faster resolution of the problem.)

# Installing Squeak

The '.app' bundle does not come with '.image/.changes' or '.sources' files. You will have to get these from elsewhere (at the Squeak Foundation ftp site, for example). If you keep the '.sources' file (or a link to it) in the same directory as your image(s) you'll be fine. Otherwise you can put it (or a link to it) in the 'Contents/MacOS' folder of the app bundle. You can also put the distributed '.image/.changes' files in the 'Contents/Resources' folder too, if you want a convenient place from which to begin working in a fresh image (see Providing a default image below).

# Starting Squeak

Squeak can be started either from the Finder (by double-clicking on the VM or an image file) or from the command line in a terminal window. If it is started from the command line then various features (that are not available when launching it from the Finder) become available through command line options, such as running without a window (useful if the application is a Swiki or some other kind of server, for example). (Some of these options will soon be available via a preferences panel in Quartz, when I get round to implementing it.) A list of the available options is available by running Squeak from the command line and giving it the option ``-help`'.

If X11 is installed then display can be via X11 or via Quartz. The default is X11 if the environment variable DISPLAY is set and Quartz if Squeak is launched from the Finder. To force one or the other, Squeak can be run from the command line with the option ``-quartz`' or ``-display <your-display>`' as desired.

Note that to run Squeak in a remote window the X11 libraries must be installed on the client machine, i.e., the one on which Squeak is running. (More accurately, Squeak requires at least `libX11` and `libXext` installed for it to be able to connect to a remote display server).

Note also that options relating to the display are only recognised after Squeak has been told which kind of display is to be used. This applies even to the ``-help`' option. For example, to see a list of options that includes those specific to Quartz, Squeak must be run with the options ``-quartz -help`', in that order.

# Providing a default image

When launched from the Finder, if Squeak cannot find a default image to run in the current directory then it looks for the files `squeak.image` and `squeak.changes` in the `Squeak.app/Contents/Resources` directory. If these files exist then Squeak will offer to copy them (with a dialogue to choose the destination) before launching. (If these files do not exist and there is no obvious default image to run in the current directory, then double-clicking the VM will enter an `open' dialogue to locate an existing image to use.)

# Known bugs, limitiations and quirks

- Croquet requires some new support code (containing GLX classes appropriate for Quartz and big-endian X11). If these haven't been filed-in then Croquet probably won't work. (Forgetfulness on my part not withstanding, a copy of the required changeset should be in the `Squeak.app/Contents/Resources` directory, for convenience.)
- The Squeak window will refuse to resize if there are any TeapotMorphs open. This is to avoid a very nasty bug (that freezes the entire machine) in Mac OS X, which cannot cope with the VM thread updating OpenGL content while the (separate) UI thread is trying to invalidate the corresponding graphics state during window resizing. (Switching to/from fullscreen mode with open TeapotMorphs does work properly.)
- Croquet might run slower than normal since there is no MatrixPlugin included with Unix Squeak. The plugin is not included since I do not have (nor can I find anywhere) the sources for it.
- In order to support Croquet under Mac OS X (which has no way to associate a default memory size with an application) Squeak will determine how much virtual memory is available (up to a maximum of 1 gigabyte) and reserve that amount for dynamically growing the object memory. (This memory will only be physically allocated if/when the image tries to grow disproportionately, so this behaviour shouldn't rattle the disk under normal circumstances.)
- To display Croquet in an X11 window it is currently necessary to set the environment variable `LD_LIBRARY_PATH=/usr/X11R6/lib:/usr/lib:/lib` before starting the VM. (This is necessary because of a bug in the Mac OS X dynamic linker, although a subsequent version of Unix Squeak might elect to cure this problem by brute force inside the VM.)
- There must be a SqueakV3.sources file (or a link/alias to one) in the same directory as the image. There is currently no start-up dialogue to locate a sources file in an alternate location. (This is fairly high on the to-do list. If it becomes a nuisance then placing a copy/link/alias of/to the sources file in the `Squeak.app/Contents/MacOS` directory will probably do the trick.)
- Command-tab (fullscreen switch) does not work. There appears to be no way in Mac OS X to intercept the corresponding key event before it's snarfed by the dock (to cycle the key window between the currently active applications).
- When starting sound recording, input will revert to the default device. This is almost certainly not the device from which you wanted to record. (The input can be pointed back to a more suitable source using the sound pane in the system preferences, after the sound recorder has been started in Squeak.)
- There is currently no support for MIDI, tablets or joysticks.
- Printing from the File menu is not yet implemented (although the menu items are already there as placeholders).
- Printing a Form from within Squeak is only partially implemented. (The output is monochrome and scaling/orientation options are ignored.)
- The Squeak window does not accept `first click'. (In other words, clicking in the window while it's inactive will activate Squeak but the click will otherwise be ignored.) If this bothers you, then it shouldn't.
- There is (currently) no way to open multiple images at the same time from the Finder. (Squeak can be run multiple times from the command line if working with more than one image at the same time is required.)
- If the VM locks up for any reason while in fullscreen mode there is a chance that Option-Command-Escape will not work. (The `Force Quit' dialog is actually there, it's just completely obscured by the Squeak window which is at a higher level [in fact, the highest] in the display order.) If this occurs then the first thing to try is pressing RETURN twice (after pressing Option-Command-Escape). If that doesn't kill Squeak then the only other escape route is to log in to the machine remotely and kill the Squeak process by hand. (An `emergency exit' key combination will soon be implemented by the VM itself to cater for this situation. This is right at the top of the to-do list.)
- There is a small danger of the Window Server becoming catatonic while running Croquet (since there may be outstanding issues with multithreaded OpenGL that I've not yet caught and eliminated). The symptoms are a spinning `coloured carousel' cursor and absolutely no response whatsoever from any window on the screen. If this happens, the only way out is logging in to the machine remotely (as root) and then typing: `sync; reboot` (There could well be a several-minute delay while the kernel tries to kill an already undead Window Server before the reboot actually happens.)
- Enabling (or disabling) the command keys via the Window menu causes the Squeak menu title to lose boldface. This is a bit of a mystery...
- Help is only available when Squeak is launched from the Finder. (I haven't figured out why it behaves that way, but it's on the list.)
- The Squeak Help Book (this document) has not yet been written.
- As you've no doubt just discovered, the Help Viewer refuses to display a scroll bar when the content is too large until you try to resize the window. It's also incapable of scrolling in response to the arrow keys. Ho hum.

# Support

The Squeak home page contains useful information and links to various resources.

The Unix Squeak home page has further information, source code, and the latest downloads specific to Unix and MacOSX.

If you have problems, questions, bugs to report, or specific feature requests concerning the Unix Squeak VM, contact me directly.