TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Customizing Summit/CM

Customization of Summit/CM operations is accomplished through property files and sets of executables and scripts. The property files contain a description of certain customization characteristics such as the host architecture. The executables and scripts provide code called by Summit/CM at specific points in its execution either to implement or augment basic Summit/CM functionality.

There are two kinds of customization:


Customization Keys

The customizations to be used are specified by customization keys. Customization keys are switches that name directories containing the property files and executables/scripts that implement the customizations.

Corresponding to the two types of customizations are two customization key switches:

When a customization key is set, Summit/CM looks in the specified directory to find the required executables and scripts. If an executable/script is not provided as part of the customization, the operation is ignored. If a customization operation exists, it is executed and the exit status is used to determine whether the operation was successful (status equal to "0") or unsuccessful (status not equal to "0"). Output emitted by the customization (either through standard output or standard error) is captured and echoed by Summit/CM.

When customization keys are not set, the basic uncustomized Summit/CM operations are executed. Because some commands, such as analyze, are fundamentally dependent on customization, Summit/CM emits an error if there is no active customization when these commands are executed.


Compiler Customization

Setting the compiler key determines how compilation and related operations are performed within a view. It is not necessary to have the compiler key set in a view. However, when the compiler key is not set, the view cannot be used to compile program units.

The following sections describe the operations called by Summit/CM using the compiler key.

The first parameter to each customization is the revision of the compiler customization interface. This parameter is called rev. The interface revision number takes this form:

The major_number is incremented for incompatible changes to the interface. The minor_number is incremented for upward compatible changes to the interface.

This document defines revision 1.1 of the compiler customization interface.

post_create_view

Syntax
Description

Called after a view has been created either as a new empty view or as a copy of an existing view. This operation provides a point at which to initialize the compilation state of the view. When this call is made, all compiler-independent objects (such as import-related objects) have been created within the view. The call is made based on the compiler key of the new view.

Parameters

Keep in mind that user-level operations such as creation or copy of a working view are complex operations that can involve multiple calls to customization operations. For example, after creating a new view, the imports are always analyzed, which will cause the post_import operation to be called.

Listed below is the sequence of operations and customization calls that make up the user-level view for create and copy operations:

post_create_directory

Syntax
Description

Called after a directory has been created. For example, use this to create makefiles in the directory.

Parameters

post_create_unit

Syntax
Description

Called after a program unit has been created in a view or copied into a view. For example, use this call to update a makefile that contains an object file target for each source unit in the view.

Parameters

pre_delete_view

Syntax
Description

Called prior to deleting the view. At this point, all compiler-independent checks have been made (for example, the view has been analyzed for checked-out objects).

Parameters

post_delete_view

Syntax
Description

Called after the view has been deleted.

Parameters

pre_freeze_view

Syntax
Description

Called prior to changing the permissions on a frozen release view.

Parameters

post_delete_unit

Syntax
Description

Called after a unit has been deleted. Not called if the containing view was deleted at the same time.

Parameters

check_imports

Syntax
Description

Called as part of an import operation to determine whether the views can be imported. Normally, the compiler checks the compatibility of the compiler keys for all the views.

Parameters
Diagnostic File Format

Currently, any lines put into the diagnostic file are emitted by Summit/CM.

post_import

Syntax
Description

Called as the final stage of importing. At this point, all compiler-independent importing computations have been performed and all compiler-dependent compatibility checks have been made.

This operation is called as a result of the import and remove_import commands.

Parameters

To put the import related operations in context, the following bullets summarize the import process:

post_create_export_set

Syntax
Description

Called when a new export set has been created.

Parameters

post_delete_export_set

Syntax
Description

Called when an export set has been deleted.

Parameters

post_export

Syntax
Description

Called when new units are exported from the named view. This is used when some set of new exports is added to the current exports. For example, this is used by the C++ compiler to create symbolic links to the exported units.

Parameters

post_main_program

Syntax
Description

The listed main units are registered. Summit/CM independently stores a file of main programs. When you add or remove a main program, the entire contents of the file are passed to the customization. For example, the C++ compiler uses this to manage main program targets in the makefile.

Parameters

set_key

Syntax
Description

Called when the compiler key of an existing view is changed to this value.

For example, a compiler might use this information to decide that the units in the view must be recompiled if the new compiler is incompatible with the old compiler.

