GemKit for Source Code Management (SCM)

User's Manual

Version 4.x

 

About This Manual

This manual describes the GemKit™ for Source Code Management (SCM), a toolkit for managing GemStone Smalltalk code through the ENVY/Developer toolkit.

This manual assumes that the reader is familiar with the standard ENVY development process and with the GemStone object application server. Refer to the section "Other Useful Documents" for sources of ENVY and GemStone information. This manual also assumes that the SCM toolkit has been installed correctly on your development system, as described in the Release Notes, and that the system meets the requirements described in the installation instructions.

This manual is organized as follows:

Terms

In order to distinguish the various kinds of Smalltalk code managed with ENVY and the various repositories and images affected by the SCM toolkit, this manual uses the following terms:

client Smalltalk
VisualWorks or VisualAge Smalltalk.

ENVY/Smalltalk image
The Smalltalk image managed by ENVY and containing both client Smalltalk code and GemStone Smalltalk code stored in the form of special client Smalltalk classes.

ENVY repository The repository where ENVY stores the client Smalltalk image. GemStone Smalltalk code managed by the SCM toolkit is stored in this repository in the form of special client Smalltalk classes.

GemStone repository
The repository which holds the GemStone Smalltalk image. GemStone Smalltalk is inherently persistent, so changes to GemStone Smalltalk code are automatically stored into the repository.

GemStone Smalltalk
Smalltalk code that is stored in the GemStone repository and executed by the GemStone object application server.

Typographical Conventions

This document uses the following typographical conventions:

mkdir

gbwparams.htf

In the Application menu of the GemStone Application Manager, select the menu option update gemstone. When a prompter appears, press OK.

setenv GBWEB value

 

Related Documentation

You may find it useful to refer to other documents for further information on GemStone and ENVY:

.1 Introducing the SCM Toolkit

The GemKit for Source Code Management (SCM) toolkit for ENVY allows developers to create and manage GemStone Smalltalk code within the ENVY environment. The toolkit consists of code fileins to ENVY, GemStone, and the client Smalltalk image. It adds some additional tools and options to the ENVY/Developer toolkit, for the purpose of GemStone code management.

The requirements for this framework are: 1) GemStone/S; 2) IBM VisualAge for Smalltalk or Cincom VisualWorks (with OTI ENVY/Developer); 3) GemStone GemBuilder for Smalltalk (GBS). The framework is expected to work with all recent versions of any of these requirements. The SCM framework comes in the form of a single binary ENVY DAT file that contains code that can be imported and loaded into any VisualAge or VisualWorks Smalltalk image that has support for ENVY/Developer and GBS.

SCM was originally created by GemStone Professional Services (GPS) of GemStone Systems, Inc. GPS consultants evolved the framework over a several year period to meet customer needs. In December 2000, GemStone Engineering took responsibility of the code out of a need to keep the code operational with the latest Smalltalk and GBS releases. In March 2002, GemStone decided to release this code into the public domain for use and maintenance by all. SCM 4.0 represents the first public release of SCM for ENVY.

1.2 Developing GemStone Smalltalk Code in ENVY

The SCM toolkit allows developers to create, version, and configure GemStone Smalltalk code using ENVY tools and to store GemStone code within the ENVY code repository. This section describes the architecture of the SCM toolkit, the SCM additions to the ENVY toolkit, and the development cycle for GemStone code using the SCM toolkit.

SCM Toolkit Architecture

In normal GemStone development, GemStone Smalltalk code is created using a tool such as GemBuilder for Smalltalk and compiled into the GemStone repository. (GemStone Smalltalk is inherently persistent, so when GemStone Smalltalk code is compiled, the compiled code immediately becomes part of the image in the GemStone repository.)

GemStone application development proceeds somewhat differently when the GemStone Smalltalk code is being managed through ENVY. Figure 1.1 illustrates the development process.

Figure 1.1 GemStone Smalltalk Development with ENVY

With the ENVY SCM toolkit, GemStone Smalltalk code is created with SCM tools in the ENVY environment. The developers use ENVY to create configuration maps, applications, subapplications, classes, and methods, just as they do when creating client Smalltalk code with ENVY. When the code is saved, it is automatically stored in the ENVY/Smalltalk image (as a special set of classes) and in the ENVY repository, and it is compiled into the GemStone repository. Changes made to GemStone code through the SCM toolkit automatically update both the ENVY and GemStone copies of the code.

Class Mapping: Client Smalltalk to GemStone Smalltalk

The SCM toolkit maps GemStone Smalltalk classes to a set of classes in the ENVY/Smalltalk image so that they can be stored in the ENVY repository. In the ENVY development environment (and in the client Smalltalk image) the names of GemStone classes, applications, and subapplications must be created with the prefix "GS_". For example, the class Set that exists in GemStone in the SymbolDictionary named Globals will exist in the ENVY/ Smalltalk image as GS_Set in the ENVY application GS_Globals (provided by the SCM toolkit). The SCM toolkitís GemStone Application Manager checks names and ensures that you use this prefix when creating application and subapplication names and other GemStone Smalltalk classes in ENVY.

