GemTools Launcher

[Update 6/5/2010] For the latest GemTools 1.0-beta.6 documentation see  the GemTools Guide on the glassdb wiki.

This post started out as a beta update post, but as I added more and more material I realized that it deserved to be a reincarnation of the Terse Guide to the GLASS Tools. It’s been a year since I wrote the original Terse Guide and there have been significant changes to the whole GLASS tool set, so a new version has been long overdue. However, I do have an announcement post to finish (and it depends upon the information in the Terse Guide), so rather than delay the announcement of the preview release, I decided to publish the Terse Guide before it was complete.

I have completed all of the sections that describe the new functionality of the GemTools Launcher, including a section on installing the GemTools Client in a fresh image. Over the next week, I plan to finish the Terse Guide.

Over time as new features are added I intend to revisit and revise this post. To that end, I’ve created a little update section, where I’ll record information about the updates I make over time:

  • current as of GemStone-dkh.441 and GLASS.230-dkh.209 (March 12, 2009)
  • one-click GemTools download available, based on Pharo0.1 update 10243 (March 22, 2009)
  • Process Browser section updated as of GemStone-dkh.465 and GLASS.230-dkh.228 – Philippe how do you like the fonts? (April 14, 2009)

All of the screen shots in this post were taken using a Pharo image. The GemTools Client runs in both Squeak and Pharo images (see Installation and Update Steps for instructions on setting up an image).

You can click on the screen shots in this post to see full size images.

Terse Guide to the (new) GLASS Tools

  1. GemTools Launcher
    1. Opening Launcher
    2. Annotation Pane
    3. Text Pane
    4. Launcher Menus
      1. Session Menu
      2. Update… Menu
      3. Admin… Menu
      4. Transaction Menu
      5. View… Menu
      6. Find… Menu
      7. Tools… Menu
      8. Debug… Menu
  2. Development Tools
    1. Workspaces
      1. Session Workspace
      2. Workspace
    2. Monticello Browser
    3. System Browser
    4. Method List Browsers
    5. Test Runner
    6. Debugger
      1. Breakpoints
      2. Remote Debugger
    7. Inspector
    8. Chasing Inspector
    9. File Browser
    10. Process Browser
    11. Transcript window
  3. Keyboard Shortcuts
  4. GemTools over WAN
  5. GemTools Client/Server Dependencies
  6. Installation and Update Steps
    1. Squeak client
    2. Pharo client
    3. GCI Library Install
    4. Gemtools Client Install
    5. Update GemTools Client and GLASS Server

GemTools Launcher


The GemTools Launcher is the main window for the new GemTools Client. From this window, you can manage multiple GemStone/S sessions against multiple stones. The Launcher gives you a view of all of your sessions. When a session is selected, the annotation pane provides an overview of important session information, the button bar provides easy access to commands and development tools, and the text pane provides access to session workspaces.

Opening the Launcher

To open the GemTools Launcher window, evaluate OGLauncher open. in a Smalltalk client workspace.


The default session (Glass) is an Appliance template, which is suitable for use on a GLASS appliance or any installation where the GemTools Client and stone are running on the same machine. Edit the template to reflect the name of your machine and the name of your stone:

OGApplianceSessionDescription new
	name: 'Glass';
	stoneHost: 'glass';
	stoneName: 'seaside';

See the Session Menu section for more details on working with sessions.

Press the Login button to connect a session to your server.

Launcher Annotation Pane


After login, the annotation pane shows selected information about the session:

  • Session name and session number. Use the Session menu to change the name of the session.
  • Version of the GLASS package currently installed.
  • Name of the session workspace visible in the text pane. Use the View… menu to manage session workspaces.
  • Name of the backup file, if you’ve restored your repository from a backup. Use the Admin… menu to backup and restore the repository.
  • Whether autoCommit and autoMigrate are enabled. Use the Transaction menu to control the autoCommit and autoMigrate settings.

Launcher Text Pane