This operation is also called when the model of a view is changed.

Parameters

unset_key

Syntax
Description

Called when the compiler key of an existing view is changed from this value. This operation always precedes set_key.

Parameters

parse

Syntax
Description

Performs syntactic analysis on the units in the designated view.

Must be provided to run apex parse.

Parameters

analyze

Syntax
Description

Performs semantic analysis on the units in the designated view.

Must be provided to run apex analyze.

Parameters

code

Syntax
Description

Codes the units in the designated view.

Must be provided to run apex code.

Parameters

link

Syntax
Description

Links the designated programs in the view. If no units are given, all appropriate units are linked.

Must be provided in order to run apex link.

Parameters

clean

Syntax
Description

Removes compilation artifacts as necessary to reduce the units to the goal state specified in the options.

Must be provided to run apex clean.

Parameters

migrate

Syntax
Description

Parses the named files into the view. If no files are given, all appropriate files in the view will be parsed.

Must be provided to run apex migrate.

Parameters

pretty_print

Syntax
Description

Pretty prints the designated units. If units are not provided, all units in the view are pretty printed.

Must be provided to run apex pretty_print.

Parameters

dependencies

Syntax
Description

Updates any necessary dependency information in the view.

Must be provided to run apex dependencies.

Parameters

maintain

Syntax
Description

Performs maintenance on the compiler state.

Parameters


Compiler Customization Properties File

Use the compiler customization properties file to specify characteristics of the customization. These characteristics are used by Summit/CM when invoking the customization and when managing the attribute objects generated by the customization.

The description file is read at the time the compiler key is initialized in the view (for example, when the view is created or remodeled), and the values are cached in the view. Running the remodel -refresh command causes the properties file to be reread.

The name of the file is Compiler_Properties; it is found in the directory containing the other executables and scripts that are part of the customization.

You must set each switch to a legal value in the customization properties file.

The following switches are defined in the properties file:

Compiler Customization Classes

Associated with each compiler customization is a compiler customization class, which defines some basic characteristics of the customization. For example, the class defines the customization operations that are applicable to the customization. The different compiler customization classes are defined below:


Version Control Customization

You can also customize Summit/CM version control operations through the "pre" and "post" processing operations described in this section.

Use the "pre" operations to determine whether an operation is allowed. If a "pre" operation returns an unsuccessful status, the associated Summit/CM operation will not be performed. Use the "post" operation to finish the associated Summit/CM operation. For example, customize check_out by having pre_check_out check the authorization of the user performing the check_out, and having post_check_out register the fact in a log.

The general sequence of operations is:

The VERSION_CONTROL_KEY and APEX_CMVC_KEY switches may contain a sequence of customization pathnames of the form:

When the switches specify a sequence of pathnames, the appropriate "pre" and "post" operations are executed in each of the specified customizations. The "pre" operations are executed in the order specified by the sequence, and the "post" operations are executed in the reverse order. All the "pre" operations must return a successful status for the operation to proceed. If a "pre" or "post" operation returns an unsuccessful status, no further "pre" or "post" operations are executed.

Prior to calling a customization operation the environment variable APEX_COMMAND_NAME is set to the name of the original command for which the customization operation is being invoked.

The first parameter to each customization operation is called rev, which represents the revision number of the customization interface. The interface revision number is of the form:

The major_number is incremented for incompatible changes to the interface. The minor_number is incremented for upward compatible changes to the interface.

This document defines revision 1.1 of the version control customization interface.

Customization Using Apex_Shell Actions

Version control customization may also be accomplished by using apex_shell actions. Apex_Shell is a scripting facility which provides direct and efficient access to Apex data structures. It is described in detail in the Scripting LanguageReference.

Apex_shell actions for version control customization are specified in an actions file, named cmvc.actions, which can be placed in any one of the following locations:

If cmvc.actions files are found in more then one location, all actions will be applied. In addition, the customization actions found in the cmvc.actions files will be applied in addition to any other scripts (for example, pre_check_out) found in the directories named by the VERSION_CONTROL_KEY or APEX_CMVC_KEY switches.

A cmvc.actions file contains a sequence of apex_shell actions whose names match those of the version control customization operations. For example, acmvc.actions file might contain pre_check_out and post_check_out actions. In addition the cmvc.actions file may also contain the definitions of addition apex_shell functions which are called from the actions.