Table 1.1 shows the class mapping for a Hotel Reservation system :

Table 1.1 Client Smalltalk-to GemStone Smalltalk Class Mapping

ENVY/Smalltalk

GemStone Smalltalk

 

 

GemStoneSourceCodeManagement (aConfigurationMap)

 

GS_Globals

Globals (a SymbolDictionary)

GS_UnOrderedCollection (a Class)

UnOrderedCollection (a Class)

...

...

GS_UserProfileSet (a Class)

UserProfileSet (a Class)

GemStoneReservationsSubSystem (aConfigurationMap)

 

GS_BookableAssets (a GbcApplication)

BookableAssets (a SymbolDicitonary)

GS_Room (a Class)

Room (a Class)

GS_SmokingRoom (a Class)

SmokingRoom (a Class)

GS_BanquetHall (a Class)

BanquetHall (a Class)

GS_Rates (a GbcApplication)

Rates (a SymbolDictionary)

GS_RackRate (a Class)

RackRate (a Class)

GS_CorporateRates (aGbcSubApplication)

 

GS_ACMERate (aClass)

ACMERate (a Class)

 

Client Smalltalk classes that represent developersí GemStone Smalltalk source code start at the root class GbcHierarchyRoot and are identified with the prefix "GS_". Modifications to the "GS_" classes will be reflected in the GemStone repository.

Note

The "GS_" prefix does not exist in the code that is executed in the GemStone repository, so the prefix should never appear in class names used within the body of a method.

Classes that implement SCM toolkit functionality are prefixed with "Gbc". You will see these classes in your ENVY/Smalltalk image, but you should have no need to modify them.

Code Management for Multi-User Smalltalk

GemStone is a multi-user Smalltalk environment. This allows users and developers to share access to classes and other objects. It is possible for developers to work on shared applications through GemStone; however this would defeat the intention of managing code through ENVY. In addition, sharing applications through GemStone would allow developers to overwrite each otherís changes and compromise other developersí test results. Therefore it is recommended in general that developers work with private copies of applications and test data in GemStone and share application code through ENVY. Refer to Chapter 2 for detailed information about configuring the development environment and sharing code during development.

When a group of developers is working together on a GemStone Smalltalk application using the SCM toolkit, developers should maintain private development environments in GemStone and share code through ENVY, by checking changes in and updating their GemStone repository with new versions from ENVY. Development strategies are discussed in more detail in Chapter 2.

Shared Method Implementation

The SCM toolkit allows to you to share method implementations between client Smalltalk and GemStone Smalltalk applications. This is useful for classes which require the same implementation in GemStone and in client Smalltalk. The SCM toolkit allows you to mark a method as shared, and from that point on any changes made to the methodís implementation are automatically made for you in the client Smalltalk image, in the GemStone repository, and in the ENVY representation of the GemStone Smalltalk class.

Figure 1.2 GemStone Smalltalk Development with ENVY

 

For example, if the client Smalltalk class Apple has a method called >>peelMe, you can create the same method in the GemStone Smalltalk class Apple (and in GS_Apple, the ENVY representation of the GemStone Smalltalk class). You would then mark >>peelMe as being shared, using the change shared status selection in the method browser menu). Then whenever a developer makes a change to the method in the client Smalltalk class Apple (using any ENVY code browser) or in the GemStone Smalltalk class GS_Apple (using the GemStone Application Manager) and compiles the change, the changed method is recompiled with the new code in the client Smalltalk class, the GS_Apple representation of the GemStone Smalltalk class Apple, and in the class Apple in the GemStone repository. The developer only needs to make code changes in one place, and the SCM toolkit keeps the methods consistent.

 

There is no automatic mechanism to mark classes as shared. However, you can effectively share class implementation by marking all a classís methods as shared.

The developer can use the SCM toolkitís Comparison Browser tool to view shared method implementations and confirm that the methodís implementation is the same for client and GemStone Smalltalk. The Comparison Browser is described in more detail in Section 1.3.

Basic Development Cycle

Development with the ENVY SCM toolkit uses the same roles as normal ENVY development: Library Supervisor, Class Owner, Application Manager, and Application Developer. Owners and Developers must be defined for the GemStone Smalltalk code maintained through ENVY.

To manage GemStone Smalltalk code most effectively through the SCM toolkit, developers must create and modify their code in the ENVY/Smalltalk environment, using interactive mode so that the ENVY/Smalltalk and GemStone repositories remain in sync. Developers should share GemStone Smalltalk code through the ENVY repository, and not through the GemStone repository.

To execute or test GemStone Smalltalk code, the developer must invoke execution from a GemStone Workspace.

 

Note: Do not attempt to execute GemStone Smalltalk code in the ENVY image. Executing GemStone Smalltalk code in ENVY produces incorrect results and may damage your ENVY/Smalltalk image.