The View… menu lets you select which session workspace is visible in the Launcher text pane.


By default a session workspace named GLASS is displayed (and created if necessary). There are menu items on both the View… menu and Tools… menu for opening a workspace window on the list of session workspaces. Session workspaces are persisted in your repository.

Launcher Menus

  1. Session Menu
  2. Update… Menu
  3. Admin… Menu
  4. Transaction Menu
  5. View… Menu
  6. Find… Menu
  7. Tools… Menu
  8. Debug… Menu

Session Menu

The Session Menu lets you create and manipulate sessions. Each session has a SessionDescription associated with it that keeps track of the information needed to log into a particular stone (stone name, netldi name or port, host name, etc.). When a session is logged in, a GCISession, representing the active GemStone session is associated with the session.

GemTools windows opened from the GemTools Launcher button bar are associated with the selected session. GemTools windows opened by executing commands within the context of another GemTools window are associated with the originating window’s session.

You may login to more than one session at any one time. The G/S[<session number>] in the title bar of a GemTools window indicates which session is associated with the window. The G/S[<session number>] is also tacked onto the end of the session’s name in the session list and annotation pane. Pressing the Logout button or selecting the Logout menu item terminates the selected session and closes all of the GemTools windows associated with the session.

When you close the GemTools Launcher window, the GemTools windows associated with all of the logged in sessions are automatically closed.

If you save your Smalltalk image, while sessions are logged in, none of the existing sessions nor their associated GemTools windows will be affected. However, when the image is restarted all session related GemTools windows will be closed and the sessions will be reset to a logged out state.


New Session

When you create a New session, you are given a choice of session templates: Appliance, Standard and Custom.

The Appliance template is suitable for logging into a GLASS appliance or an installation where your GemTools Client and the stone are running on the same machine:

OGApplianceSessionDescription new
	name: 'Glass';
	stoneHost: 'glass';
	stoneName: 'seaside';

If you are logging into a stone from a remote GemTools Client or have  started a non-standard netldi, or have change the password for the DataCurator user, then the Standard template is suitable:

OGStandardSessionDescription new
	name: 'Standard';
	stoneHost: 'glass';
	stoneName: 'seaside';
	gemHost: 'glass';
	netLDI: '50377';
	userId: 'DataCurator';
	password: 'swordfish';
	backupDirectory: '';

The Custom template provides access to some of the more esoteric login parameters:

OGCustomSessionDescription new
	name: 'Standard';
	stoneHost: 'glass';
	stoneName: 'seaside';
	gemHost: 'glass';
	netLDI: '50377';
	gemTask: 'gemnetobject';
	userId: 'DataCurator';
	password: 'swordfish';
	osUserId: '';
	osPassword: '';
	backupDirectory: '';
	dataDirectory: '';


Edit Session

The Edit session command gives you an opportunity to change the values of fields in the SessionDescription. You may also change the class of the SessionDescription (OGApplianceSessionDescription, OGStandardSessionDescription, or OGCustomSessionDescription) to expose more or fewer fields.

When you press Okay, the expression is evaluated and the resulting SessionDescription is associated with the selected session.

A logged in session may not be edited.sessionmenu1

Copy Session

The Copy session command copies the selected session and creates a new session whose name has ‘ copy’ appended.

If you copy a logged in session, only the session description information is copied (i.e., the new session is not in a logged in state).sessionmenu1

Delete Session

The Delete session command removes the selected session from the list.

The collection of sessions is stored in the Sessions class variable of the client class OGLauncherNode.

A logged in session may not be deleted.sessionmenu1


When the Login command is executed, a new gem is launched against the named stone using the netldi of the given name (or port number).

When the gem is started, it creates a log file in the home directory (typically) of the user that owns the gem process (in the appliance that would be /home/glass). If the gem process ever exits unexpectedly, you can check in the log file for error messages.



When you press the Logout button or execute the Logout command the selected session is terminated and all of the GemTools windows associated with the session are closed.

