TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Configuration Management

Apex supports configuration management by:

This chapter provides an overview of the configuration manager Summit/CM.

About this Chapter

This chapter covers the following topics:


Summit/CM Overview

The Rational Summit/CM system supports:

For more details on Summit/CM, please see the Concepts Guide.

The Check-In and Check-Out System

Apex divides programming efforts into subsystems to make them more manageable. A specific version of a subsystem is called a view. A view contains the files that represent the logical objects in a subsystem. Every Rational subsystem contains at least one view. Because views contain actual files, they are directories in which compilation is performed.

Summit/CM is a system for controlling modifications made to individual objects in a subsystem. Objects under the control of Summit/CM can be checked out and checked in, much like books in a library.


Controlled and Uncontrolled Objects

Objects in views must be explicitly placed under Summit/CM control for Apex to track changes in them and control access to them. Only objects in views can be placed under Summit/CM control. Also, there are some files that cannot be placed under Summit/CM control. The VC_FILE_EXCLUSIONS switch controls whether an object can be placed under Summit/CM control. You set this switch to prevent files from being placed under Summit/CM control when they should not be.

To find out if an object is controlled, select the object in a directory-viewer window and choose the View > Format > CM Attributes menu item. Summit/CM information then appears beside the object's name in the directory viewer. You may have to scroll the window horizontally to see all the information.

To place an object under Summit/CM control, select the line listing the object in a directory-viewer window and choose the Control > Object Properties menu item. Apex displays the Object Properties dialog box which is illustrated in Figure 1.

Figure 1 Object Properties Dialog Box

The Object Properties dialog box shows the current properties of the object and lets you change those properties. If the Current Property Values text field shows that the object is uncontrolled, you can make the object controlled by checking the Controlled check box in the New Property Values area and then clicking OK or Apply.

To make several objects controlled in a single operation, you can use the Control > Change Object Properties dialog box. (Choose the Control > Change Subsystem Properties menu item to create a new version history family in multiple subsystems.)

For more information about placing an object under Summit/CM control, see The Check-In and Check-Out System and Checking Objects In and Out.

Objects in a Subsystem and Views

An Apex development effort is always divided into one or more subsystems. For information about dividing systems into subsystems, see the Concepts Guide.

In a software-development effort, the individual files that contain source code, documents, specifications, design notes, test data, and other information used during development are referred to as objects in subsystems. All work on the objects in a subsystem is performed in views of the subsystem that contain files corresponding to the object. In a view, the name of an object is the view-relative pathname of the file that corresponds to the object.

For example, suppose the following subsystem is part of a software-development effort:

/projects/compiler.ss

Assume that this subsystem contains two views:

/projects/compiler.ss/dev.wrk  /projects/compiler.ss/test.wrk

Also assume that each view contains the following files, which are under Summit/CM control.

Ada:

/projects/compiler.ss/dev.wrk  /projects/compiler.ss/dev.wrk/requirements  
/projects/compiler.ss/dev.wrk/scanner.1.ada 
/projects/compiler.ss/dev.wrk/scanner.2.ada 
/projects/compiler.ss/test.wrk  /projects/compiler.ss/test.wrk/requirements  
/projects/compiler.ss/test.wrk/scanner.1.ada  
/projects/compiler.ss/test.wrk/scanner.2.ada /projects/compiler.ss/test.wrk/test_data

C/C++:

/projects/compiler.ss/dev.wrk  /projects/compiler.ss/dev.wrk/requirements  
/projects/compiler.ss/dev.wrk/scanner.h 
/projects/compiler.ss/dev.wrk/scanner.C 
/projects/compiler.ss/test.wrk  /projects/compiler.ss/test.wrk/requirements  
/projects/compiler.ss/test.wrk/scanner.h  
/projects/compiler.ss/test.wrk/scanner.C  /projects/compiler.ss/test.wrk/test_data

For Ada, there are four Summit/CM-controlled objects in the subsystem shown above: requirements, scanner.1.ada, scanner.2.ada, and test_data. For C/C++, the Summit/CM-controlled objects are: requirements, scanner.C, scanner.C, and test_data. Every object of a subsystem does not need to be in each view of the subsystem (a view is a subset of the objects in the subsystem.)

If there are subdirectories in a view, the name of each subdirectory is included in the object name of any objects in that subdirectory.

Propagation of Changes Between Views

Consider the two files named requirements in the preceding example of a subsystem. There is one file named requirements in the dev.wrk view, and there is another file named requirements in the test.wrk view. Each requirements file corresponds to the same Summit/CM object. However, the two files named requirements might be different versions of the same object. When a subsystem contains more than one view, as in the preceding example, files representing the same object in different views can have different contents because they represent different versions of the object.