The SCM toolkit automatically compiles code changes into the GemStone repository, but it does not automatically commit the changes. It is the developerís responsibility to determine when to commit changes to GemStone. Aborting the current GemStone transaction will erase from GemStone all changes made since the last commit. Batch updates can be used to re-synchronize ENVY and GemStone after an abort. (Refer to Chapter 3 for more information on batch updates.)

 

Figure 1.3 GemStone Smalltalk Development with ENVY


The basic development process is illustrated in Figure 1.3:

1.3 ENVY SCM Tools

The SCM toolkit adds some additional tools to the standard ENVY toolkit, and it modifies some other tools to support the development and management of GemStone Smalltalk.

GemStone Application Manager

The GemStone Application Manager is a browser, similar to the ENVY Application Manager, except that it only displays and operates on GemStone applications and classes (applications and classes whose names in ENVY/Smalltalk have the "GS_" prefix). The GemStone Application Manager has new and changed menu items to keep the ENVY/Smalltalk image and the GemStone repository in sync.

Figure 1.4 The GemStone Application Manager

The GemStone Application Manager commands are presented in detail in Appendix A.

GemStone Changes Browser

The SCM toolkit's Changes Browser is based on the ENVY Changes Browser, but the SCM Browser shows differences between GemStone methods in the ENVY/Smalltalk image and methods in the developerís GemStone repository (whereas the ENVY Changes Browser shows differences between different code versions in ENVY).

Figure 1.5 The SCM Changes Browser

For example, the SCM Changes Browser would show differences between the >>peel_me method in the ENVY/Smalltalk class GS_Apple and the class Apple in the GemStone repository. Note that this is, in effect, a GemStone-to-GemStone Smalltalk comparison. To compare differences between client Smalltalk and GemStone Smalltalk method implementation, use the SCM Comparison Browser, described in the next section.

Figure 1.6 Comparisons in the SCM Changes Browser

 

The GemStone Changes Browser commands are presented in detail in Appendix A.

 

GemStone Comparison Browser

A Comparison Browser is provided to help developers identify differences between shared method implementations in client Smalltalk and GemStone Smalltalk.

Figure 1.7 The SCM Comparison Browser

 

This browser is raised whenever you try to version an application which contains one or more shared methods that are not in sync. This browser can also be launched by a Developer at any time from the GemStone Application Managerís popup menu, using the menu selection compare with mirror. This popup menu option is not available from the standard ENVY Application Manager.

 

Figure 1.8 Comparisons in the SCM Comparison Browser

The GemStone Comparison Browser is a subclass of the ENVY Changes Browser. It functions exactly like an ENVY Changes Browser except that it does not filter out methods whose code is the same. In other words, it shows you all existing classes and methods and lets you browse through to see if there are any differences. This browser will show methods that have been added as extensions to classes in other applications. This browser has shared/unshared toggles. No public/private view toggles are provided.

Other Tools

The SCM toolkit adds additional menu items to a number of other ENVY tools to support the management of GemStone Smalltalk code. Appendix A presents detailed explanations of the new menu items.

Chapter 2ĖStrategies for Team Development

There are several issues in team Smalltalk development for GemStone beyond the versioning of classes :

These issues are covered in detail in the following sections.

2.1 Planning a Development Strategy

Regardless of your development strategy, you should carefully plan, document and communicate your teamsí approach to managing both code and test data. On large team projects, the management of test data can become as challenging as the management of code.

 

2.2 Using Multiple GemStone Namespaces

Because GemStone Smalltalk is multi-user, each GemStone user has an individual namespace. Each GemStone user has an account object called a UserProfile, which contains a SymbolList for that user. The GemStone compiler defines any symbol which is not local to the current method or its class by looking in the current userís SymbolList. Any object created by a GemStone user is private (referenced only by that userís SymbolList) unless a reference to that object is explicitly placed in another userís SymbolList or in a shared SymbolList that is referenced by a group of users. The SCM toolkit maps each GemStone application in a GemStone userís SymbolList (System myUserProfile symbolList) to an ENVY/Smalltalk application of the same name (with the "GS_" prefix, of course).

Each GemStone developer should have a separate GemStone user account and will therefore operate within a private namespace. Source code changes made by each developer affect only the classes and methods in their own namespace. Although developers may start with the same GemStone Smalltalk code, they do not see or change other developersí classes or methods in GemStone. By managing changes through the ENVY repository, other developersí changes can be viewed and merged using the standard ENVY tools.

If necessary during development, developers can use the message System resolveSymbol to resolve references to Global symbols. When moving to production, assign the Global symbol its production value, change the code to reference that symbol directly, and recompile the method.

2.3 Developing with Shared SymbolLists

If a development team is working within a shared GemStone repository and sharing references to application code, conflicts can be avoided by enforcing Class Ownership through standard ENVY and GemStone mechanisms.