When a GemStone gem terminates, it’s log file is automatically deleted. The log file is not deleted if the gem terminates unexpectedly.


Update Client

See the Update Client Command.

GLASS Client recent Changes

See the Change Logs section.

Update… Menu

The commands on the Update… menu allow you to easily update the software on both the client (Squeak or Pharo) and the server. For a better understanding of the relationship between the client and server software see this section.

Continuing  the trend started with the previous preview release the update process just gets easier and easier. We’ve added commands that perform all of the necessary tasks for an update: from identifying which versions of the packages are update candidates, to performing the package load itself, to running the required preDoIt and postDoit scripts, to refreshing the session by automatically logging out and in again.

The GemTools Client has meta information about every GLASS package version. The meta information includes the status of the version (release, beta, or poison). Poison versions excluded from display. In addition to the version status, the meta information includes preDoIt and postDoIt expressions for each version (where needed). When the Update GLASS command is executed, all of the appropriate preDoIt and postDoIt expressions between your current GLASS package version and the target GLASS package version are evaluated in order.

When you are ready to update your GemTools Client and GLASS Server, you should always use the Update Client command first. The update for the GemTools Client may contain new meta information for the GLASS Server as well as bugfixes and new features. After running the Update Client command, you may run the Update GLASS command.


Update Client Command

The Update Client command queries the GLASS project for versions of the GemStone package that are later than the one currently installed. If later versions are found, the list is displayed from which you may choose a version to be loaded. If there are no more recent versions of the GemStone package in the GLASS project, you have the option to see All versions. The All versions list includes versions of the GemStone package from the GemTools project, which are likely to be under development. Unless you are specifically told to load a non-released version I don’t recommend doing so.

When the load is complete it is usually a good idea to save your client image.

If you want to go to a previous version of the GemTools Client, you must use the Monticello Browser (in the client Smalltalk).


Change Logs

GLASS Client recent changes & GLASS Server recent changes

These two commands open a workspace with the version comments associated with the most recent GemStone package versions in the GemTools project or GLASS package versions in the GLASS project.

GLASS Server change log & GLASS Client change log

These two commands prompt for a package version (either GemStone or GLASS) and a workspace is opened with the version comments from the selected version to the latest version in the GLASS project.


Update GLASS Command

After you have updated the GemTools Client, you may update the Glass Server with the Update GLASS command.

The Update GLASS command queries the GLASS project for versions of the GLASS package that are later than the one currently installed and marked as either a release or a beta. If later versions are found, the list is displayed from which you may choose a version to be loaded. If there are no more recent release or beta version, you have the option to see ALL versions. All versions will include alpha versions of the GLASS package, but I don’t recommend that you load alpha versions as they are typically under developement and may introduce problems.

Once you’ve selected a version to load, all of the GemTools windows associated with the session are automatically closed and the version is loaded. When the load is complete a commit is performed and the session is logged out and in again. Progress messages are printed to the client Transcript window while the load operation is performed.

It is a good idea to backup your repository right before you perform the Update GLASS command and again immediately after the load is complete. With backups you will always be able to return to a know point and restore from backup is much quicker than reloading a GLASS package.

If you want to go to a previous version of the GLASS Server, you must use the GemTools Monticello Browser (in the server).

Admin… Menu

The Admin… menu is primarily intended to provide commands for performing System Administration activities.


Backup/Restore Commands

I won’t go into much detail about GemStone/S backup and restore commands here, so I recommend that you read Chapter 9 of the System Administration Guide paying special attention to Sections 9.4 and 9.5.

Backup Repository

The Backup Repository command creates a backup file in the backup directory (by default $GEMSTONE/seaside/backups). You can change the location of the backup directory using the Edit Session command on the Session Menu.

It is perfectly okay to make a backup of a system that is currently running (i.e., multiple gems running).

Restore Backup

