Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SQUEAK(1)		    Squeak Smalltalk System		     SQUEAK(1)

       squeak, inisqueak - Unix	Squeak virtual machine and installer

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

       squeak  is the virtual machine for the Squeak Smalltalk system.	It re-
       quires 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  ses-
       sion, 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  en-
       counters	 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.

       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	direc-
       tory.  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	start-
       ing 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  pro-
       cessing (and behaves as if image	was not	specified).  This is useful to
       specify a script	(possibly with script arguments) without specifying an
       explicit	image.

       Command	line  options  fall into two categories: 'common' options that
       are recognised by the base VM and '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	recog-
       nised only after	squeak has loaded the driver to	which it relates.  Re-
       fer 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	selec-
	      tion) or exporting text (pasting text from Squeak	to another ap-
	      plication, or when generating filenames containing special char-
	      acters).	 In other words, it affects the	correspondence between
	      what Squeak displays on the screen and what it sends to (or  re-
	      ceives  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  en-
	      coding.	If  other  fonts  (from	X11 or elsewhere) are imported
	      into the image and used as system	fonts then  the	 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 suffux `m' is given then the ar-
	      gument 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	 allo-
	      cated.   (The  suffixes  are  as described for the '-memory' op-
	      tion.)  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 addi-
	      tional space will	be allocated dynamically.  Likewise, when mem-
	      ory 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 vir-
	      tual memory or 1 gigabyte, whichever is smaller.

	      disables the new (image 2.8 and later) event-driven input	mecha-
	      nism.  This option is only useful	for testing backwards compati-
	      bility with older	images and should not be used.

	      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 characteris-
	      tics.  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 (collec-
	      tions 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 it-
	      self 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  de-
	      fault locations.

       -textenc	enc
	      specifies	 the  external character encoding to be	used by	Squeak
	      when exchanging clipboard	text with other	applications.  The de-
	      fault is UTF-8 on	Mac OS X and ISO-8859-15 (aka Latin9) on other
	      Unix systems.  Note that X11 applications	requesting the	selec-
	      tion  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.)

	      prints three or more lines of version information, as follows:

		 o   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;

		 o   the complete uname(1) information for the host  on	 which
		     the virtual machine was compiled;

		 o   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


	      separated	by spaces or commas.  The supported  combinations  are

		     to	 display the Squeak window on a	local or remote	X Win-
		     dow System	server.

		     to	display	on the local Mac OS X desktop.

		     to	disable	the  display  (and  keyboard/mouse)  entirely.
		     (This driver is useful primarily for running 'server' ap-
		     plications	in Squeak.)

		     provides sound input and output via the Open  Sound  Sys-
		     tem.   (If	 you have a device called '/dev/dsp' then this
		     is	likely the one you want.)

		     provides sound input/output via Core Audio	on Mac OS X.

		     provides sound i/o	via the	Network	Audio System.

		     provides sound on Sun Microsystems	hardware.

		     disables sound entirely.  squeak will not attempt to play
		     or	record sounds when this	driver is loaded.

	      Note that	only those drivers relevant to the local platform will
	      be available.  Attempting	to load	 an  unsupported  driver  will
	      cause squeak to exit with	an error message.  A list of available
	      drivers is printed by  the  '-help'  option.   If	 a  particular
	      driver  cannot load system libraries on which it depends then it
	      will neither be listed nor be available to load at runtime.

	      Note also	that on	Mac OS X both the X11 and Quartz display driv-
	      ers  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 embarrassement.

       Options specific	to the X11 display driver are 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  de-
	      fault behaviour) to find the name	of the server to use.

       -cmdmod N
	      tells  the VM to map modifier key	N on the keyboard to the modi-
	      fier code	that the image expects for the Command key.

       -optmod N
	      tells the	VM to map modifier key N on the	keyboard to the	 modi-
	      fier code	that the image expects for the Option key.

	      enables  support for an overlay window in	which individual char-
	      acters (e.g., Japanese hiragana) are composed before  being  in-
	      terpreted	 as  a	single character (e.g.,	Japanese kanji)	by the

       -xicfont	font
	      tells the	VM to use the named font within	the composition	 over-
	      lay window.

	      causes the Squeak	window to occupy as much of the	screen area as
	      possible.	 Implies '-notitle'.

	      disables the graphical display and mouse/keyboard	 input.	  This
	      mode of operation	is useful primarily for	servers.

	      asks the window manager to iconify the Squeak window at startup.

       -lazy  causes  Squeak to	`snooze' whenever the main winodw 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  un-
	      mapped  squeak  will  not	respond	to any external	stimuli	(other
	      than to provide the X selection to requestors,  when  Squeak  is
	      the owner).

	      maps the Delete key onto Backspace.  Backspace deletes the char-
	      acter 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

	      disables support for the X drag-and-drop protocol.

	      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.

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

	      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 but-
	      tons 1, 2	and 3 to the red, yellow and blue buttons, in that or-
	      der.  With this option, it maps X	buttons	1, 2 and 3 to the red,
	      blue and yellow buttons.)

	      causes Squeak to use asynchronous	display	updates.  The  virtual
	      machine normally flushes and synchronises	the display connection
	      at regular intervals.  Using this	option	disables  synchronisa-
	      tion, which will be performed only when the image	explicitly re-
	      quests 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 are	as follows:

       -fbdev device
	      Use  the	given  framebuffer  device  instead  of	 the   default

       -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

		  dumpkeys -f -n --keys-only >

	      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	 dump-
	      keys(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  de-
	      vice attached.

       -msproto	protocol
	      Use  the	given mouse protocol instead of	the default.  The sup-
	      ported 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'.

	      Disallows	VT switching, regardless of whether the	request	 comes
	      from the keyboard	or from	another	program	such as	chvt(1).

	      Enables  keyboard	VT switching.  Note that this option is	effec-
	      tively disabled if the '-vtlock' option is also enabled.

       Options specific	to the OSS and MacOSX sound drivers are	as follows:

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

       Options specific	to the ALSA sound driver are as	follows:

       -capture	device
	      Uses the named input device for sound capture.

       -playback device
	      Uses the named output device for sound playback.

       Several	common	options	are deprecated and are provided	only for back-
       ward compatibility.  These options should not be	used and will  be  re-
       moved in	a future release:

       -display	dpy
	      is equivalent to '-vm display=X11	-display dpy'.

	      is equivalent to '-vm display=X11	-headless'.

	      is equivalent to '-vm display=none'.

	      is equivalent to '-vm sound=none'.

	      is equivalent to '-vm display=Quartz'.

       Many of the options that	can be set on the command line can also	be set
       from environment	variables.

	      if set in	the environment	then equivalent	to the '-xasync' flag.
	      (The value is ignored.)

	      see '-capture'.

	      if  set in the environment then equivalent to the	'-composition-
	      input' flag.  (The value is ignored.)

	      the name of the internal	character  encoding  used  by  Squeak.
	      Equivalent to giving the '-encoding' command-line	option if set.

	      the  name	 of  the framebuffer device to use when	running	on the
	      console.	See the	'-fbdev' option.

	      equivalent to '-fullscreen' if set.

	      equivalent to the	'-iconic' flag.

	      the name of the image file to execute if no  image  argument  is
	      given on the command line.

	      the  name	of the keymap file to use when running on the console.
	      See the '-kbmap' option.

	      equivalent to the	'-lazy'	flag.

	      equivalent to the	'-mapdelbs' flag.

	      the initial size of the heap, with optional 'k' or  'm'  suffix.
	      Equivalent to the	'-memory size[km]' flag.

	      the name of the mouse device to use when running on the console.
	      See the '-msdev' option.

	      the name of the mouse protocl to use when	running	 on  the  con-
	      sole.  See the '-msproto'	option.

	      if set then equivalent to	specifying the '-vtlock' option	on the
	      command line.

	      if set then equivalent to	specifying the '-vtswitch'  option  on
	      the command line.

	      if set, equivalent to '-noevents'.

	      equivalent to '-nointl' if set.

	      equivalent to '-nomixer' if set.

	      equivalent to '-notimer' if set.

	      if set, equivalent to '-notitle'.

	      the  name	 of  the character encoding used to construct file and
	      directory	names.	Equivalent to giving the  '-pathenc'  command-
	      line option if set.

	      see '-playback'.

	      see '-plugins'.

	      equivalent to '-swapbtn' if set.

	      the  name	 of  the  character  encoding  used to copy/paste text
	      from/to external applications.  Equivalent to giving the	'-tex-
	      tenc' command-line option	if set.

	      contains	the  names  of one or more drivers to be loaded	during
	      initialisation.  See the '-vm' option for	details.

	      if set in	the environment	then it	provides a  default  name  for
	      the composition overlay font; see	the '-xicfont' flag.

	      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.  Environ-
       ment variables are processed before command-line	 arguments  and	 '-vm'
       cannnot 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 (in-
       cluding 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 key-
       boards, 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  can  load and execute a 'script'	file containing	Smalltalk code
       at startup.  The	name of	the file should	be given as the	 script	 argu-
       ment  to	squeak.	 For example, assuming that the	image 'foo.image' con-
       tains 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:

	      export SQUEAK_IMAGE

       If any arguments	are present after the script name then they can	be re-
       trieved from within the script using the	method

	      Smalltalk	getSystemAttribute: n

       where n is the index of the argument, starting at 3 for the first argu-
       ment.  (See the method comment for


       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

	      #!/usr/local/bin/squeak --
	      "Echo arguments to the Transcript."
	      |	i a |
	      i	:= 2.
	      [(a := Smalltalk getSystemAttribute: (i := i + 1))
		whileTrue: [Transcript space; show: a].

       When run	as

	      ./echo.sq	one two	three

       this would print	'one two three'	in the Transcript window.

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

	      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/lib/squeak/Squeak*.image			      /usr/lo-
	      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)).

	      A	link to	the system sources file.

	      Private copies of	image and changes files.

	      Virtual machine 'plugins'	(containing primitives that are	loaded
	      on demand) and drivers (for different types of display and sound

	      The Squeak virtual machine and personal image installer script.

	      This manual page.

	      Miscellaneous documentation.

       This  manual page documents version 4.10.2-2614 of Unix Squeak.	It may
       not be appropriate for any other	version.

       The image and changes files containing a	saved Squeak session are inti-
       mately  related.	  They	should always be used together,	never be sepa-
       rated, 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.

       The  Unix  Squeak virtual machine fully supports	OpenGL in both the X11
       and Quartz display drivers.  Open Croquet will run just fine  with  ei-
       ther  of	 these	drivers	 (and  many  Mac OS X users will even have the
       choice of which driver to use :).

       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 can-
       not 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 in-
       correct arguments or illegal operations from within a  Squeak  program,
       please  send  a	bug report to: <>.  (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.)

       This manual page	was written by Ian Piumarta.

       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:

       The  general-purpose  'squeak-dev' mailing list (not for	VM-related bug

       The Squeak 'vm-dev' mailing list	(amongst others):

       The latest source and binary distributions of Unix Squeak:

Squeak Smalltalk System						     SQUEAK(1)


Want to link to this manual page? Use this URL:

home | help