With this approach, each class is maintained by a single developer. In order to share access to an application, the application must appear in a GemStone SymbolDictionary which is added to the UserProfile SymbolList of each developer. Order is then maintained by allowing only the Class Owner in ENVY to update each class.

In GemStone, each class should be assigned to the Class Ownerís segment. (A segment is a GemStone authorization object. A segment defines access privileges for objects assigned to it.) Other developers may have read access to the segment, but only the Class Owner has the privileges to update that segment.

For example, if one developer owns the class GS_Hotel, then only that developer can release a new edition of GS_Hotel to its owning application in ENVY to make the new edition available to other developers. This person should be the only developer with the necessary authorization to update the Hotel class in GemStone. Other developers may create new editions of GS_Hotel and modify the code, but they cannot update the Hotel Class in GemStone.

2.4 Symbol Resolution in GemStone

In GemStone Smalltalk, references to global variables are resolved at compile time using the SymbolList of the developer who compiles the method. The reference is stored in the compiled method as a pointer to an association which points, in turn, to an object. When a method containing the reference is executed by any GemStone user, the global is resolved using the assocation that existed when the method was compiled.

If the object being referenced is a class, then the assocation is updated to point to the newest version of the class whenever a new version is created using normal GemBuilder functions, and methods will continue to execute as expected. However, if a developer removes or changes an associationófor example during a major test data rebuildóall methods that reference that association must be recompiled or the method will generate run-time errors. (In general, it is best not to remove associations.)

If different developers have compiled methods which reference objects with the same name, then run each otherís methods, the results will reflect the other developerís objects. In this case, it is best to choose one object and give each developer a reference to it.

If a method requires that a reference be resolved at run time, use the resolveSymbol method, as discussed in Chapter 3.

2.5 Configuring and Using Development, Test, and Production Repositories

When doing team development of GemStone Smalltalk applications, it is most efficient to maintain separate GemStone repositories for development, test, and production. This section describes how to set up and work with these repositories.

Configuring the GemStone Development Environment

This section presents three possible approaches to setting up the GemStone Smalltalk development environment, depending on the number of developers involved in the project and the complexity of the application(s). In all cases, the developers share application code through ENVY, not through the GemStone repository.

Option 1: Separate GemStone Repositories (>6 developers)

In this configuration, each developer works in a separate GemStone repository. A developerís work is not visible to other developers. Developers load the editions of all the required GemStone Smalltalk Classes into their ENVY/Smalltalk images, then update their GemStone repositories. All GemStone Smalltalk changes are made in the ENVY repository, so that other developers and managers can see work in progress (and finished work) by browsing the ENVY library. Even though each developer is using a private repository, the Configuration Map Managers, Application Managers, and Class Owners can still browse and merge code using the shared ENVY repository.

The advantage of this option is that test data and specific class versions can easily be maintained for each developer and there is no chance that developers will interfere with each otherís work by modifying the same GemStone Smalltalk classes. The disadvantage is that this option requires enough resources to run multiple GemStone databases.

When each developer is using their own GemStone repository, it is also helpful to maintain a "clean" repository that contains the most recently released versions of all base behavior (tools, utilities, modifications to the GemStone kernel, etc.). This is similar to what most groups do with client Smalltalk development images. This will make it easier to bring new developers into the project and to reset current developersí environments if necessary.

Option 2 : One GemStone Environment for All Developers (< 15 developers)

For small to medium-sized projects, there are some advantages to sharing a single GemStone repository. Shared global and test data can be maintained easily. Changes can be viewed and integrated across the whole project quickly. There are fewer repositories to backup, and less memory and disk space are required.

There are two ways to have developers work within a single repository. In the first approach, developers have separate namespaces. Developersí changes do not affect each other, and the code is still shared and managed through ENVY. It is as if each developer were working in a separate repository, but fewer resources are required.

In the second approach, developers share access to code or data by sharing references to the SymbolLists containing the code. This approach carries the risk that developers will make conflicting changes to shared objects. For more information on how to avoid these problems, refer to Section 2.3, "Developing with Shared SymbolLists."

Option 3 : One GemStone Development Environment Per Subsystem (complex projects)

If a project is large enough to be broken down into significant subsystems, there may be an advantage to separating development along these lines. For example, a Hotel Business System may be split into Accounting, Reservations and Property Maintenance subsystems, with each subsystem having its own GemStone development environment. Developers working on one subsystem can access and load updates to classes from other subsystems as necessary, for instance, when a major release of Utilities code is made available across subsystem development groups. Developers should still maintain separate namespaces (refer to Option 2, above).

Working in the Test Repository

Use the test environment to test "released" versions of your application components against large amounts of test data. The following strategies are recommended for setting up and using the test repository:

The Production Repository

If necessary during development, developers can use the message System resolveSymbol to resolve references to Global symbols. When moving to production, assign the Global symbol its production value, change the code to reference that symbol directly, and recompile the method.