Before the stone starts a restore from backup, all non-essential gems are shut down, including the Seaside Gems and the Maintenance VM. When the restore from backup is complete the Seaside Gems and Maintenance VM need to be restarted manually (see the Restart Seaside Gems command).

The Restore Backup w/o tranlogs command restores the repository to exactly the state it was in when the backup was made. This command is intended to to be used to restore a checkpoint of the repository.

The Restore Backup w/tranlogs command restores the repository and replays all of the subsequent changes using the transaction logs. This command is intended to be used to recover from a system crash, where the extent file was somehow corrupted.

Ongoing progress for both commands is written to the client Transcript window.

You can try a little experiment to see the difference between the two commands:

  1. Make a backup.
  2. Add some text to a workspace and save the workspace (doing a commit).
  3. Run the Restore Backup w/tranlogs command and when the restore is complete note that the workspace includes your addition.
  4. Run the Restore Backup w/o tranlogs command and when the restore is complete note that the workspace does not include your addition.
  5. For extra credit run the Restore Backup w/tranlogs command and note that the restore from current logs failed. For an explanation of what’s going on read about the “Fork-in-Time” Scenario on page 9-31 in the System Administration Guide.

I find the Restore Backup w/o tranlogs command to be the most useful as it mimics the functionality one gets with a client Smalltalk when one restarts a saved image.

Before putting a system into production, I suggest that you read Chapter 9 of the SAG and experiment with the backup/restore commands using topaz. adminmenu

Start/Stop/Restart Seaside Gems Commands

The Start/Stop/Restart Seaside gems commands executes the $GEMSTONE/seaside/bin/runSeasideGems shell script on the server machine. By default this script starts the Maintenance VM and 3 FastCGI Seaside gems listening on ports 9001, 9002, and 9003. The script can be edited to change the number and types of gems that are started.

If you don’t start a Maintenance VM during development, then you should plan on running a SystemRepository markForCollection. periodically to make sure that the persistent objects are garbage collected. I’ll probably add a Repository Garbage Collect command to the Admin… menu in a future version of the tools.

Ongoing progress for these commands is written the client Transcript window. adminmenu

DoIt Commands

The DoIt commands includes a collection of scripts that Gerhard Obermann has found useful over the years working with GemStone.You can learn a fair amount about GemStone by taking a look at the information provided by these scripts.

The Change Packages And Methods command provides a quick overview of the unsaved changes that you have made to the code.

The Show Object Log command provides a workspace with the String version of the Object Log.

The Empty Object Log command empties the entire Object Log (also see the Remove Continuations from Object Log command in the Debug… menu). adminmenu

Bug Report Commands

When someone submits a bug report to the GLASS Beta Mailing List I invariably ask “What version of the GemTools package are you using?” and “What version of the GLASS package are you using?” Now that we are supporting both Pharo and Squeak as GemTools clients, I realized that I would need to start asking “Which Smalltalk client are you using?”

While these are the questions I typically ask, I actually care about more information like “What OS are you running?” and “What version of GemStone/S are you running?”

Bug Report Info

The Bug Report Info command collects the answers to the above questions and more, displaying the results in a client workspace. In the future, when you submit a bug report to the GLASS Beta Mailing List, please attach the contents of the workspace to your email.

Send Bug Report

Even better would be to use the Send Bug Report command. If you have access to an SMTP server, you should use this command as it brings up a Morphic window for mailing a bug report, just fill your information and press the Send button.

This command uses Gerhard Obermann’s SMTPMail package and you’ll need to configure SendMail:

    mailfrom: 'e-mail address used to subscribe to Beta mailing list';
    mailhost: 'SMTP mail host'.

Transaction Menu

The Transaction Menu provides commands for manually performing commits and aborts.transactionmenu


The Commit command performs a System commitTransaction. All changes made since the last transaction boundary (commit or abort) are saved to the repository.

When committing, be aware the the GemTools windows will not be updated to reflect any changes that may have been made in other sessions.

