3. Upgrading GLASS/GsDevKit Applications

This chapter describes the additional upgrade step that applies when upgrading an application that is using variants of the open-source Development Kit for GemStone/S 64 Bit (GsDevKit, referred to also as also as GLASS or Seaside) to GemStone/S 64 Bit v3.7. The term GsDevKit is used to collectively refer to any of these environments.

The process described here can be used to upgrade repositories using GLASS, GLASS1, the older GsDevKit environment, and tODE. There are a number of possible configurations and there may be additional setup required for some environments. For more background on these environments, see https://github.com/GsDevKit/GsDevKit_upgrade/blob/master/README.md#upgrading-glassgsdevkit-applications-to-gemstone-350

If you are using the most recent version, from github.com/GsDevKit/GsDevKit_home, then you may use the upgrade scripts provided there to perform the entire upgrade, rather than using the instructions in this Installation Guide.

The complete process for upgrading includes the GemStone standard upgrade, followed by additional GsDevKit upgrade. Upgrading GemStone is described in earlier chapters of this Installation Guide; Chapter 2. You will need to follow the steps in that chapter, which will note the point at which the GsDevKit upgrade takes place.

Upgrade Procedure

The GsDevKit upgrade occurs partway through a standard GemStone upgrade.

To upgrade a GsDevKit/GLASS application:

First, install the new version if GemStone, and upgrade your repository, according to the instructions in Chapter 2.
After the upgradeImage step, you will upgrade the GsDevKit application as described in this chapter.
After the GsDevKit upgrade completes, continue with the remaining steps of the GemStone upgrade in Chapter 2.

1. Ensure that GemStone 3.7 is installed and your repository upgraded

You must first follow install version 3.7 and follow the instructions in Chapter 2, before you can upgrade your GsDevKit application. These instructions will let you know at which point you perform the GsDevKit upgrade.

You should also have confirmed that your application code has been updated as required. We recommend that you install your application code in a test GemStone/S 64 Bit v3.7 repository, and verify that your code is working correctly, making changes as necessary. Do this prior to upgrading the data in your application, to ensure the upgrade process will go smoothly.

2. If necessary, customize the upgrade instructions

There are many ways a GsDevKit or GLASS application may be built, and a variety of packages that can be loaded. The upgradeSeasideImage script will upgrade a hypothetical standard installation, but there may be customizations required in specific cases.

The upgrade is performed by an upgrade script. By default, this is $GEMSTONE/upgrade/createGsDevKit_upgrade.topaz.

The default upgrade script is a file containing topaz commands for the upgrade.

Example 3.1 Default upgrade instructions in createGsDevKit_upgrade.topaz

run

	UserGlobals

		at: #GsDevKit_Image_Upgrade

			put: (GsuAbstractGsDevKitUpgrade

				upgradeUserName: SeasideUpgradeUser).

System commitTransaction

In this script, SeasideUpgradeUser is an internal global that by default resolves to DataCurator.

Customizing upgrade

To create customized upgrade instructions, make a copy of this file, edit the copy, and pass the path to your customized upgrade script file as an argument to the upgradeSeasideImage script.

The following example shows a customized file.

Example 3.2 Example customized upgrade

run

UserGlobals

	at: #GsDevKit_Image_Upgrade

	put: ((GsuAbstractGsDevKitUpgrade

		      upgradeUserName: 'DataCurator'

		      upgradeSymbolDictName: #UserGlobals)

		bootstrapApplicationLoadSpecs: {

		{ 'Metacello' .

			'github://dalehenrich/metacello-work:master/repository' } .

		{ 'GLASS1' .

			'github://glassdb/glass:master/repository' .

			#( 'default' 'Base' 'Announcements') } .

		{ 'Seaside3' .

			'github://SeasideSt/Seaside:master/repository' .

			#( 'CI') 			}

		} ).

System commitTransaction

Further information about LoadSpecs is provided in the comment for $GEMSTONE/upgrade/createGsDevKit_upgrade.topaz.

You may also refer to the example scripts on github, at github.com/GsDevKit/GsDevKit_upgrade/tree/master/bin.

3. Perform the Upgrade

The GsDevKit upgrade is performed by the script upgradeSeasideImage, which is located in the $GEMSTONE/seaside/bin subdirectory.

Prior to executing upgradeSeasideImage, if you need to do a customized upgrade, you should have set up the upgrade script as described above. This is provided a argument to this script.

upgradeSeasideImage [ -c tempObjCacheSize ] [ -s stoneName ] [ -u gemstoneUser ] [ -p password ] [ -P pathToUpgradeScript ] [ -W ] [ -E ]

-c tempObjCacheSize
set the size of the GEM_TEMPOBJ_CACHE_SIZE; if omitted, default is 100000.

-E enable isNil optimization (leave the isNil selector optimized, and not recompilable). Base GemStone upgradeImage enables isNil optimization by default, but there are potential problems with isNil optimization in some Seaside projects. upgradeSeasideImage disables isNil optimization, unless the -E option is specified.
See https://github.com/GsDevKit/GsDevKit_upgrade/issues/30 for more information.

-u gemstoneUser
specify the GemStone user name, if seaside was installed as a user other than DataCurator. If omitted, defaults to DataCurator.

-p password
specify the password for gemstoneUser. If omitted, defaults to swordfish.

-P pathToUpgradeScript
path to customized to GsDevKit_upgrade instance creation script. If omitted, $GEMSTONE/upgrade/createGsDevKit_upgrade.topaz.

-s stoneName
set the name of the running stone to upgrade; if omitted, default is gs64stone.

-W enable GEM_LISTEN_FOR_DEBUG, and set up to allow debugging via debuggem.

For example,

os$ $GEMSTONE/seaside/bin/upgradeSeasideImage -s stoneName37

The script will prompt you to press the return key to begin.

The script should complete with the message:

Seaside Upgrade completed. No errors detected.

If you encounter errors in upgradeSeasideImage, and you are experienced at using topaz, you may use the -W argument, and follow the instructions in the Topaz User’s Guide for v3.6 on how to use debuggem to attach to the upgrade process and debug the error.

4. Load your Application Code

After upgrade has successfully completed, reload your application code.

5. Complete the Upgrade Process

To complete the upgrade, return to Chapter 2 and complete the remaining upgrade steps.