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:

This document uses the following typographical conventions:

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

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.

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.

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.

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.

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 :

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.

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.

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.

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.

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.

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.

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

The basic development process is illustrated in Figure 1.3:

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.

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.

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

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

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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:

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.

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.

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

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.

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

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:

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:

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.

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:

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.

To load modifications from ENVY into GemStone:

To load modifications from the GemStone repository into ENVY:

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.

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.

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

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.

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.

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.

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.2 explains SCM menu options added to other ENVY and client Smalltalk tools.

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.