If the commit fails, then an Inspector is brought up on the result of System transactionConflict:

A SymbolDictionary that contains an Association whose key is #commitResult and whose value is one of the following Symbols: #success, #failure, #retryFailure, #commitDisallowed, or #rcFailure.

The remaining Associations in the dictionary are used to report the conflicts found.  Each Association’s key indicates the kind of conflict detected; its associated value is an Array of OOPs for the objects that are conflicting. If there are no conflicts for the transaction, the returned SymbolDictionary has no additional Associations.

The conflict sets are cleared at the beginning of a commit or abort and therefore may be examined until the next commit, continue or abort.

The keys for the conflicts are as follows:

Key                Conflicts
Read-Write          StrongReadSet and WriteSetUnion conflicts.
Write-Write         WriteSet and WriteSetUnion conflicts.
Write-Dependency    WriteSet and DependencyChangeSetUnion conflicts.
Write-WriteLock     WriteSet and WriteLockSet conflicts.
Write-ReadLock      WriteSet and ReadLockSet conflicts.
Rc-Write-Write      Logical write-write conflict on reduced conflict object.

The Read-Write conflict set has already had RcReadSet subtracted from it.

The Write-Write conflict set does not have RcReadSet subtracted .

Beginning with Gemstone64 v1.1 , the WriteSet no longer includes objects newly committed by this transaction.  Thus a conflict between a lock and a newly committed object in prior releases will no longer show up as a conflict.

The Write-Dependency conflict set contains objects modified (including DependencyMap operations) in the current transaction that were either added to, removed from, or changed in the DependencyMap by another transaction. Objects in the Write-Dependency conflict set may be in the Write-Write conflict set.



The Abort command performs a System abortTransaction. All changes that you have made since the last transaction boundary (commit or abort) are lost.

When aborting, be aware the the GemTools windows will not be updated to reflect any changes that may have been made in other sessions.transactionmenu

Auto Commit

By default Auto Commit is enabled. With Auto Commit enabled, the system performs a commit after every UI action that can change state. In the Browsers that means there are commits after virtually every menu operation. In a workspace or code definition pane, a commit is performed after  expression evaulation (doIt, printIt, inspectIt, etc.) and after an accept command.


Auto Migrate

By default Auto Migrate is enabled. With Auto Migrate enabled, whenever a class is modified all instances of the class and all instances of all of its subclasses will be automatically migrated to the new classes shape. This is normally done every time you change a class in a client Smalltalk, however, in GemStone, when there may be billions of instances in a repository, an allInstances call can be very expensive, so migration has been spilt out from class modification. Of course in a development environment, Auto Migrate is a very convenient/necessary feature.

For the Auto Migrate feature to operate Auto Commit must be enabled. Therefore if you disable Auto Commit, Auto Migrate will be disabled.

The status of Auto Migrate and Auto Commit are displayed in the  annotation pane.

View… Menu

viewmenuThe View… menu lets you select which Session Workspace is visible in the text pane. By default a workspace named GLASS is displayed. In the example menu on the right, there is a list of 5 session workspaces named: ‘GLASS’, ‘MC’ (the highlighting and x in from of the name indicates that the MC workspace is currently visible in the GemTools Launcher), ‘ToDo’, ‘history’, and ‘pier 1.1.1’. When you select a session workspace the saved contents of that workspace are displayed text pane.


The New command allows you to create a session workspace. The contents of a session workspace are persisted in the repository.


The Open command opens a GemTools Workspace window, a separate window giving you access to the session workspaces.


The Remove command deletes the selected session workspace.

Session Info

The Session Info command provides a little more detail about the logged in session:


Find… Menu

findmenuThe Find… menu is the entry point for editting/browsing code.

The Class…, Hierarchy…, and Class References… commands prompt for a Class name fragment, brings up a list of Classes whose name includes the fragment and then opens the an appropriate OBBrowser on the selected Class.