2.6 Managing Security

During development, you will want to test your production implementation of GemStone security mechanisms without hindering the work of developers. The recommended strategy for doing this is to "turn off" security for all developers in the development repository and create "business users" to test your security implementation, by following these steps:

To test your implementation of GemStone-based business security mechanisms, login to your development environment as a business user. You now have full access to read or write any and all objects associated with the WorldAccessSegment, but restricted privileges to read/write data associated with other segments you have built to enforce business security rules.

Chapter 3ĖCode Management Procedures

This chapter gives detailed procedures for developing GemStone Smalltalk code using the SCM toolkit. The procedures include:

3.1 Creating GemStone Applications and Classes

You can create GemStone Smalltalk applications and classes in the ENVY repository either through the SCM toolkitís GemStone Application Manager or from existing applications and classes in the GemStone repository.

Creating New GemStone Smalltalk Applications and Classes

    1. Login to GemStone.
    2. Open a GemStone Application Manager by selecting manage gemstone applications from the Launcherís ENVY menu in VisualWorks or, in VisualAge, from the Smalltalk menu in the System Transcript.
    3. From the Application menu in the GemStone Application Manager, select create>gemstone application.
    4. When a prompter appears, enter the name of the application.
    5. If a prompt appears asking whether to prefix the name with "GS_", press OK.
    6. Create a subapplication, if desired, by repeating steps 3 and 4, except that you will select create>gemstone subapplication.
    7. By default, the SCM toolkit will immediately create a GemStone SymbolDictionary in your current GemStone view with the same name as your new ENVY GemStone application (without the "GS_" prefix).
    8. From the Application menu, choose browse gemstone application. An ENVY Application Browser will be opened presenting a class template with the correct syntax to create classes in GemStone Smalltalk.
    9. Modify this template to create your new GemStone class. For example, to create a new GemStone class named Hotel, modify the template so that the superclass is GS_Object and the new class is GS_Hotel.
    10. You can start creating protocols and methods as you usually do in ENVY. These new protocols and menus will immediately be updated in your current GemStone view.

Class definitions are displayed in ENVY/Smalltalk browsers with different syntax than either client Smalltalk or GemStone Smalltalk, as shown in Example 3.1.

Example 3.1 Envy/Smalltalk Class Devinitions for GemStone

GS_Object subclass: 'GS_Segment'

instVarNames: #('itsRepository' 'itsOwner' 'groupsRead' 'groupsWrite' 'ownerAuthorization' 'worldAuthorization' 'spare1')

classVars: #('AuthorizationSymbols' 'AuthorizationFactors' 'AuthorizationMasks')

classInstVars: #()

poolDictionariesString: #()

inDictionary: 'Globals'

constraintsString: #(#('itsRepository' 'Repository')

#('itsOwner' 'UserProfile')

#('groupsRead' 'SymbolSet')

#('groupsWrite' 'SymbolSet')

#('ownerAuthorization' 'SmallInteger') #('worldAuthorization' 'SmallInteger'))

instancesInvariant: false

description: nil

isModifiable: false

All names are quoted, and parentheses "()" are used in place of square brackets "[]". Class definitions can be modified by following this syntax and accepting it in an ENVY/Smalltalk Browser.

Note

Do not change the isModifiable: declaration in GemStone class definitions in ENVY. See the GemStone Programmers Guide for a discussion of this declaration.

Creating GemStone Applications in ENVY From Existing GemStone Code

    1. Login to GemStone.
    2. Confirm that the GemStone SymbolDictionaries you wish to load into the ENVY repository are in the current GemStone userís SymbolList.
    3. Open a GemStone Application Manager by selecting manage gemstone applications from the Launcherís ENVY menu in VisualWorks or, in VisualAge, from the Smalltalk menu in the System Transcript.
    4. In the GemStone Application Manager, create a GemStone application:
    1. Create a subapplication if desired. Follow the same sequence as in step 4, except that you will select create>gemstone subapplication.
    2. If necessary select the subapplication that you just created, then middle-click and select set as default.
    3. Follow the directions in the section "Batch Update Mechanism."

3.2 Initializing Global Definitions and Data

When loading a given version of an application into the GemStone repository, it may be necessary to define and initialize certain global data.

The SCM toolkit provides functionality similar to the standard ENVY method Application>>toBeLoadedCode: (see the ENVY documentation) in the methods Gbc(Sub)Application>>preLoadedCode and Gbc(Sub)Application>>postLoadedCode. Each time a GemStone Smalltalk application or subapplication is updated from ENVY, the SCM toolkit goes through the following update process:

    1. The GemStone Smalltalk code defined as a string in preLoadedCode is executed in GemStone.
    2. Class and method changes youíve made are compiled into GemStone.
    3. The GemStone Smalltalk code defined as a string in postLoadedCode is executed in GemStone.

The method preloadedCode is used to initialize objects that are needed for successful compilation of GemStone code being loaded from ENVY. A typical use of preLoadedCode might be to define Global names:

Example 3.2 preLoadedCode method

preLoadedCode

^ĎUserGlobals at: #MyGlobalName put: nil.í

 

The method postLoadedCode is used to initialize data after compilation of GemStone code from ENVY. A typical use of postLoadedCode might be to define Global data.

Example 3.3 postLoadedCode method

postLoadedCode

^ĎMyGlobalName := TestClass buildTestDataí

 

3.3 Synchronizing Code Changes

Compiling All Changes in GemStone Smalltalk and ENVY/Smalltalk

By default, all changes made to "GS_" prefixed classes are automatically compiled and placed in both the ENVY repository and the GemStone database. For example, whenever a developer accepts code from the ENVY Class Browser, Classes Browser, Class Hierarchy Browser, Application Browser, Applications Browser, or Debugger, both the ENVY repository and the GemStone repository are updated.

All changes made in ENVY are automatically synchronized, including:

Batch Update Mechanism

Normally updates in ENVY will automatically be made in GemStone as well. However there are circumstances in which you will have to do batch updates to synchronize ENVY/Smalltalk and the GemStone repository.

You may need to update your ENVY image from the GemStone repository at the following times:

You may need to update your GemStone repository from the ENVY image at the following times:

Batch updates can be made in either direction, from ENVY to the GemStone repository and from the GemStone repository to ENVY. Batch updates can be done at the level of a single method or multiple methods, classes, or applications. The level is determined by what you have selected in the GemStone Application Manager.

Note

When doing batch updates from Envy to GemStone, never select the class GS_Globals as the target of the update. Replacing global classes while the GemStone object manager is active may damage the repository.

To load modifications from ENVY into GemStone:

    1. Login to GemStone. The SymbolDictionaries to be updated must be visible from the GemStone userís SymbolList.
    2. Open a GemStone Application Manager by selecting manage gemstone applications from the Launcherís ENVY menu in VisualWorks or, in VisualAge, from the Smalltalk menu in the System Transcript.
    3. Select the corresponding GemStone application in the Application pane of the GemStone Application Manager.
    4. If you only want to update particular classes, select those classes in the middle pane.
    5. From the Applications or Classes pop-up menu choose update gemstone.
    6. If you changed a class definition by adding or deleting an instance variable or by changing the classís superclass, the subclasses of the changed class will be automatically recompiled when you update GemStone.
    7. When the prompter appears, select Yes or No, depending on whether you wish to migrate instances.
    8. If the "GS_" class has one or more subclasses, a prompter will appear asking whether you want to migrate instances of the subclasses. Select Yes or No, depending on whether you wish to migrate instances.

Note

This operation will only migrate instances to which you have write access.

To load modifications from the GemStone repository into ENVY:

    1. Login to GemStone.
    2. Open a GemStone Application Manager by selecting manage gemstone applications from the Launcherís ENVY menu in VisualWorks or, in VisualAge, from the Smalltalk menu in the System Transcript.
    3. You must have an open edition of the GemStone application which will contain the updated code. Depending on the situation, you would create a new GemStone application, create a new edition of an existing GemStone application, or load one from the ENVY repository. If necessary, select this GemStone application and in the pop-up menu choose set as default.
    4. Select update envy in the pop-up menu to download from GemStone into ENVY.
    5. Watch the System Transcript for completion or for error information. Errors during download occur most often occur because prerequisite objects are not defined for an application. ENVY will refuse to bring across a class whose superclass isnít defined in one of the applicationís prerequisites. If you see this type of error, use the preLoadedCode method to load the prerequisites before loading the application.
    6. When the download has completed successfully, save the image.

Loading Configuration Maps and Updating GemStone

You can choose to update Gemstone after a configuration map is loaded by using the Configuration Maps Browser pop-up menu option load edition and gemstone.

To avoid complications, we recommend that you keep GemStone applications and client Smalltalk applications in separate configuration maps. As you load the configuration map, the GemStone classes in the map are updated in your current GemStone session.

Updating GemStone Subapplications and Extensions

GemStone does not have structures that correspond to the ENVY subapplication or extensions.

As mentioned earlier, the SCM toolkit maps GemStone applications in ENVY to SymbolDictionaries in the GemStone repository. If you view your GemStone classes from GemBuilder code browsers, you wonít see any objects that represent subapplications or extensions. Instead, you will find the ENVY subapplication and extension code stored within the SymbolList that corresponds to the containing GemStone application in ENVY. In other words, all classes and class extensions "roll up" to their "owning" application and are updated in the GemStone SymbolDictionary that is directly associated with that application.

When you make a change to a class extension in a subapplication, the SCM toolkit will automatically make the change in the GemStone repository, in the SymbolDictionary whose counterpart GemStone application holds the class definition. Likewise, if you make a change to a class that is defined in a subapplication, changes to that class are also reflected in the GemStone SymbolDictionary that is the counterpart for the ENVY application that contains the subapplications.