For example, suppose a developer creates new versions of several files in a view by checking out the files. When the changes are complete, the developer checks the files back in. It is then possible to copy each changed file to a different view by executing the Control > Update Objects command. When Control > Update Objects is invoked to update a controlled file from one view into the corresponding element in another view, the destination file is changed to match the source file. After a Control > Update Objects command is executed, the files in the source and destination views are the same in content and version number.

To illustrate how this works, suppose that in the preceding example, a developer creates new versions of several files in dev.wrk by checking out the files, updating and testing the files, and checking the files in. The developer can then move the changed files individually to the test.wrk view by executing Control > Update Objects. Control > Update Objects changes the files in the destination view (test.wrk) to match the changed files in source (dev.wrk) view.

Control > Update Views propagates all the changes from one view to another. The Control > Update commands automatically change out-of-date versions in a destination view to newer versions.

The examples in this section assume that all objects are in the same version history family. For more information about version history families, see the next section.


The Summit/CM Database

When you place a file under version control, Apex starts tracking the file's development in a special database called the Summit/CM database.

Version History

When files are checked out, modified, and checked in repeatedly, the result is a time-ordered, numbered sequence of versions, called a version history.

For example, object A in Figure 2 has three versions, each one containing an image of the file as it appeared at the time it was checked in.

Figure 2 Version Histories

Version History Families

A version history family is a set of version histories. A version history family includes at most one version history for each file in the subsystem. A version history family composed of the version histories of three files is illustrated in Figure 3. Version history families can be used to group together version histories that are related in some way. Each file under Summit/CM control is a member of a named version history family. Version history families are properties of subsystems.

Figure 3 Version History Family

Each object under Summit/CM control is a member of a named version history family. Version history families are properties of subsystems.

Creating a Version History Family

To create a version history family, follow these steps:

1 . Select a subsystem in a directory-viewer window.

2 . Choose the Control > Subsystem Properties menu item.

Apex displays the Subsystem Properties dialog box showing the current existing version history families of the subsystem you have selected as illustrated in Figure 4.

Figure 4 Subsystem Properties Dialog Box

3 . To create a new version history family, enter its name in the Add text field and click the Add button.

4 . Click OK or Apply to create the new history.

There is another way to create a version history family for a subsystem:

1 . Execute the File > New > New History command.

Apex opens the New History dialog box illustrated in Figure 5.

Figure 5 New History Dialog Box

2 . To create a new version history family for the files in a subsystem, enter the name of the subsystem and a name for the version history family you want to create.

3 . Click OK or Apply to create your version history family.

Use the Control > Change Subsystem Properties menu item to create a new version history family in multiple subsystems.

Setting the Version History of an Object

To set the version history of an object when the object is first placed under Summit/CM control, follow these steps:

1 . Choose the Control > Object Properties menu item.

Apex displays the Object Properties dialog box.

2 . When the Object Properties dialog box appears as illustrated in Figure 6, enter the name of the history in the History field next to the Controlled check box.

Figure 6 Object Properties Dialog Box with New Property Values

3 . Click OK or Apply.

Changing the Version History of an Object

To change the version history of an existing controlled object:

1 . Select the object in a directory-viewer window.

2 . Choose the Control > Object Properties menu item.

Apex displays the Object Properties dialog box shown earlier in this chapter. The Object Properties dialog box shows the current properties of the object, including its version history.

3 . Enter the name of the desired new version history in the Object Name text field.

A new set of options appears in the New property values panel, as shown in Figure 6.

Figure 7 Object Properties Dialog Box

You can use the new options shown in the New Property Values panel to reconcile cases in which current object contents do not match the latest version in the new version history. This kind of match is required to set the history and version number for the object. You can reconcile an object with the latest version of a new version history by:

4 . When you have selected the options you want, click OK or Apply.


Storing Notes About a Version

User-supplied notes about a version can be permanently stored in the Summit/CM database. You can enter such notes at any time. Once entered, a note becomes a permanent addition to the version of the specified object.

Notes can contain any kind of textual information. You can define a structure for the text contained in notes and write tools that process the text to generate release notes, test information, or other kinds of reports.

You can incorporate notes into version history by choosing the Control > Check In, Control > Check Out, or the Control > Add Notes menu item. The Control > Check In and Control > Check Out dialog boxes contain fields for adding notes during check in and check out. The Control > Add Notes dialog box lets you add notes at any time.