The Method… and Senders… commands do similar operations using method selectors instead of Class names.

The String… command prompts for a string and then opens a Method List Browser on all methods that contain the chosen string.

Tools… Menu

toolsmenuOpen Workspaces

The Open Workspaces command opens a GemTools Workspace window, a separate window giving you access to the session workspaces.

File Browser

The File Browser command opens a File Browser window.

Process Browser

The Process Browser command opens a Process Browser window.

Inspect Undefined Symbols

The Inspect Undefined Symbols command opens an Inspector on a Dictionary of Undefined Symbols:


The key is the UndefinedSymbol and the value is a collection of Associations whose key is a class and whose value is a selector for the method in the class that references the Undefined Symbol.

When you run the Inspect Undefined Symbols command, you get a filtered list of Undefined Symbols. If you look at the class UndefinedSymbolsTest, you’ll see that there the methods whose selectors start with ‘undefinedSymbols’ list Symbols that are filtered out of the original list. If you want to see the unfiltered list, inspect the global UndefinedSymbols directly.

The test UndefinedSymbolsTest is intended to run clean.

Inspect Sent but not Implemented

The Inspect Sent but not Implemented command opens an Inspector on an IdentitySet of selectors that are sent as messages in the repository, but for which there is no method implemented:


If you want to see which methods send a particular selector, select one of the selectors and use the CTL-n shortcut, to open a Senders Browser window.

When you run the Inspect Sent but not Implemented command you get a filtered list of selectors. See the class SentButNotImplementedTest and look at the methods whose selectors start with ‘nonImplementedSelectors’, to see which selectors are filtered out of the original list.

The test SentButNotImplementedTest is intended to run clean.

Test Runner

The Test Runner command opens a Test Runner window.


The Monticello command opens a Monticello Package Browser window.

Debug… Menu

debuggingmenuThe Debug… Menu allows you to select a continuation to debug. see Remote Seaside Debugging with Persistent Continuations for information on initiating a Remote Debugging sequence.

In addition to the two commands Remove Continuations… and Clear Object Log, The Debug… Menu lists the continuations that are present in the Object Log. When you select a particular continuation, a Remote Debugger is brought up on the continuation. For a continuation with a leading ‘^’ , you may use the proceed command to resume the HTTP request that initiated the continuation (you also have to press on the Proceed link on the original page). The newest continuations are listed last. Continuations stay in the Object Log until deleted via the web interface or via one of the following commands.

Remove Continuations from Object Log

This command removes all of the continuations from the Object Log, while leaving all of the other object log entries alone.

Clear Object Log

This command remove all of the log entries from the Object Log.

Development Tools


Session Workspace


CTL-s to save the contents of the workspace


Monticello Browser


System Browser


Method List Browsers


Test Runner





GemStone/S supports breakpoints, so it isn’t always necessary to edit a method to get the debugger to stop at an interesting point. The definition pane menu in browsers have a ’set breakpoint’ item that will set a breakpoint at the selected point in a method. For a method that has a breakpoint set, an additional menu item, ‘clear method breakpoints’, shows up and allows you to clear all of the breakpoints in the selected method. If a breakpoint is set on any method in the system, a ‘clear ALL breakpoints’ method shows up on all of the definition pane menus and will clear all the breakpoints in your session when selected.

A breakpoint browser is on the drawing board that will allow for the individual control of breakpoints, including disable/enable selected breakpoints.

Breakpoints are session-based and are associated with a particular instance of a method. If the method changes by either code changes on your part or the method is changed via an update via a commit or abort, then the previously set breakpoints aren’t active on the new instance of the method.

Remote Debugger

see Remote Seaside Debugging with Persistent Continuations



Chasing Inspector


File Browser


Process Browser


The Process Browser consists of three panes: process pane, context pane and code pane. When you select a process, the context pane displays the context stack for the selected process. When you select a context the code pane displays the code for the selected method and highlights the statement that is being executed by the context. You can edit and accept  the code in the code pane.

The Process Browser is still under development and I expect that over time the functionality will evolve.

Process Menu

The Process Menu is used to perform operations on the selected process in the process pane of the Process Browser.


Suspends the selected process.


Terminates the selected process.

yield 5


(Delay forSeconds: 5) wait.

which gives any blocked processes in the Gem a chance to run. Control returns to the client after 5 seconds.

If another process encounters an error or terminates normally before the 5 seconds has elapsed, control will be returned to the client. A debugger will be opened if there was an error, otherwise the result of the process will be returned. If you refresh the process list in the Process Browser, you should see the 5 second delay process in the list.

yield forever

Executes an infinite delay loop:

[ true ] whileTrue: [ (Delay forSeconds: 10) wait ]

This effectively gives control back to the Gem and allows all threads and services to run freely.

This command is useful if you’ve used Alt-. and closed a debugger, but want the Gem to continue servicing requests.

chase/chase references/explore/inspect

Performs the selected operation on the selected process.


Refreshes the list of processes displayed in the process pane of the Process Browser.

Context Menu

contextmenuThe Context Menu is used to perform operations on the selected context in the context pane of the Process Browser.

The standard menu items are available and the target of command is the selected context.

If you are interested in inspecting the receiver of the message, then you should use the chase menu item, then click on the 1 switch in the Chasing Inspector and then click on the receiver list item.

Transcript Window


Keyboard Shortcuts

The following keyboard shortcuts are supported in all of the GemStone text panes whether they show up in a menu or not:

  • CTL-b browse selected class
  • CTL-N references for selected class
  • CTL-n senders of selected selector
  • CTL-m implementors of selected selector
  • CTL-E methods containing selected string
  • CTL-i inspect it
  • CTL-I explore it (open a Chasing Inspector on the result of evaluating the selected expression)
  • CTL-p print it
  • CTL-d do it

In Session Workspaces, the evaluation context for CTL-i, CTL-i,CTL-I, and CTL-d, is not defined, which means that you can’t use ’self’ in workspace expressions. In code browsers the evaluation context is the selected class (’self’ is the class), in the Debugger the evaluation context is the message receiver, and in the inspector the evaluation context is the inspected object (you have to select a field in the inspector to set the inspected object).

GemTools over WAN

GemTools Client/Server Dependencies

The GemTools Client software executes in a client Smalltalk (Squeak or Pharo), however, it depends upon the GLASS Server software.

The first source of dependency between the client and server code is at the OmniBrowser level. When a session is logged in, a GCI connection is established to the gem (server) running under the control of a GemStone/S stoned process. When a GemTools window is opened there is OmniBrowser code that is executing on the server (GemStone vm) and Morphic code executing on the client (Smalltalk client) communicating via GCI. When you are editting code in a GemTools Browser, the classes, categories, and methods that you are manipulating exist on the server and not on the client. Only the names of categories, classes and methods are present in the client, along with object ids or OOPs of some of the necessary server-side objects.

The interaction across the wire is roughly at the level of the API between OmniBrowser and OB-Morphic, where the OmniBrowser code (like OB-Standard, i.e,, the development tools) executes on the server and the OB-Morphic code executes on the client. Morphic clicks and menu picks are transmitted across the wire from the client to the OmniBrowser objects on the server, the OmniBrowser code on the server generates changed: messages that are shipped across the wire from the server to the Morphic widgets on the client, and finally the Morphic widgets make content requests ( lists or text) across the wire to which the server replies.

For the most part, window specific code is not required on the client. The System Browser, Method Implementors and Monticello Package Browser windows have no special code running on the client. On the other hand, the OTDebugger and OTInspector windows do have special code running on the client. The special code is primarily related to the unique layout requirements of those windows. As a consequence, the new OTInspector code may not function correctly with an earlier version of the client software. Conversely, as new functionality is added or moved from the client to the server (like the recent move of the Test Runner) more code dependencies are introduced between the client and the server