An apex_shell action has the following format:

where <action-name> is just the name of the action (for example, pre_check_out), and <object-filter> is a naming expression which is used to filter the objects which the operation will be applied to.

For example, an action which would be called for each check-out of a C source file would look like:

The apex shell actions for version control customization are passed the same parameters as any other scripts which are used for version control customization.

pre_control

Syntax
Description

Called prior to placing an uncontrolled object under version control.

When a new version is created as part of the control command the pre/post_create_version customization calls are also made. In fact, execution of the control command would execute the following sequence of actions and customization calls when the control command involves creation of a new version:

Parameters

post_control

Syntax
Description

Called after the file has been made controlled.

Parameters

pre_accept_control

Syntax
Description

Called prior to accepting new controlled object into a view. The trigger is invoked whenever the accept_changes command causes a new controlled object to be created. This may happen when a new file is being created or an existing uncontrolled file is being controlled during accept_changes.

Parameters

post_accept_control

Syntax
Description

Called after a new file has been controlled by accept_changes.

Parameters

pre_uncontrol

Syntax
Description

Called prior to making a file uncontrolled.

Parameters

post_uncontrol

Syntax
Description

Called after a file has been made uncontrolled.

Parameters

pre_check_out

Syntax
Description

Called prior to check_out of a controlled file.

Parameters

post_check_out

Syntax
Description

Called after check_out of the file.

Parameters

pre_private_check_out

Syntax
Description

Called prior to "private" check_out of a controlled file.

Parameters

post_private_check_out

Syntax
Description

Called after a private check_out of the file.

Parameters

pre_upgrade_check_out

Syntax
Description

Called prior to check_out of a controlled file when the check out is upgraded from private to a check out with reservation.

Parameters

post_upgrade_check_out

Syntax
Description

Called after check_out of the file.

Parameters

pre_check_in

Syntax
Description

Called when a checked out file is checked in.

Parameters

post_check_in

Syntax
Description

Called after a new version has been created.

Parameters

pre_abandon

Syntax
Description

Called prior to abandoning the check out of an object.

Parameters

post_abandon

Syntax
Description

Called after check out has been abandoned.

Parameters

pre_create_version

Syntax
Description

Called when a new version is created for some reason other than check-out/check-in. For example, this is called when a new version is created because of the -create option on the control command.

Parameters

post_create_version

Syntax
Description

Called after a new version has been created.

Parameters

pre_set_version

Syntax
Description

Called prior to changing the version of a controlled file. This is called when Summit/CM commands accept_changes, set_version, or recover are executed. It is also called when the version of an object is updated prior to checking out an object.

It is not called when a checked-out object has its version changed while it is still in the checked-out state.

Parameters

post_set_version

Syntax
Description

Called after the version of a controlled file has been changed.

Parameters

pre_set_history

Syntax
Description

Called prior to changing the history of a controlled file.

Parameters

post_set_history

Syntax
Description

Called after the history of a controlled file has been changed.

Parameters

pre_add_comment

Syntax
Description

Called prior to adding a comment to the specified version.

Parameters

post_add_comment

Syntax
Description

Called after a comment has been added.

Parameters

post_write_controlled_file

Syntax
Description

Called after a controlled and checked-in file is updated. This call is made in addition to any other calls after the file has been updated.

Parameters

post_delete_controlled_file

Syntax
Description

Called after a controlled and checked-in file is deleted. This call is made in addition to any other calls after the file has been updated.

Parameters

pre_copy_version

Syntax
Description

Called when a set of versions is being copied from one history to another. The source_params specify the location of the source history and the first version in the source history being copied. The destination_params specify the destination history and the first version onto which the history is copied.

When copying versions between subsystems, the version control key of the destination subsystem is used.

Parameters

post_copy_version

Syntax
Description

Called after versions have been copied from one history to another.

Parameters

pre_create_view

Syntax
Description

Called prior to creating a new view.

Parameters

post_create_view

Syntax
Description

Called after a new view has been created. This is called in addition to post_create_view in the compiler customization.

When a frozen view is requested it is possible that the conditions necessary to freeze a view will not be met (for example, the imports may not be valid). In this case the kind will change to stable.

Parameters

pre_delete_view

Syntax
Description

Called prior to deleting a view. This is called in addition to pre_delete_view in the compiler customization.

Parameters

post_delete_view

Syntax
Description

Called after a view has been deleted. This is called in addition to post_delete_view in the compiler customization.

TParameters

pre_change_kind

Syntax
Description

Called prior to changing the kind of a release.

Parameters

post_change_kind

Syntax
Description

Called after the kind of a release has been changed.

When a frozen view is requested. it is possible that the conditions necessary to freeze a view will not be met (for example, the imports may not be valid). In this case. the kind will change to stable.

Parameters

pre_set_attr

Syntax
Description

Called prior to setting extended version control attributes. This trigger is used when individual attributes are set but not when a file is used specify a list of attributes. This trigger is invoked when attributes are set by the explicit set_attribute command and when attributes are set as a side-effect of other commands such as check_in.

Parameters
Environment:

post_set_attr

Syntax
Description

Called after setting extended version control attributes. This trigger used when individual attributes are set but not when a file is used specify a list of attributes.

Parameters
Environment

pre_set_attr_file

Syntax
Description

Called prior to setting extended version control attributes. This trigger used when a file is used specify a list of attributes.

Parameters
Environment

post_set_attr_file

Syntax
Description

Called after setting extended version control attributes. This trigger is used when a file is used to specify a list of attributes.

Parameters
Environment

pre_unset_attr

Syntax
Description

Called prior to resetting an extended attribute.

Parameters
Environment

post_unset_attr

Syntax
Description

Called after resetting an extended attribute.

Parameters
Environment

pre_add_task

Syntax
Description

Called prior to associating a version with a task by the add_task command.

Parameters

post_add_task

Syntax
Description

Called after associating a task with a version by the add_task command.

Parameters

pre_remove_task

Syntax
Description

Called prior to removing a task association by the remove_task command.

Parameters

post_remove_task

Syntax
Description

Called after associating a task with a version by the remove_task command.

Parameters


Changing Customization Keys

Compiler Keys

Explicit Key Changes

You can change the compiler key in a view at any time by changing the model of the view or by editing the key value in the switch file. When you change the key using the remodel command, the unset_key customization operation is called on the old key and the set_key customization operation is called on the new key.

When you edit the switch file to change the keys, all operations that use the key fail until the model has been refreshed. Refreshing the model causes unset_key and set_key to be called on the old and new key values.

Internally Summit/CM stores the current key value and the time stamp of the switch file at the last time the model was set or refreshed.

Because changing the compiler key relies on calling the old key to reset itself, situations can occur where the view cannot be made usable because the old customization no longer exists. A force option to the remodel command causes the operation to succeed even if the old customization no longer exists or if it fails in the unset_key operation.

Implicit Key Changes

Because customization keys are simply directory pathnames, a key can name a symbolic link such as /Rational/compilers/ada_current. When this happens, the customization used by a view is changed implicitly when the symbolic link is changed. Customizations can store their own version information to deal with this so that they can detect obsolescence when the compiler changes.

Version Control Keys

You change a version control key by editing the subsystem switch file. When a version control key is changed, the effect is immediate.


Miscellaneous

Shell Variables

Prior to calling any executables, the shell variables APEX_COMPILER_KEY or APEX_VERSION_CONTROL_KEY are set to contain the value of the customization key switch. Customizations can use the shell variables to refer to other executables or files that are part of the customization. For example, the C++ customization can use the shell variables to refer to the makefiles used.

These shell variables are set by Apex. They can be overridden using either the VERSION_CONTROL_KEY switch or the APEX_CMVC_KEY environment variable. More information on customization keys can be found in Customization Keys.

Messages Generated by Customization Scripts

Generally, any messages generated by customization scripts are echoed by the command that called the customization. By default, any messages emitted to standard output are treated as text messages while any messages emitted to standard error are treated as error messages.

It is also possible for the customization to specify a message kind by appending a standard message prefix to the beginning of the message. For example, any message that begins with "+++" is treated as a positive message.

Customization Scripts Calling Rational Commands

Customization scripts can call Rational commands. However, performing Rational operations from a customization script might run into locks that have been set by the original Rational command. For example, the customization script for post_check_in might run into locks set by the original check_in command.


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