To display the notes for a specific version or group of versions of an object under Summit/CM control, choose the Control > Show > Notes command.


Checking Objects In and Out

When an object is controlled, you must check it out before you can modify it. When you have checked out a controlled object, you can edit it in any way you like, but all other users are locked out. They cannot modify the object until you have checked it in again.

When you check in a controlled object, it is unlocked and is again available to other users, provided they have the necessary UNIX user privileges to check it out.

Figure 8 illustrates the process of checking an object out and checking it back.

Figure 8 Check Out and Check In Process

Checking Out an Object

When you first place an object under Summit/CM control, it is not modifiable (although you can use controlled, unmodifiable objects to compile programs). To make a controlled object modifiable, you must check it out by executing the Control > Check Out command.

Checking out an object from the Summit/CM database has these effects:

Note: Apex implements the "check out to place" model, not the "check out to person" model. That is, when a file is checked out in a view, it cannot be edited or checked out in another view (except via a private check out). However, it can be edited and checked back in by any user who has write privileges in the original view (that is, the user checking it back in does not have to be the user who originally checked it out).

When you have checked out a object, you can make changes to it (including compiling, linking, and debugging), save it, and make more changes. None of these changes is reflected by the Summit/CM database until you check the object in.

To check out an object in a view, you can do one of the following:

Figure 9 Check Out Dialog Box

When the Check Out dialog box appears, you check out one or more objects by placing their names in the Objects to Check Out scroll box and clicking the OK or Apply. For information on using scroll boxes, see Using and Customizing the GUI. To learn about the options offered in the Check Out dialog box, see the Control > Check Out entry in the Online Reference.

Once an object is successfully checked out, you can edit it in the normal manner using the Apex editor or any other UNIX editor.

Only the latest, highest-numbered version can be checked out. Checking the object out creates a new version with the next higher number and this is the version that can be changed. If an object is already checked out in another view, it cannot be checked out. If an object is not at its latest version, it cannot be checked out using default options. These cases are considered in the next sections.


When You Do Not Have the Latest Object

Suppose you are checking out the object /projects/avionics/navigation/math_library.ss/rev.1.wrk/trig_functions.2.ada and the version in your view is 12 and the latest version is 14. The check out will fail with a message indicating that you do not have the latest version.

There are several alternatives you can pursue:


When the Object Is Checked-Out Elsewhere

When a check-out operation fails because the unit (Ada) or file (C/C++) is checked out in another view, you have several options.

To find out the state of a unit (Ada) or file (C/C++), select the unit (Ada) or file (C/C++) in a directory- viewer window and choose View > Format > CM Attributes. This displays the Summit/CM information in the viewer on the same line with the unit (Ada) or file (C/C++) name. You may need to scroll the display to the right to see the user who has the unit (Ada) or file (C/C++)checked out.

Checking In an Object

To check an object in, you execute the Control > Check In command. Checking an object in has these effects:

Each time you check out, modify, and check in an object, you add a new version of the object to the Summit/CM database. This sequence of versions is called a version history.

To check an object in:

Figure 10 Check In Dialog Box


Corresponding Objects

A subsystem usually contains at least one working view. A working view is a view in which objects can be checked out, modified, checked in, compiled, and tested. At any given time, each working view contains at most one version of each object.

Objects are said to be corresponding if they exist in different views of the same subsystem and have the same view-relative name. Corresponding objects may or may not share the same version history.

When corresponding objects have the same version history, an object can be checked out for editing in only one view at any given time. If an object is checked out in one view, the corresponding object in another view cannot be checked out until the object in the first view is checked in.

Even after you have checked in an object, corresponding objects in other views are not affected by changes you have made in the object until you explicitly accept changes from the first view. You can accept changes by opening the Control > Check Out dialog box and checking the radio button labeled Accept latest version of each object.

When corresponding objects do not share the same version history, they can be checked out in different views at the same time, and changes made in one view never affect other views.


Views

To support various development methodologies, including an iterative approach to building releases, Apex provides three kinds of release views. Listed in order from least restrictive to most restrictive, the three kings of release views are:

Release views are usually created as copies of existing views —— either working or release views. All release views have the extension .rel, distinguishing them from working views, which have the extension .wrk. To create a release view that is a copy of an existing view, execute the File > Copy command.

You can specify or change the type of release view by following either of these procedures:

Figure 11 Change View Properties Dialog Box


Placing Files Created Outside of Apex Under Configuration Control

If an object was created in another way and needs to be placed under Summit/CM control, follow these steps. For this example, assume the object trig_functions.2.ada in the view

/projects/avionics/navigation/math_library.ss/rev.1.wrk

was created with another editor such as emacs and you want to place it under Summit/CM control. This operation is usually run from a directory-viewer window on the view.

1 . Select trig_functions.2.ada in the directory viewer. (If the object has been created but does not appear in the viewer, choose File > Redisplay.)

2 . Choose Control > Object Properties to open an Object Properties dialog box.

The Object Properties dialog box should show the object name:

/projects/avionics/navigation/math_library.ss/rev.1.wrk/trig_functions.2.ada

If it doesn't, enter that object name and click Reset. Current object properties should say "Uncontrolled."

3 . Click on the Controlled check box.

Some options may appear at this point.

4 . Click OK or Apply to place the object under Summit/CM control.

There maybe a number of objects to place under Summit/CM control. This could happen if many objects were created without placing them under control at the time of creation. You could use the above steps for each object, or alternatively follow the steps below to place many objects under Summit/CM control in a single operation:

1 . Choose Control > Change Object Properties to bring up a Change Object Properties dialog box.

2 . Enter the names of all of the objects to control.

An easy way to do this is:

a . Click on the Navigator Icon to bring up a File Selection dialog box for the Objects list field.

b . In the selection dialog, change the filter so that only the Uncontrolled check box is set.

c . Click Filter to apply the new filter.

Now only objects not under Summit/CM control appear. You can select them all, or only those that you actually want to control.

d . Click OK in the selection dialog.

e . This transfers all of the selected objects into the Objects list.

3 . Click the Place Under CM Control button.

Click OK or Apply to place the objects under Summit/CM control.


Merging Changes

Suppose you have the following situation, in the working view, /projects/avionics/navigation/math_library.ss/rev.1.wrk, is an Ada unit, trig_functions.2.ada at version 3 and it is checked out. In another view of the same subsystem, rev.1.phil.wrk, trig_functions.2.ada is at version 2 and the developer Phil wishes to edit it. Upon attempting to check it out, Phil is informed that the object is unavailable:

Since Phil wants to proceed, he can check it out privately: After selecting trig_functions.2.ada in a directory viewer, he chooses Control > Check Out. In the resulting Check Out dialog box, he checks the Private Check-out check box. This results in an editable version in rev.1.phil.wrk.

Phil then makes his changes and waits for the unit to be checked-in. When the version in rev.1.wrk is checked in, Phil can perform a merge operation to add his changes to the latest version by following these steps:

1 . In the rev.1.phil.wrk view, select trig_functions.2.ada in a directory-viewer window.

2 . Choose Control > Merge.

3 . The Merge dialog box, illustrated in Figure 12, is displayed. The fields are automatically filled in so that the current version of trig_functions.2.ada (the one that is privately checked out) will be merged with the latest version, and a new object is created. An editor window is brought up on the merged object so that any conflicts can be dealt with. To copy the merge result onto the privately checked out object if the displayed merge object is satisfactory, choose File > Save and then the Merge > Copy Onto File 1 menu item to copy the merge result onto the privately checked out object.

Figure 12 Merge Dialog Box

4 . To make the merged result the latest version choose Control > Check Out in the resulting Check Out dialog box.

5 . Set the options Upgrade private check-out to full and Keep the current version of each object.

This results in a new latest version that is checked-out and has contents that are the result of the merge.

You can check in the object now or make other changes if desired before checking it in.

Important Note About Merge and Private Check Out

Because privately checked-out objects do not have their own version number, it is important that any merge operation involving a privately checked-out object name the privately checked-out object explicitly. This happens in the above example because the merge is done from the view where the object is privately checked out. If the merge were done from the rev.1.wrk view, for example, Object #1 would have to be changed to name explicitly the view rev.1.phil.wrk because there is no version number that can be used to reference the privately checked-out object from a Summit/CM element name in rev.1.wrk.

Explicit version numbers can be used in the Version field, but again, an explicit version number cannot be used to reference a privately checked-out object.


Deleting Objects

At some point in the development process, an object may become obsolete and need to be deleted. There are two ways to delete an Ada unit or a C/C++ file:

The latter is usually preferred because the existence of the "deleted version" is something that can be propagated to other views as easily as other kinds of changes to existing objects.

To create a deleted version of an Ada unit or a C/C++ file, you do not check the an Ada unit or a C/C++ file out as you would for other kinds of changes. Instead follow these steps:

1 . Select the Ada unit(s) or a C/C++ file(s) to be deleted in the directory viewer.

You may want to verify that they are controlled objects before deleting them. If they are not controlled, the act of deleting them will simply remove the UNIX files, and Apex does not provide any facility for recovery.

2 . After the objects are selected, choose View > Format:CM Attributes. The word Uncontrolled appears next to objects that are not under Apex control; the history name and current version information will appear next to objects that are under Apex control to check if the objects are controlled.

3 . Choose File > Delete Object.

4 . Click OK in the resulting Delete Objects dialog box.

The object will be removed from the view, and a deleted version added to the history of the object. If changes are propagated from this view to another, the object will be deleted in the other view. The version history of the object is retained, and any version can be recovered at any time.

Recovering a Deleted Object

To recover a deleted object, use the following steps. Recover a deleted object means to "set the version in the current view to a version that is not deleted." As part of recovering a deleted object, you can optionally create a new, latest version from the last existent version.

1 . From a directory viewer on the view that does not contain a file for the desired object, click on Control > Recover.

2 . In the resulting Recover dialog box, enter the name of the object to recover in the text entry area for the list field and click Add.

If you do not know the exact name of the object (quite likely since it is not there), click on the Navigator Icon of the Add field to bring up a file selection dialog box. This file selection dialog will list the deleted versions relevant for this view.

3 . Click OK or Apply to change the version to an existing one, recreating the file in the view.

Deleting Controlled Files

No matter how you use Apex to delete a controlled file, the file is never removed permanently from the Summit/CM database. There will always be a way to retrieve it. To delete a file, always use File > Delete Object. There are two options for deleting controlled files, each has distinctly different effects:

1 . When the Delete from view only option in the Delete Object dialog box is selected, the file is deleted only from the view where the operation is performed. Any other views will not be affected by this operation. To recover this file into the view from another view, simply run Control > Update Objects with the selected option ... and add new objects from the current histories. To recover this file into the view, without using a source view or file, create an empty file with the same name and run Control > Change Object Properties with place under cmvc control and accept from latest version.

2 . By selecting the Create `Deleted Version' in version history option (default option), the file is removed from the view as it was in the previous case and also a `deleted' mark is attached to the file in the version history of the file. For Apex, this means the file has been deleted. In effect no other view can make changes to the file (for example, check out). Running the Control > Update Objects function in the other views will remove the file from the views. But still it is possible to recover the file by running the Control > Recover function that simply removes the `deleted' mark from the version history.

For Apex 3.0.0b, the second option is named Delete in version history instead of Create `Deleted Version' in version history.

For Apex.2.4.6 or older, the name of the first option is Make objects uncontrolled and the second option is default. By selecting the first option, the second option is deselected.

Deleting Normal Uncontrolled Objects

File > Delete Object can also be used to delete objects that are not under Apex control. Simply use the Delete Object dialog box as described above.

If you want to remove a controlled object from a view without creating a deleted version of the object, follow these steps. (This might be done if controlled objects are erroneously accepted into a view during a Control > Update Views operation, for example.)

1 . Select the objects to be deleted in a directory-viewer window. Choose File > Delete Object.

2 . The resulting Delete Object dialog box is displayed. Check the Make Objects Uncontrolled check box.

3 . Click OK or Apply to delete the objects.

This will remove the objects from Apex control and then delete the UNIX file.


Making an Uncontrolled Object Controlled

Sometimes new objects are created and not placed immediately under Summit/CM control. To have changes automatically propagated between views by Control > Update Objects and Control > Update Views, the objects must be under Summit/CM control.

Sometimes an object is initially uncontrolled. The object may be manually copied to different views and be uncontrolled in each. Later, the decision may be made to place the object under Summit/CM control. This section describes how to sort out the problems and accomplish this task.

To initially place one copy of the object under Summit/CM control in one view, follow these steps:

1 . Select the object in a directory-viewer window.

2 . Choose Control > Object Properties.

3 . In the resulting Object Properties dialog box, check the Controlled check box.

4 . Click OK or Apply to place the object under Summit/CM control.

When the Controlled check box is checked, several other options appear. These will be used in other steps.

Now, the first object is under Summit/CM control, but there are uncontrolled copies in other views. Each of these must also be placed under Summit/CM control. To set each under control to the same version as the first, the contents must be identical (otherwise they are different values trying to be the same version of an object).

In each other view, repeat the above steps. If the file in that view has a different value from the first, then the attempt to place the object under control will fail. You have two alternatives:

If different versions are created, then you will have to resolve, perhaps using Control > Merge (see Merging Changes), the differences and eventually update all of the views so that they have the new, latest version.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS