1. Installation

1.  Verify System Requirements

Prior to installing, verify that your system meets the requirements for v8.1.

2.  Install GBS v8.1 distribution

GemBuilder for Smalltalk is provided in zipped form. You will need to unzip the distribution into a temporary location or into the installation directory you have selected.

The GemBuilder for Smalltalk distribution includes the following:

A directory named VW with the parcel files for VisualWorks:

CstMessengerSupport.pcl
CstMessengerSupport.pst
GbsRuntime.pcl
GbsRuntime.pst
GbsTools.pcl
GbsTools.pst

A directory named docs that contains PDF copies of the GemBuilder for Smalltalk documentation:

GBS-UsersGuide-VW-7.6.pdf (unchanged from previous release)
GBS-ReleaseNotes-8.1.pdf
GBS-InstallGuide-8.1.pdf

Determine the appropriate location for the GBS v8.1 parcels. This directory should already be on, or will need to be added to, the VisualWorks parcel path (this is described in the next section).

Copy the parcel files from the distribution directory named VW to this location.

3.  Load GBS Smalltalk code into your VisualWorks Image

1. Start VisualWorks, using a clean image without any previous versions of GemBuilder for Smalltalk.

2. Use the System > Settings tool to ensure that the directory to which you copied the parcels is included in System > Parcel Path. Add it, if necessary.

3. In a Parcel Manager, select the parcel GbsTools. Select Parcel > Load. This parcel in turn loads the other required parcels.

If you are building a deployment image and do not need the GBS development tools, install the GbsRuntime parcel instead of GbsTools.

4. Save your image. You may find it helpful to create an additional copy of this GBS image to use as a backup during application development.

4.  Install client shared libraries from GemStone/S Server

GBS requires a set of client-specific shared libraries (.dll or .so files) that are provided as part of the GemStone server product distribution. These libraries need to be loaded into the VisualWorks image in which GBS code is installed, in order for GBS to be able to login to the GemStone server.

The client shared libraries should be the same release version as the GemStone/S server, but since they are loaded into the VisualWorks client, they are specific to the OS platform and VisualWorks bit size (32-bit or 64-bit).

You may need or wish to install the entire GemStone/S server on the client node, or just copy the specific shared libraries that are required.

5.  Determine client shared library to load

Whether or not you have a full server installation on the client or have copied a few libraries, there is a specific library name you will specify to have GBS load using the libraryName: parameter.

The following table lists the possible library names for each supported GemStone server product and version. Library names that include ’lnk’ allow both linked and RPC logins; library names with ’rpc’ allow only RPC logins.

You will specify only one library name from the following table with libraryName:; other required library files can then be found automatically.

With GemStone/S 64 Bit v3.x, library names with ’64’ or ’32’ specify the compiled bit size of the library, and should match the client Smalltalk bit size.

Table 6 Library name arguments to libraryName:

Server Product and Version	Windows	Solaris and Linux
GemStone/S 64 Bit v3.3	libgcirpc-3.3.0-32.dll    or libgcirpc-3.3.0-64.dll	libgcirpc-3.3.0-32.so    or libgcirpc-3.3.0-64.so    or libgbslnk-3.3.0-64.so
GemStone/S 64 Bit v3.2.12	libgcirpc-3.2.12-32.dll    or libgcirpc-3.2.12-64.dll	libgcirpc-3.2.12-32.so    or libgcirpc-3.2.12-64.so
GemStone/S v6.7	gcirw67.dll    or gcilw67.dll	libgcirpc67.so    or libgcilnk67.so

6.  Configure GBS to load client shared library

GBS uses the configuration parameter libraryName to determine the name and location of the shared library to load. While only one specific library name is set by this parameter, any other shared library files that are listed in the preceding tables must be available, usually in the same location, in order for the library load to succeed and logins to work.

There are a number of options for specifying the library file that should be loaded:

• Execute code to set full path

Set libraryName to the full path and file name of the client library file. 32-bit VisualWorks clients on Windows, logging into GemStone/S 64 Bit v3.3:

GbsConfiguration current libraryName:

	'InstallDir\GemBuilderC3.3.0-x86.Windows_NT\bin32\libgcirpc-

	3.3.0-32.dll'

With this option, the shared libraries may be anywhere on the client; the libraries do not need to be on the %PATH% or $LD_LIBRARY_PATH.

• Execute code to set filename, allow system to determine path

Set libraryName to the file name of the client library file. For example, for 32-bit VisualWorks clients on Windows, logging into GemStone/S 64 Bit v3.3:

GbsConfiguration current libraryName: 

	'libgcirpc-3.3.0-32.dll'

This options requires that the library be in a directory on the %PATH% or $LD_LIBRARY_PATH; or on Linux, in the standard Linux library directories.

On Windows, it may also be in the current working directory, or in the VisualWorks executable directory.

If you are using 32-bit GemStone/S, the client library names are not unique between versions. Be sure to verify that no other versions of shared libraries are in directories on the path.

• Allow system to determine path and filename

Leave libraryName set to the empty string. This is the default, equivalent to:

GbsConfiguration current libraryName: '' 

This requires that the client libraries be in the current working directory, or in the bin directory or subdirectory of your VisualWorks image’s VISUALWORKS directory.

Be sure to verify that no other versions of the shared libraries are in these locations.

• Use file dialog to set path and filename

Use the file dialog to select the library name and path.

If the library name specified by libraryName in the previous options cannot be loaded, the resulting notification provides the option of selecting a file using a file dialog.

The load error may be due to an incorrect libraryName, copying the wrong library, or an additional required library failing to load.

Navigate to the location of the shared library and select the file. The dialog provides filename filtering, so only valid library names will appear.

Selecting a file using the file dialog will set libraryName to the full path selected.

7.  Verify installation by logging into the GemStone/S Server

To preserve your libraryName setting, save your image. You may wish to make a backup of this image.

The libraryName setting controls the shared library that is loaded the first time GemStone server code is accessed after image startup. If you have a client library already loaded in your image, changing the libraryName has no effect. To change the shared library that is loaded, update the libraryName, and save and restart the image.

Once the shared libraries are loaded, you should test your installation by logging into the GemStone/S server. You will need to ensure that the Stone repository monitor, and a NetLDI (if necessary), are accessible.