For example, if GS_Jonathon is a class defined in subapplication GS_Apple which is contained in GemStone application GS_Orchard, when you update a method in GS_Jonathon, that update will be reflected in the GemStone SymbolDictionary named Orchard. Similarly, if GS_Jonathon is a class extension in the GemStone application GS_Orchard2 and the class definition GS_Jonathon is contained in GemStone application GS_Orchard, when you update a method in the class extension under GS_MoreFruit, that update will be reflected in the GemStone SymbolDictionary named Orchard.

If you follow the recommended practice and make all your GemStone code changes through ENVY, your subapplications and class extensions will always be kept up to date in GemStone.

If you must do a batch update from GemStone to ENVY (for example, during the initial install of the SCM), note that the SCM toolkit will update methods in subapplication classes and class extensions correctly if the methods already exist in your ENVY image. If the method does not already exist in your image, the SCM toolkit will compile the new method into the current default GemStone application or subapplication (the current ENVY default application). If a class extension is required but does not yet exist, it will be created.

This specific functionality is useful for separating any methods your group may have added to the GemStone kernel classes, for example, during the initial install of the SCM toolkit. You can maintain all your GemStone kernel enhancements in class extensions in any application or subapplication separate from GS_Globals.

Updating Superclasses

If you structurally modify a GemStone class with subclasses in the ENVY development environment, and then update GemStone, the SCM toolkit :

Committing Code Changes to GemStone

Neither interactive changes nor batch updates perform a GemStone commit. It is the developerís responsibility to determine when it is appropriate to commit changes to GemStone. Performing a GemStone abort will erase from GemStone all changes made since the last commit. Batch updates can be used to re-synchronize the ENVY and GemStone repositories after an abort.

3.4 Reconciling "Forked" Development Paths

The standard ENVY development roles still apply when working with the SCM toolkit: GemStone projects can be partitioned into configuration maps, applications, and subapplications, and Managers can be assigned to control versioning and releasing of changes. Developers use the normal ENVY conventions and tools to reconcile forked development paths, then update the merged results into GemStone.

3.5 Setting Up Shared Method Implementations in Client Smalltalk and Gemstone

To share methods between client Smalltalk and GemStone Smalltalk, you must initially build both classes manually, then mark methods as shared using the change shared status menu pick in the Methods pane.

To have method changes propagated to the mirror class:

You can update a shared method or change the shared status of a method from any ENVY Class Browser or Method Browser, and you can update shared methods from either the client Smalltalk class or from the GemStone Smalltalk class in ENVY (for example, from Apple or from GS_Apple).

Method updates to methods marked as shared are always compiled to all three Smalltalk "spaces": client Smalltalk, GemStone Smalltalk in ENVY (the "GS_" class) and GemStone Smalltalk in the GemStone repository. If the class containing the shared method does not exist in all three spaces, and you make a change to a shared method, a prompter will inform you that the class does not exist. If the class exists in all three spaces but the method does not yet exist in the class in one or more spaces, you will be prompted to confirm that you want to create the method and make it shared.

If you try to set a method to shared and the implementation is different in one of the Smalltalk spaces, you will see a prompt asking whether you want to update the "mirrored" source as well. The SCM toolkit will not allow you to make a method shared unless you update the mirrored source.

Appendix AĖ

Table A.1 explains how the menus in the GemStone Application Manager differ from the ENVY Application Manager and how the new and altered menu functions work.

 

 

 

Table A.1 GemStone Application Manager Menu Options

Menu

Selection

Difference from ENVY

Operation

Application Pane Pop-up Menu

Available

Shows only applications with "GS_" prefix

Shows GemStone applications

 

find gemstone application

Replaces Find Application

Finds GemStone applications

 

Find Class

Finds only classes with "GS_" prefix.

Finds GemStone classes

 

browse gemstone application

Replaces Browse Application

Browses GemStone applications

 

create...

New submenu choices are gemstone applications or gemstone subapplications

Creates GemStone application or subapplication

 

update gemstone

New option

For selected applications, updates GemStone repository to match current ENVY version

 

update gemstone with prerequisites

New option

Updates GemStone, including all applications that the developer has sent to be ENVY prerequisites

 

update envy

New option

For selected applications, updates the currently loaded ENVY editions from the currenly open GemStone session

 

browse gemstone changes

New option

For selected applications, shows differences between GemStone methods in ENVY/Smalltalk image and GemStone repository

 

print gemstone changes

New option

For selected applications, prints selected differences between GemStone methods in ENVY/Smalltalk image and GemStone repository

 

print all gemstone changes

New option

Prints all differences between GemStone methods in ENVY/Smalltalk image and GemStone repository

 

compare with mirror

New option

Shows shared method implementation

 

Table A.1 GemStone Application Manager Menu Options (cont.)

Menu

Selection

Difference from ENVY

Operation

Class Pane Pop-up Menu

