1. Installation

This document describes how to install GemBuilder for Smalltalk v8.2.

Please review the GemBuilder for Smalltalk Release Notes for v8.2 for details of the changes, before installing or upgrading to this version.

GBS v8.2 is supported with the VisualWorks Smalltalk environment, can cannot be used with VA Smalltalk. Support for VA Smalltalk is provided in a separate set of releases.

Installing GBS is a multi-step process:

1.   Verify System Requirements

2.   Install GBS v8.2 distribution

3.   Load GBS Smalltalk code into your VisualWorks Image

4.   Install client shared libraries from GemStone/S Server

5.   Determine client shared library to load

6.   Configure GBS to load client shared library

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

GBS does not support upgrade from an image in which an older version of GBS has been previously installed. To upgrade GBS, start with a VisualWorks image in which GBS is not installed. Follow the instructions in this Installation Guide, and then restore your application code.

1.  Verify System Requirements

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

Operating system

Supported operating systems are listed in Table 1 .

Client Smalltalk

This version of GBS is supported with the Cincom VisualWorks Smalltalk environment, both 32-bit and 64-bit, as listed in listed in Table 1 .

GemStone Server

Supported GemStone/S 64 Bit versions are listed in Table 1 .

GemStone Server Shared Library Files

GemBuilder for Smalltalk requires access to a set of shared library files that are compatible with the specific GemStone server product and version.

The required libraries must match the platform on which the client Smalltalk executable will run, regardless of the platform on which the server is running.

32-Bit VisualWorks Smalltalk

With 32-bit VisualWorks, you must use 32-bit shared libraries. The GemStone/S 64 Bit distribution includes both 32-bit and 64-bit libraries.

With GemStone/S 64 Bit, you can only login RPC from 32-bit VisualWorks.

64-Bit VisualWorks Smalltalk

Using 64-bit GemStone/S 64 Bit shared libraries with 64-bit VW, you can login linked as well as RPC from Solaris and Linux clients. On Windows, only RPC logins are possible.

Supported Platforms and Versions

The following tables describe the client Smalltalk versions and platforms supported by GBS 8.2, and the GemStone/S server products and versions that can be used with each.

Table 1 Supported GemStone/S 64 Bit Server versions

 

VW 8.1.1
32-bit (RPC only)

and

64-bit (RPC, and linked on UNIX)

VW 7.10.1
32-bit (RPC only)

and

64-bit (RPC, and linked on UNIX)

Windows 8

3.3.1, 3.2.15

3.3.1, 3.2.15

Windows 2008 R2

3.3.1, 3.2.15

3.3.1, 3.2.15

Windows 7

3.3.1, 3.2.15

3.3.1, 3.2.15

Ubuntu Linux 12.04

3.3.1, 3.2.15

3.3.1, 3.2.15

Ubuntu Linux 14.04

3.3.1, 3.2.15

3.3.1, 3.2.15

Red Hat Linux ES 6.4

3.2.15

3.2.15

Red Hat Linux ES 6.5

3.2.15

3.2.15

Red Hat Linux ES 6.7

3.3.1

3.3.1

Red Hat Linux ES 7.1

3.3.1

3.3.1

SUSE Linux ES 12

3.3.1, 3.2.15

3.3.1, 3.2.15

Solaris 10 on SPARC

3.3.1, 3.2.15

3.3.1, 3.2.15

2.  Install GBS v8.2 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

GbsToolsVw7.pcl

GbsToolsVw7.pst

GbsToolsVw8.pcl

GbsToolsVw8.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.2.pdf
GBS-InstallGuide-8.2.pdf

Determine the appropriate location for the GBS v8.2 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. If you are using only VisualWorks 7.x, you do not need to copy GbsToolsVw8.*, and vice versa, but copying both sets of files is recommended.

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. Open the Parcel Manager and navigate to the directory containing the GBS 8.2 parcels. Select the parcel GbsTools and load it. This parcel in turn loads the other required parcels, including either GbsToolsVw7.pcl or GbsToolsVw8.pcl. The code detects your VisualWorks version and automatically loads the correct tools parcel.

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.

Complete GemStone/S Server Installation

See the GemStone/S Installation Guide for your client platform for instructions on how to install the GemStone/S server component.

