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.