1. Installation

This document describes how to install GemBuilder™ for Smalltalk (GBS) v8.3.

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

This version of GemBuilder for Smalltalk is compatible with both GemStone/S 64 Bit, the 64-bit GemStone/S-based object server, and with GemStone/S, the original 32-bit GemStone object server. Applications using GBS version 8.3 can log in to either GemStone/S 64 Bit or GemStone/S repositories (but not simultaneously), provided that the appropriate client libraries for each are used. For details, see GemStone Server Shared Library Files.

GBS v8.3 is supported with the VisualWorks Smalltalk environment only, and 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

1.   Install GBS v8.3 distribution

2.   Load GBS Smalltalk code into your VisualWorks Image

3.   Install client shared libraries from GemStone/S Server

4.   Determine client shared library to load

5.   Configure GBS to load client shared library

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

Operating system

Supported operating systems are listed in Table 1   and Table 2  .

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 in Table 1   and Table 2  .

The 32-bit VisualWorks Smalltalk environment is supported with both 32-bit GemStone/S and GemStone/S 64 Bit.

The 64-bit VisualWorks Smalltalk environment is supported with GemStone/S 64 Bit only.

GemStone Server

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

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. These are distributed with both 32-bit GemStone/S and with GemStone/S 64 Bit. The GemStone/S 64 Bit distribution includes both 32-bit and 64-bit libraries.

32-bit GemStone/S allows both linked and RPC logins from 32-bit VisualWorks.
With GemStone/S 64 Bit, you can only login RPC from 32-bit VisualWorks.

64-Bit VisualWorks Smalltalk

With 64-bit VW, you can only login to GemStone/S 64 Bit; it is not compatible with 32-bit GemStone/S.

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.3, 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.2.1
32-bit

and

64 bit

VW 8.1.1
32-bit

 

VW 7.10.1
32-bit

 

VW 7.10.1
64-bit

Windows 10

3.4, 3.3.6

 

3.4, 3.3.6

3.4

Windows 8

3.4, 3.3.6

3.3.6

3.4, 3.3.6

 

Windows 2008 R2

3.4, 3.3.6

3.3.6

3.4, 3.3.6

 

Windows 7

3.4, 3.3.6

3.3.6, 3.2.17

3.4, 3.3.6, 3.2.17

3.3.6

Ubuntu Linux 16.04

3.4, 3.3.6

 

3.4, 3.3.6

 

Ubuntu Linux 14.04

3.4, 3.3.6

3.3.6, 3.2.17

3.4, 3.3.6, 3.2.17

 

Red Hat Linux ES 7.1

3.4, 3.3.6

 

3.4, 3.3.6

3.4

Red Hat Linux ES 6.7

3.4, 3.3.6

3.3.6, 3.2.17

3.4, 3.3.6, 3.2.17

3.3.6
Table 2  Supported 32-bit GemStone/S Server versions

 

VW 7.10.1

32-bit

Windows 2008 R2

  6.7

Windows 7

  6.7

Red Hat Linux ES 6.5

  6.7

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

GbsToolsVw821.pcl

GbsToolsVw821.pst

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

GBS-UsersGuide-VW-7.6.pdf

GBS-ReleaseNotes-8.3.pdf

GBS-InstallGuide-8.3.pdf

To install, determine the appropriate location for the GBS v8.3 parcels. 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 all files is recommended.

2.  Load GBS Smalltalk code into your VisualWorks Image

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

2. Open the parcel manager. In VW 7.x, use the VW Laucher menu item System > Parcel Manager; in 8.x, the Laucher menu item Tools > Parcel Manager.

3. Select the Parcel Manager menu item File > Load Parcel File..., and navigate to the directory containing the GBS 8.3 parcels. Select the file GbsTools.pcl and load it (if you don’t see files with the .pcl extension, check the filter settings). This parcel loads the other required parcels, including the version specific tools parcel/s and the runtime parcel.

The code detects your VisualWorks version and automatically loads the correct additional version-specific tools parcel or parcels. VW 7.10.1 images load the GbsToolsVw7.pcl. VW 8.1.1 images load GbsToolsVw8.pcl. VW 8.2.1 images load both GbsToolsVw8.pcl and GbsToolsVw821.pcl.

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.

3.  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 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 server on the client node, or just copy the specific shared libraries that are required.

Complete GemStone Server Installation

See the GemStone Installation Guide for your client platform for instructions on how to install the GemStone 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 the $GEMSTONE environment variable 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 (on 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 Server Installation.         

Table 1 Shared Libraries to copy for RPC login to GemStone/S 64 Bit 3.4

Client Image

Windows
Client Shared Libraries

Linux
Client Shared Libraries

32-bit
VW Clients

 

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

In $GEMSTONE/lib32/:
 libgcirpc-3.4.0-32.so
 libfloss-3.4.0-32.so

64-bit
VW Clients

 

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

In $GEMSTONE/lib/:
 libgcirpc-3.4.0-64.so
 libfloss-3.4.0-64
Table 2 Shared Libraries to copy for RPC login to GemStone/S 64 Bit 3.3.6

Client Image

Windows
Client Shared Libraries

Linux
Client Shared Libraries

32-bit
VW Clients

 

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

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

64-bit
VW Clients

 

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

In $GEMSTONE/lib/:
 libgcirpc-3.3.6-64.so
 libssl-3.3.6-64.so
Table 3 Shared Libraries to copy for RPC login to GemStone/S 64 Bit 3.2.17

Client Image

Windows
Client Shared Libraries

Linux
Client Shared Libraries

32-bit
VW Clients

 

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

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

64-bit
VW Clients

 

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

In $GEMSTONE/lib/:
 libgcirpc-3.2.17-64.so
 libssl-3.2.17-64.so
Table 4 Shared Libraries to copy for RPC login to 32-Bit GemStone/S 6.7

Client Image

Windows
Client Shared Libraries

Linux
Client Shared Libraries

32-bit

VW Clients

 

In %GEMSTONE%\bin\:
 gcirw67.dll
 gsw67.dll
 englis67.err

In $GEMSTONE/lib/:
 libgcirpc67.so

In $GEMSTONE/sys/:
 english67.err

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

Server Product and Version

Windows

Solaris and Linux

 

GemStone/S 64 Bit

v3.4

libgcirpc-3.4.0-32.dll

   or

libgcirpc-3.4.0-64.dll

libgcirpc-3.4.0-32.so

   or

libgcirpc-3.4.0-64.so

   or

libgbslnk-3.4.0-64.so

GemStone/S 64 Bit

v3.3.6

libgcirpc-3.3.6-32.dll

   or

libgcirpc-3.3.6-64.dll

libgcirpc-3.3.6-32.so

   or

libgcirpc-3.3.6-64.so

   or

libgbslnk-3.3.6-64.so

GemStone/S 64 Bit

v3.2.17

libgcirpc-3.2.17-32.dll

   or

libgcirpc-3.2.17-64.dll

libgcirpc-3.2.17-32.so

   or

libgcirpc-3.2.17-64.so

   or

libgbslnk-3.2.17-64.so

GemStone/S

v6.7

gcirw67.dll

   or

gcilw67.dll

libgcirpc67.so

   or

libgcilnk67.so

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

For example, for 32-bit VisualWorks clients on Windows, logging into GemStone/S 64 Bit v3.4:

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

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

GbsConfiguration current libraryName: 
    'libgcirpc-3.4.0-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.

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.

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.

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