Prior to the most recent Beta Preview release, there was a complicated and error prone process for updating the software on the client and server. Fortunately the changes that were made to OmniBrowser between OmniBrowser-dr.408 (corresponding to GLASS.230-dkh.164) and OmniBrowser-dr.432 (corresponding to GLASS.230-dkh.209) were small enough that I could make compatibility changes in the client code that would allow most of the UI for GLASS.230-dkh.164 to run in the current GemTools Client code.

Installation and Update Steps

[Updated: 3/22/09]When the rate of change for the GemTools Client slows down a bit we will release a new on-click version. Until then you’ll need to roll your own GemTools Client image.

[Update 11/04/2009] Please see the GemTools Client 1.0-beta.1 post for up-to-date instructions.

James Foster has made a one-click GemTools download available. The GemTools 2.3.1 (Preview) download is based upon Pharo0.1 update 10243. If you use the one-click image, be sure to Update the GemTools Client and GLASS Server.

If you prefer to use a Squeak-based client or want to use a later version of Pharo then follow the instructions below. on this page. [Updated 10/17/2009]


To use a Squeak image as your client, first download and install a Squeak 3.10 vm. Then download a stable Squeak3.10 basic image and changes file. I’ve been using with good results.

The Universe Browser is pre-installed in the basic Squeak image, so when you’ve got your image ready jump to the GemTools Client Install step.


To use a Pharo0.1 image as your client, download and install a recent Pharo release following these instructions. As of this writing I’ve been using pharo0.1-10243dev09.02.3 and GemStone.230-dkh.441 with good results.

Pharo is still in Alpha and there is always the possibility that a new drop of the Pharo image will break something in the GemTools Client. If that happens, use a version that works, until I get a chance to take care of the problem. Note:pharo0.1-10250dev09.03.2 has an installation issue. [Update 4/15/2009: For the time being, I’d stick with for the GemTools Client. Pharo has moved to genuine closures in later versions and the dev images are a little unstable while the closure modifications ripple through the system].

To install the GemTools Client in Pharo, you have to first install the Universe Browser following these instructions.

GCI Library Install

To install the GCI library, I recommend that you use the gci libraries from a download of the one-click Squeak image. Copy all three gci files (gciForWindows.dll,, and from the directory of into the directory where you’ve got your .image file.

GemTools Client Install


Now that you’ve got a Squeak/Pharo client with the Universe Browser installed and the GCI libraries in place. Fire up your image:

  1. Open the Universe Browser and install the package GemTools-Client version 0.441 or later (under the Network category). The Universe Browser will install the following pacakges along with their depdents: OmniBrowser, OmniBrowser-Morphic, ShoutOmniBrowser, OmniBrowser-SUnit-GUI (for OB multiple selection lists), and FFI.
  2. Save your client image.
  3. Evaluate OGLauncher open. in a workspace to open the GemTools Launcher window.
  4. Click on the New Session button and select a Standard session.
  5. Change the appropriate fields (see screen shot on right), typically you will want to fill in the name:, stoneHost:, stoneName: and gemHost: fields. See the New Session command for more information.
  6. Test the session description by logging in.
  7. Logout and save your client image.

Update GemTools Client and Update GLASS Server

Given that you’ve already installed a GemTools Client, take the following steps to update the client and server software:

  1. Log out of your GemStone session.
  2. click on the Update Client menu item under the Update… menu and select the most recent Released version (currently GemStone-dkh.441).
  3. When the software has finished loading, save your client image.
  4. Log into the stone.
  5. Click on the Backup Repository menu item under the Admin… menu and make a backup of your current repository, in case you discover problems during or after the update.
  6. Click on the Update GLASS menu item under the Update… menu and select the most recent Released or Beta version (currently GLASS.230-dkh.209).
  7. Click on the Backup Repository menu item under the Admin… menu and make a backup of your freshly updated repository.
  8. Your ready to go!