![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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:
- Compiler Customization
Use the compiler customization to specify the compiler and related programs used for compilation-oriented operations within a view. For example, the compiler-specific compatibility checks performed as part of importing are provided as part of the compiler customization.
- Version Control Customization
Use the version control customization to customize Summit/CM version control operations within a subsystem. For example, you can use version control customizations to provide authorization checking or logging facilities for Summit/CM operations such as check_in and check_out.
Customization KeysThe 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:
- COMPILER_KEY
or BUILD_KEYThis switch is stored in the switch file associated with a view and is used to specify the compiler components that will be used in that view.
- VERSION_CONTROL_KEY
The programs or scripts to use in extending the basic version control operations. This switch controls the version control operations in the associated subsystem and is used for customization of Summit/Configuration Management operations. It is only valid at the subsystem level.
This switch can contain a sequence of pathnames (separated by colons) each naming a particular version control customization directory. When a sequence is provided each customization is applied in the order specified.
In addition to the version control key, version control customization can also be enabled by setting the APEX_CMVC_KEY environment variable to name the directory containing customization scripts.
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 CustomizationSetting 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:
<major_number>.<minor_number>
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
post_create_viewrev new_view
[source_view
]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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- new_view
Specifies the new view that has been created.
- source_view
If the new view was created as a copy, this parameter is the name of the original view.
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:
- The new view is created. If the view is a copy of an existing view, the contents of the source view are copied into the new view.
- The files associated with the model are copied into the new view. (These files include the Switches containing the compiler_key).
- The "Interface" switch is set in the view to reflect its proper value.
- If the view was created as a copy, unset_key is called on the key of the source view. (This allows the old key to clean up its state.)
- post_create_view is called on the new key.
- The imports are analyzed. (This can involve other customization calls to check compiler compatibility, and so on.)
- post_import is called on the new key.
post_create_directory
Syntax
post_create_directoryrev directory
Description
Called after a directory has been created. For example, use this to create makefiles in the directory.
Parameters
- directory
Specifies the full pathname of the newly created directory.
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
post_create_unit
Syntax
post_create_unitrev unit
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- unit
Specifies the full pathname of the unit that has been created.
pre_delete_view
Syntax
pre_delete_viewview
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
post_delete_viewrev view
Description
Called after the view has been deleted.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
pre_freeze_view
Syntax
pre_freeze_viewrev view
Description
Called prior to changing the permissions on a frozen release view.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
post_delete_unit
Syntax
post_delete_unitrev unit
Description
Called after a unit has been deleted. Not called if the containing view was deleted at the same time.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- unit
check_imports
Syntax
check_importsrev importer_file wrk_file frz_file diag_file
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- importer_file
Specifies a file containing the names of the importer views. All the views in the file are part of the same mutual importing set. Keep in mind that views are importing one-another as well as the views in the wrk_file and the frz_file. All views in a mutual importing set must have the same compiler key.
- wrk_file
A file containing non-frozen views that are being imported, including working views, development release views, and stable release views. Contains both explicit and implicit imports.
- frz_file
A file containing any frozen release views that are being imported. Contains both explicit and implicit imports.
- diag_file
A file containing diagnostic information describing the result of the check.
Diagnostic File Format
Currently, any lines put into the diagnostic file are emitted by Summit/CM.
post_import
Syntax
post_importrev view mutual_file explicit_file implicit_file set_file
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view that is having its imports updated.
- mutual_file
Specifies a file containing the set of imports that are mutual imports of the view.
- explicit_file
Specifies a file containing the name of each explicit import that is not a mutual import.
- implicit_file
Specifies a file containing the name of each implicit import.
- set_file
Specifies a file containing the export set used for each of the explicit imports.
To put the import related operations in context, the following bullets summarize the import process:
- Process explicit imports.
- Compute implicit imports by looking at the closure of the explicit imports.
- Check compiler-independent import consistency.
- Call check_imports to make compiler-dependent checks.
- Commit imports, update Compilation.cfg.
- Call post_import.
post_create_export_set
Syntax
post_create_export_setrev view export_set_name
Description
Called when a new export set has been created.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the name of the view containing the export set.
- export_set_name
post_delete_export_set
Syntax
post_delete_export_setrev view export_set_name
Description
Called when an export set has been deleted.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view that contained the export set.
- export_set_name
post_export
Syntax
post_exportrev view export_set_name export_set_file
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the name of the view that contains the units.
- export_set_name
Specifies the simple name of the export set that will include these units.
- export_set_file
Specifies a file containing the set of units to be exported. Each line of the file contains a single view-relative unit name.
post_main_program
Syntax
post_main_programrev view main_units_file
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the main programs.
- main_units_file
Specifies a file containing the view-relative names of all the main units that have been registered.
set_key
Syntax
set_keyrev view old_key
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view whose key is being changed.
- old_key
unset_key
Syntax
unset_keyrev view new_key
Description
Called when the compiler key of an existing view is changed from this value. This operation always precedes set_key.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view whose key is being changed.
- new_key
parse
Syntax
parserev view
[compiler_options
] [units_in_view...
]Description
Performs syntactic analysis on the units in the designated view.
Must be provided to run apex parse.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the units to parse.
- compiler_options
Any options that were passed to the original command.
- units_in_view
Specifies the view-relative names of the units to parse. If no units are given, all units in the view should be parsed. May also name subdirectories in the view when all units in the subdirectories are to be parsed.
analyze
Syntax
analyzerev view
[compiler_options
] [units_in_view...
]Description
Performs semantic analysis on the units in the designated view.
Must be provided to run apex analyze.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the units to analyze.
- compiler_options
Any options passed to the original command.
- units_in_view
The view-relative names of the units to analyze. If no units are given, all units in the view should be analyzed. May also name subdirectories in the view when all units in the subdirectories are to be analyzed.
code
Syntax
coderev view
[compiler_options
] [units_in_view...
]Description
Codes the units in the designated view.
Must be provided to run apex code.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the units to code.
- compiler_options
Specifies any options passed to the original command.
- units_in_view
Specifies the view-relative names of the units to code. If no units are given, all units in the view should be coded. May also name subdirectories in the view when all units in the subdirectories are to be coded.
link
Syntax
linkrev view
[compiler_options
] [units_in_view...
]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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the units to link.
- compiler_options
Specifies any options passed to the original command.
- units_in_view
Specifies the view-relative name of the units to link. If no units are given, all appropriate main units should be linked. May also name subdirectories in the view when all appropriate units in the subdirectories are to be linked.
clean
Syntax
cleanrev view goal_state
[compiler_options
] [units_in_view...
]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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the units to clean.
- goal_state
Specifies the compilation state to which the view or units will be cleaned. The possible values are: archived, source, installed, and coded.
- compiler_options
Specifies any options passed to the original command.
- units_in_view
Specifies the view-relative names of the units to clean. May also name subdirectories. If none are given, the entire view is cleaned.
migrate
Syntax
migrate [compiler_options
] rev view target_directory files...
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the parsed units.
- compiler_options
Specifies any options that were passed to the original command.
- target_directory
Specifies the directory in the view, which will contain the new units. The directory name is relative to the view parameter.
- files
pretty_print
Syntax
pretty_printrev view
[compiler_options
] [units_in_view...
]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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view containing the units.
- compiler_options
Specifies any options passed to the original command.
- units_in_view
Specifies the view-relative name of the units to pretty print.
dependencies
Syntax
dependenciesrev view
[compiler_options
]Description
Updates any necessary dependency information in the view.
Must be provided to run apex dependencies.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view in which to compute dependencies.
- compiler_options
maintain
Syntax
maintainrev
[options
]view
Description
Performs maintenance on the compiler state.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view to be maintained.
- options
Only checks for problems if set, but does not repair. Otherwise, problems are repaired.
Compiler Customization Properties FileUse 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:
- LANGUAGE: Ada | C++
Specifies the language that is supported for compilation in the view. This affects which program unit subclasses are compilable in the view.
Note: Compilers for C++ should also include support for C language units.
- ADA_DIALECT: Ada_83 | Ada_95
If the language is Ada, this switch specifies the dialect of the Ada language. If no dialect is set, Ada_83 is assumed.
- CLASS: Standard | Extended | Rational_Ada | Rational_Build
Specifies the class of the compiler customization. The different classes are described below. The class determines the operations you can customize.
- HOST_ARCHITECTURE: sun4_solaris2 | rs6k | hppa_hpux | alpha_osf1 | mips_irix5 | winnt_x86
Specifies the host architecture for the compiler and its components. You can run the compiler and other customization operations only on the specified architecture. Attempts to run customization operations on another architecture result in an error.
- TARGET_ARCHITECTURE: sun4_solaris2 | rs6k | hppa_hpux | alpha_osf1 | mips_irix5 | winnt_x86
Specifies the target architecture for the compiler. This specifies the architecture for object files and executables in the view.
- REUSE_ATTRIBUTES: True | False
Set to true if the compiler is able to reuse its attribute files (for example, object files and Diana trees).
If set to true, Summit/CM operations that move units between views with the same host and target architectures also move attribute files. Otherwise, the attribute files are not moved. This also controls whether attribute files are copied when an entire view is copied.
Normally, the Ada compiler sets REUSE_ATTRIBUTES to true, while the internal C++ compilation tools does not reuse attributes.
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:
- Standard
The Standard class supports customization using the following operations:
- check_imports
- post_import
- post_import_set
- post_export
- post_main_program
- pre_freeze_view
- parse
- analyze
- code
- link
- clean
- migrate
- pretty_print
- dependencies
- maintain
- Extended
The Extended class supports customization using all operations included in the Standard class and using the following operations:
- post_create_view
- pre_delete_view
- post_delete_view
- set_key
- unset_key
- post_create_directory
- post_create_unit
- post_delete_unit
- Rational_Ada
The Rational_Ada class supports the normal platform Ada compiler that is shipped as part of Apex.
- Rational_Build
The Rational_Build class supports management of makefiles for C, C++ and Java. The capabilities of this class are described in the Build Management chapter of the Command Line Reference document.
Version Control CustomizationYou 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:
- Check all standard Summit/CM conditions.
If any conditions are not satisfied, the operation will not proceed.
- Call the appropriate "pre" operation.
If the "pre" operation does not return a successful status, the operation will not proceed unless the -force option was set on the original command.
- Perform the Summit/CM operation.
- Call the appropriate "post" operation if everything was successful.
The VERSION_CONTROL_KEY and APEX_CMVC_KEY switches may contain a sequence of customization pathnames of the form:
<pathname1> : <pathname2> : ...
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:
<major_number>.<minor_number>
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:
- The Policy directory of the enclosing view.
- The Policy directory of the enclosing subsystem.
- A directory named by the VERSION_CONTROL_KEY context switch of the view or subsystem.
- A directory named by the APEX_CMVC_KEY session switch.
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:
action <action-name
> <object-filter
> <apex-shell-statements
> end_action
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:
action pre_check_out *.c echo "Checking out a C source file $2 " end_action
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
pre_controlrev file history version comment
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:
- Call pre_control.
- Call pre_create_version new.
- Create the new version and control the file.
- Call post_create_version new.
- Call post_control.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being controlled.
- history
Specifies the history associated with the file.
- version
Specifies the version number associated with the file.
- comment
post_control
Syntax
post_controlrev file history version comment
Description
Called after the file has been made controlled.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being controlled.
- history
Specifies the history associated with the file.
- version
Specifies the version number associated with the file.
- comment
pre_accept_control
Syntax
pre_accept_controlrev file history version comment
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the new file that was controlled.
- history
Specifies the history associated with the file.
- version
Specifies the version number associated with the file.
- comment
post_accept_control
Syntax
post_accept_controlrev file history version comment
Description
Called after a new file has been controlled by accept_changes.
Parameters
- rev
Revision of the compiler customization interface. For more details see Version Control Customization.
- file
Specifies the new file that was controlled.
- history
Specifies the history associated with the file.
- version
Specifies the version number associated with the file.
- comment
pre_uncontrol
Syntax
pre_uncontrolrev file
Description
Called prior to making a file uncontrolled.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
post_uncontrol
Syntax
post_uncontrolrev file
Description
Called after a file has been made uncontrolled.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
pre_check_out
Syntax
pre_check_outrev file history version comment
Description
Called prior to check_out of a controlled file.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being checked out.
- history
Specifies the history associated with the file.
- version
Specifies the new version created by the check out.
- comment
post_check_out
Syntax
post_check_outrev file history version comment
Description
Called after check_out of the file.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being checked out.
- history
Specifies the history associated with the file.
- version
Specifies the new version created by the check out.
- comment
pre_private_check_out
Syntax
pre_private_check_outrev file history version comment
Description
Called prior to "private" check_out of a controlled file.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being checked out.
- history
Specifies the history associated with the file.
- version
Specifies the new version created by the check out.
- comment
post_private_check_out
Syntax
post_private_check_outrev file history version comment
Description
Called after a private check_out of the file.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being checked out.
- history
Specifies the history associated with the file.
- version
Specifies the new version created by the check out.
- comment
pre_upgrade_check_out
Syntax
pre_upgrade_check_outrev file history version comment
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being checked out.
- history
Specifies the history associated with the file.
- version
Specifies the new version created by the check out.
- comment
post_upgrade_check_out
Syntax
post_upgrade_check_outrev file history version comment
Description
Called after check_out of the file.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file being checked out.
- history
Specifies the history associated with the file.
- version
Specifies the new version created by the check out.
- comment
pre_check_in
Syntax
pre_check_inrev file history version comment
Description
Called when a checked out file is checked in.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file that was checked out.
- history
Specifies the history associated with the file.
- version
Specifies the number of the new version.
- comment
post_check_in
Syntax
post_check_inrev file reason history version comment
Description
Called after a new version has been created.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file that was checked out.
- history
Specifies the history associated with the file.
- version
Specifies the number of the new version.
- comment
pre_abandon
Syntax
pre_abandonrev file history version comment
Description
Called prior to abandoning the check out of an object.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file whose check out is being abandoned.
- history
Specifies the history associated with the checked-out file.
- version
Specifies the version currently checked out.
- comment
post_abandon
Syntax
post_abandonrev file history version comment
Description
Called after check out has been abandoned.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file whose check out is being abandoned.
- history
Specifies the history associated with the checked-out file.
- version
Specifies the version currently checked out.
- comment
pre_create_version
Syntax
pre_create_versionrev file reason history version comment
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file that is the source of the new version.
- reason
Specifies the reason behind the creation of the new version. Possible values are:
first The first version of a new version history
new A new version
deleted A deleted version
- history
Specifies the history containing the new version.
- version
Specifies the version number of the new version.
- comment
post_create_version
Syntax
post_create_versionrev file reason history version comment
Description
Called after a new version has been created.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the file that is the source of the new version.
- reason
Specifies the reason behind the creation of the new version. Possible values are:
first The first version of a new version history
new A new version
deleted A deleted version
- history
Specifies the history containing the new version.
- version
Specifies the version number of the new version.
- comment
pre_set_version
Syntax
pre_set_versionrev file history version comment
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled file whose version is being changed.
- history
Specifies the current history of the file.
- version
Specifies the version number to which the file will be set.
- comment
post_set_version
Syntax
post_set_versionrev file history version comment
Description
Called after the version of a controlled file has been changed.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled file whose version is being changed.
- history
Specifies the current history of the file.
- version
Specifies the version number to which the file will be set.
- comment
pre_set_history
Syntax
pre_set_historyrev file history version comment
Description
Called prior to changing the history of a controlled file.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- file
Specifies the controlled file whose history is being changed.
- history
Specifies the history that will be associated with the file argument.
- version
Specifies the version in the history with which the file will be associated.
- comment
post_set_history
Syntax
post_set_historyrev file history version comment
Description
Called after the history of a controlled file has been changed.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled file whose history is being changed.
- history
Specifies the history that will be associated with the file argument.
- version
Specifies the version in the history with which the file will be associated.
- comment
pre_add_comment
Syntax
pre_add_commentrev file history version comment
Description
Called prior to adding a comment to the specified version.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled file.
- history
Specifies the history associated with the controlled file.
- version
- comment
post_add_comment
Syntax
post_add_commentrev file history version comment
Description
Called after a comment has been added.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled file.
- history
Specifies the history associated with the controlled file.
- version
- comment
post_write_controlled_file
Syntax
post_write_controlled_filerev file
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled and checked-in file that has been updated.
post_delete_controlled_file
Syntax
post_delete_controlled_filerev file
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- file
Specifies the controlled and checked-in file that has been deleted.
pre_copy_version
Syntax
pre_copy_versionrev source_params destination_params count
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- source_params
Specifies a sequence of four items:
- source_subsystem
- source_element
- source_history
- source_version
- destination_params
Specifies a sequence of four items
- destination_subsystem
- destination_element
- destination_history
- destination_version
- count
Specifies the total number of versions copied from the source history to the destination history.
post_copy_version
Syntax
post_copy_versionrev source_params destination_params count
Description
Called after versions have been copied from one history to another.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- source_params
Specifies a sequence of four items:
- source_subsystem
- source_element
- source_history
- source_version
- destination_params
Specifies a sequence of four items
- destination_subsystem
- destination_element
- destination_history
- destination_version
- count
Specifies the total number of versions copied from the source history to the destination history.
pre_create_view
Syntax
pre_create_viewrev new_view kind
[source_view
] [copy_options
]Description
Called prior to creating a new view.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- new_view
Specifies the name of the view to be created.
- kind
Specifies the kind of the new view. The possible values are:
- working
- development
- stable
- frozen
- source_view
Specifies the source view if the new view was created as a copy.
- copy_options
Provided only when a source view is provided. For objects controlled in the source view, this specifies their state in the new view.
post_create_view
Syntax
post_create_viewrev new_view kind
[source_view
]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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- new_view
Specifies the name of the view to be created.
- kind
Specifies the kind of the new view. The possible values are:
- working
- development
- stable
- frozen
- source_view
Specifies the source view if the new view was created as a copy.
- copy_options
Provided only when a source view is provided. For objects controlled in the source view, this specifies their state in the new view.
pre_delete_view
Syntax
pre_delete_viewrev view
Description
Called prior to deleting a view. This is called in addition to pre_delete_view in the compiler customization.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- view
post_delete_view
Syntax
post_delete_viewrev view
Description
Called after a view has been deleted. This is called in addition to post_delete_view in the compiler customization.
TParameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- view
pre_change_kind
Syntax
pre_change_kindrev view kind
Description
Called prior to changing the kind of a release.
Parameters
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view being changed.
- kind
Specifies the new release kind. The possible values are:
- development
- stable
- frozen
post_change_kind
Syntax
post_change_kindrev view kind
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
- rev
Revision of the compiler customization interface. For more details see Compiler Customization.
- view
Specifies the view being changed.
- kind
Specifies the new release kind. The possible values are:
- development
- stable
- frozen
pre_set_attr
Syntax
pre_set_attrrev subsystem element history version mode attr-name attr-value
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the attribute.
- mode
Specifies how the attribute is being set. The possible values are:
- initial
Specifies that the attribute is being set to its initial value.
- inherit
Specifies that the attribute is being set a value inherited from a previous version.
- replace
Specifies that the new value is replacing the current value.
- append
Specifies that the new value will be appended to the existing value if the attribute is list valued.
- clear
Specifies that original value is being cleared prior to a new value being set.
- attr-name
Specifies the name of the attribute that is being set.
- attr-value
Environment:
post_set_attr
Syntax
post_set_attrrev subsystem element history version mode attr-name attr-value
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
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the attribute.
- mode
Specifies how that attribute is being set:
- initial
Specifies that the attribute is being set to its initial value.
- inherit
Specifies that the attribute is being set a value inherited from a previous version.
- replace
Specifies that the new value is replacing the current value.
- append
Specifies that the new value will be appended to the existing value if the attribute is list valued.
- clear
Specifies that original value is being cleared prior to a new value being set.
- attr-name
Specifies the name of the attribute that is being set.
- attr-value
Environment
pre_set_attr_file
Syntax
pre_set_attr_filerev subsystem element history version mode attr-file
Description
Called prior to setting extended version control attributes. This trigger used when a file is used specify a list of attributes.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the attribute.
- mode
Specifies how that attribute is being set:
- initial
Specifies that the attribute is being set to its initial value.
- inherit
Specifies that the attribute is being set a value inherited from a previous version.
- replace
Specifies that the new value is replacing the current value.
- append
Specifies that the new value will be appended to the existing value if the attribute is list valued.
- clear
Specifies that original value is being cleared prior to a new value being set.
- attr-file
Environment
- APEX_CURRENT_ATTR_VALUE
Contains the name of a temporary file containing the attribute values which were changed.
post_set_attr_file
Syntax
post_set_attr_filerev subsystem element history version mode attr-file
Description
Called after setting extended version control attributes. This trigger is used when a file is used to specify a list of attributes.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the attribute.
- mode
Specifies how that attribute is being set:
- initial
Specifies that the attribute is being set to its initial value.
- inherit
Specifies that the attribute is being set a value inherited from a previous version.
- replace
Specifies that the new value is replacing the current value.
- append
Specifies that the new value will be appended to the existing value if the attribute is list valued.
- clear
Specifies that original value is being cleared prior to a new value being set.
- attr-file
Environment
- APEX_CURRENT_ATTR_VALUE
Contains the name of a temporary file containing the attribute values which were changed.
pre_unset_attr
Syntax
pre_unset_attrrev subsystem element history version attr-name
Description
Called prior to resetting an extended attribute.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the attribute.
- attr-name
Environment
post_unset_attr
Syntax
post_unset_attrrev subsystem element history version attr-name
Description
Called after resetting an extended attribute.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the attribute.
- attr-name
Environment
pre_add_task
Syntax
pre_add_taskrev subsystem element history version task
Description
Called prior to associating a version with a task by the add_task command.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the task
- task
post_add_task
Syntax
post_add_taskrev subsystem element history version task
Description
Called after associating a task with a version by the add_task command.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the task
- task
pre_remove_task
Syntax
pre_remove_taskrev subsystem element history version task
Description
Called prior to removing a task association by the remove_task command.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the task
- task
post_remove_task
Syntax
post_remove_taskrev subsystem element history version task
Description
Called after associating a task with a version by the remove_task command.
Parameters
- rev
Revision of the version control customization interface. For more details see Version Control Customization.
- subsystem element history version
The full version name of the version associated with the task.
- task
Changing Customization KeysCompiler 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.
MiscellaneousShell 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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |