1. Installation

This document describes how to install GemBuilder for Smalltalk v5.4.3.

Please review the GemBuilder for Smalltalk Release Notes for v5.4.3 for details of the changes, before upgrading to this version.

This version of GemBuilder for Smalltalk (GBS) is compatible only with GemStone/S 64 Bit 3.x. Support for 32-bit GemStone/S, and for earlier versions of GemStone/S 64 Bit, is provided in separate releases.

Version 5.4.3 of GemBuilder for Smalltalk supports VA Smalltalk only.

Installing GBS is a multi-step process:

1.   Verify System Requirements

2.   Install GBS v5.4.3 distribution

3.   Load GBS Smalltalk code into your development environment

4.   Install client shared libraries from GemStone/S 64 Bit Server

5.   Configure GBS to load client shared library

6.   Verify installation by logging into the GemStone/S 64-Bit 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 VA Smalltalk image in which GBS is not installed. Follow the instructions in this Installation Guide, and then load your application code.

1.  Verify System Requirements

Prior to installing, verify that your system meets the requirements for v5.4.3.

Operating system

Supported operating systems are listed in Table 1 .

Client Smalltalk

This version of GBS is supported with the 32-bit VA Smalltalk environment, as 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 client library files that are compatible with the specific GemStone/S server product and version.

The required libraries must be for the platform on which GBS will be running, regardless of the platform on which the server is running. With 32-bit VA Smalltalk, you must use 32-bit shared libraries.

Supported Platforms and Versions

The following table describe the client Smalltalk versions and platforms supported by GBS 5.4.3, and the GemStone/S 64 Bit server versions that can be used with each.

Table 1 Supported GemStone/S 64 Bit Server versions

 

VA Smalltalk 8.6.2

VA Smalltalk 8.5.2

Windows 8

3.3, 3.2.12

 

Windows Server 2008 R2

3.3, 3.2.12

3.3, 3.2.12

Windows 7

3.3, 3.2.12

3.3, 3.2.12

.

2.  Install GBS v5.4.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:

gbs5.4.3.dat — The GemBuilder for Smalltalk ENVY data file.

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

GBS-UsersGuide-VA-5.4.pdf (unchanged from previous release)
GBS-ReleaseNotes-5.4.3.pdf
GBS-InstallGuide-5.4.3.pdf

3.  Load GBS Smalltalk code into your development environment

Loading GemBuilder is a two-step process:

Importing into your ENVY Repository

You need to perform this procedure only once per ENVY repository. You can then load GBS from that repository into any number of Smalltalk client images.

1. Start a client Smalltalk image.

2. In the Configuration Maps Browser, choose Names > Import > Selected Versions....

3. A dialog will open requesting Enter the IP address or host name of the server. Leave the field blank and click on OK.

4. In the resulting dialog, navigate to the GBS distribution location and select the file gbs5.4.3.dat.

5. Click Open.

6. In the Name pane on the left, select the GBSGemBuilder configuration map to import.

7. In the middle versions pane, select version 5.4.3, and click >> to move it to the Selected versions pane on the right.

8. Click OK or Accept.

9. Check in the Configuration Maps Browser to ensure that the configuration map was imported.

Loading into an Image

1. Start a client Smalltalk image which does not have any previous versions of GemBuilder for Smalltalk loaded.

2. From a Configuration Maps Browser, select the newly imported GBSGemBuilder map in the Names pane on the left. Version 5.4.3 appears in the middle Editions and Versions pane.

3. In the Editions and Versions pane, select 5.4.3 and choose the menu item Load to load the configuration map.

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 64 Bit Server

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

These client libraries should be the same release version as the GemStone/S 64 Bit server.

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

Complete GemStone/S 64 Bit Windows Client Installation

See the GemStone/S 64 Bit Windows Client Installation Guide for instructions on how to install the GemStone/S 64 Bit Windows Client.

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

Shared Libraries only

If you do not need tools such as topaz, gslist, and VSD on the client machine, then you may copy only the shared client libraries to your client node. You will need to download the GemStone/S 64 Bit Windows Client, locate the required files, and copy them.

The required libraries files are listed in table Shared Libraries to copy GemStone/S 64 Bit Server Distribution.

Note that the server installation includes two directories containing the shared libraries; bin, containing 64 bit libraries and executables, and bin32, containing 64 bit libraries and executables. Ensure you copy the client library files from the bin32 directory (GBS supports only 32-bit VA Smalltalk).

You may copy these shared libraries to:

  • the VA Smalltalk working directory, or the directory containing the executables for your VA Smalltalk installation (either the installation directory, or the bin subdirectory, depending on your version).
  • 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 or only the name of the file.

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

Table 2 Shared Libraries to copy GemStone/S 64 Bit Server Distribution

Server Product and Version

Windows
Client Shared Libraries

Argument to libraryName:

GemStone/S 64 Bit
v3.3

 

In %GEMSTONE%\bin32:

  • libgcirpc-3.3.0-32.dll
  • libssl-3.3.0-32.dll
  • msvcr100.dll

 

libgcirpc-3.3.0-32.dll

 

GemStone/S 64 Bit
v3.2.12

In %GEMSTONE%\bin32:

  • libgcirpc-3.2.12-32.dll
  • libssl-3.2.12-32.dll
  • msvcr100.dll

libgcirpc-3.2.12-32.dll

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. Only one library name is set by this parameter, although all the listed library files must be available, usually in the same location, in order for the library load to succeed and logins to work. The library name to specify is listed in Table 2 

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:

GbsConfiguration current libraryName: 'InstallDir\GemStone64Bi
   tClient3.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%.

Set libraryName to the file name of the client library file, without the path.
For example:

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

This options requires that the library be in a directory on the %PATH%, in the current working directory, or in the VA Smalltalk executable directory.

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 64-Bit 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 64 Bit server. You will need to ensure that the Stone repository monitor and a NetLDI are accessible.

See the GemBuilder for Smalltalk User’s Guide, Chapter 11, for instructions on logging into the GemStone/S 64 Bit server.