update gemstone

New option

For selected subapplications, updates GemStone repository to match current ENVY version

 

update envy

New option

For selected applications, updates the currently loaded ENVY editions from the currenly open GemStone session

 

browse gemstone changes

New option

For selected subapplications, shows differences between GemStone methods in ENVY/Smalltalk image and GemStone repository

Table A.2 explains SCM menu options added to other ENVY and client Smalltalk tools.

 

Table A.2 Other SCM Menu Options

Tool

Menu

Option

Operation

VisualWorks or VisualAge System Transcript

ENVY drop-down menu

manage gemstone application

Opens a GemStone Application Manager

Configuration Maps Browser

Editions pop-up menu

load edition and gemstone

Loads components from the ENVY repository into the ENVY/Smalltalk image and updates GemStone

 

Applications pop-up menu

load edition and gemstone

Loads components from the ENVY repository into the ENVY/Smalltalk image and updates GemStone

Class Browser

Class pop-up menu

update gemstone

For selected classes, updates GemStone repository to match current ENVY version

 

 

update envy

For selected applications, updates the currently loaded ENVY editions from the currenly open GemStone session

 

 

spawn GS browser

Opens a GemStone (GemBuilder) Browser

 

Methods pop-up menu

update gemstone

For selected methods, updates GemStone repository to match current ENVY version

 

 

update envy

For selected applications, updates the currently loaded ENVY editions from the currenly open GemStone session

Application Browser, Applications Browser, Class Hierarchy Browser

Class pop-up menu

(if a GemStone class is selected)

update gemstone

For selected classes, updates GemStone repository to match current ENVY version

 

 

update envy

For selected applications, updates the currently loaded ENVY editions from the currenly open GemStone session

 

 

spawn GS browser

Opens a GemStone (GemBuilder) Browser

 

Methods pop-up menu (if a GemStone class is selected)

update gemstone

For selected methods, updates GemStone repository to match current ENVY version

 

 

update envy

For selected applications, updates the currently loaded ENVY editions from the currenly open GemStone session

Appendix AĖ

Subclasses of Parser (GbcParser) and Compiler (GbcCompiler) are used to compile GemStone Smalltalk into ENVY CompiledMethod representation.

Minimal changes were made to Behavior, Class, ClassDescription, EtBrowser (and its subclasses), Metaclass, String, and SubApplication.

GbcDefinition is a subclass of MessageSend used to store the information necessary to create GemStone class representations in ENVY, and compare class definitions between GemStone and ENVY.

GbcUpLoader controls the movement of classes and methods from ENVY into GemStone.

GbcDownLoader controls the movement of classes and methods from GemStone into ENVY.

GbcHierarchyRoot has no superclass and is the root of all GemStone classes in ENVY.

GbcSubApplication is a subclass of SubApplication. Its instances may contain other GemStone subapplications or classes.

GbcApplication is a subclass of Application, whose instances contain GbcSubApplications and or classes.

GbcApplicationManager is a subclass of ApplicationManager, whose instances (GemStone Application Manager browsers) display and manage only instances of GbcApplication and GbcSubApplication.

 

 

 

 

 

 

Chapter 1: Gemkit for source code management

1.1 introducing the SCM Toolkit

1.2 Developing GemStone Smalltalk Code in ENVY

SCM Toolkit Architecture

Class Mapping: Client Smalltalk to GemStone Smalltalk

Code Management for Multi-User Smalltalk

Shared Method Implementation

Basic Development Cycle

1.3 ENVY SCM Tools

GemStone Application Manager

GemStone Changes Browser

GemStone Comparison Browser

Other Tools

chapter 2: strategies for team development

2.1 Planning a Development Strategy

2.2 Using Multiple GemStone Namespaces

2.3 Developing with Shared SymbolLists

2.4 Symbol Resolution in GemStone

2.5 Configuring and Using Development, Test, and Production Repositories

Configuring the GemStone Development Environment

Option 1: Separate GemStone Repositories (>6 developers)

Option 2 : One GemStone Environment for All Developers (< 15 developers)

Option 3 : One GemStone Development Environment Per Subsystem (complex projects)

Working in the Test Repository

The Production Repository

2.6 Managing Security

chapter 3: code management procedures

3.1 Creating GemStone Applications and Classes

Creating New GemStone Smalltalk Applications and Classes

Creating GemStone Applications in ENVY From Existing GemStone Code

3.2 Initializing Global Definitions and Data

3.3 Synchronizing Code Changes

Compiling All Changes in GemStone Smalltalk and ENVY/Smalltalk

Batch Update Mechanism

Loading Configuration Maps and Updating GemStone

Updating GemStone Subapplications and Extensions

Updating Superclasses

Committing Code Changes to GemStone

3.4 Reconciling "Forked" Development Paths

3.5 Setting Up Shared Method Implementations in Client Smalltalk and Gemstone

Appendix A: SCM Tools

Appendix B: Implementation Notes