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@squeakland.org (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.