In most cases, you will want to define the $GEMSTONE or %GEMSTONE% environment variable to point to the GemStone server or client installation directory, and add $GEMSTONE/bin or %GEMSTONE%\bin to your machine search path.

Defining $GEMSTONE is required for 64-bit linked logins.

Shared Libraries only

If you will only have RPC logins (with the gem on the stone’s host or on a gemserver), and do not need tools such as topaz, gslist, and VSD on the client, then you may copy only the client shared libraries to your client node. You will need to download the GemStone/S Server or Windows Client, locate the required files, and copy them.

The required shared library files are listed in the following tables, depending on your server product and version.

Note that the GemStone/S 64 Bit server installation includes two directories containing the shared libraries; bin or lib, containing 64-bit libraries and executables, and bin32 or lib32, containing 32-bit libraries and executables.

You may copy the shared libraries to:

  • the VisualWorks installation directory, or a directory under the bin subdirectory of your $VISUALWORKS environment
  • to a directory location on your machine search path, or that you add to the machine search path
  • To a directory that is not on your machine search path.

Your choice of destinations on the client will affect your options in specifying the client library, that is, whether you must include the full path and filename, filename only, or may leave libraryName empty.

The following tables list the specific client libraries that you must copy from the server installation to the client node.

Note that linked library names are not included; linked logins (available on Solaris and Linux) require additional executables on the client, so you cannot simply copy the shared libraries. If you require linked logins on the client, you should follow the instructions above for Complete GemStone/S Server Installation.

Table 2 Shared Libraries to copy for RPC login to GemStone/S 64 Bit 3.3.1

Client Image

Windows
Client Shared Libraries

Solaris or Linux
Client Shared Libraries

32-bit
VW Clients

 

In %GEMSTONE%\bin32\:
 libgcirpc-3.3.1-32.dll
 libssl-3.3.1-32.dll
 msvcr100.dll

In $GEMSTONE/lib32/:
 libgcirpc-3.3.1-32.so
 libssl-3.3.1-32.so

64-bit
VW Clients

 

In %GEMSTONE%\bin\:
 libgcirpc-3.3.1-64.dll
 libssl-
3.3.1-64.dll
 msvcr100.dll

In $GEMSTONE/lib/:
 libgcirpc-3.3.1-64.so
 libssl-3.3.1-64

Table 3 Shared Libraries to copy for RPC login to GemStone/S 64 Bit 3.2.15

Client Image

Windows
Client Shared Libraries

Solaris or Linux
Client Shared Libraries

32-bit
VW Clients

 

In %GEMSTONE%\bin32\:
 libgcirpc-3.2.15-32.dll
 libssl-3.2.15-32.dll
 msvcr100.dll

In $GEMSTONE/lib32/:
 libgcirpc-3.2.15-32.so
 libssl-3.2.15-32.so

64-bit
VW Clients

 

In %GEMSTONE%\bin\:
 libgcirpc-3.2.15-64.dll
 libssl-3.2.15-64.dll
 msvcr100.dll

In $GEMSTONE/lib/:
 libgcirpc-3.2.15-64.so
 libssl-3.2.15-64.so

5.  Determine client shared library to load

Whether 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 4 Library name arguments to libraryName:

Server Product and Version

Windows

Solaris and Linux

 

GemStone/S 64 Bit

v3.3.1

libgcirpc-3.3.1-32.dll

   or

libgcirpc-3.3.1-64.dll

libgcirpc-3.3.1-32.so

   or

libgcirpc-3.3.1-64.so

   or

libgbslnk-3.3.1-64.so

GemStone/S 64 Bit

v3.2.15

libgcirpc-3.2.15-32.dll

   or

libgcirpc-3.2.15-64.dll

libgcirpc-3.2.15-32.so

   or

libgcirpc-3.2.15-64.so

   or

libgbslnk-3.2.15-64.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:

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.1:

GbsConfiguration current libraryName:
	'InstallDir\GemBuilderC3.3.1-x86.Windows_NT\bin32\libgcirpc-
	3.3.1-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.

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.1:

GbsConfiguration current libraryName: 
	'libgcirpc-3.3.1-32.dll'

This option 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.

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