![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Managing Target Libraries and Compilation This chapter describes the method of extending your customization to manage target libraries and compilation by using shell scripts. This allows you to control creation and deletion of target directories, imports, compilation, and RCI operations.
As you read this chapter, use the scripts provided in the example customization as samples for the operations described.
The chapter contains information about the following areas:
- Using Scripts to Extend Your Customization
- Required Scripts
- Library Management
- Compilation Management
- RCI Extensions and Utilities
Note: Rational may be able to provide additional information to help with customization for a particular target compilation platform or vendor compiler. Before you begin a customization, contact your Rational representative for more information.
Using Scripts to Extend Your CustomizationCertain scripts are required; others are optional. The scripts you use depend on the requirements of your target compiler. As you customize, you will use some scripts as they exist now in the example customizations, you will modify others, and you may need to write some from scratch based on the requirements of your target compiler. Use the example customizations as a place to start.
Scripts are used to send basic instructions to the target compiler. You are generating, from your host RCI customization, the commands to send to the target compilation system. They should be, in most cases, the same instructions that you would issue from a command line on the target platform.
As you customize, you use these scripts to implement the functionality of the RCI user commands. You must address the basic user commands and explain how, if at all, your customization supports these operations. Provide this information, in the form of notes or a customization guide, to your users to complete the information in the RCI User's Guide.
Choosing a language for your scripts
The Rational provided example customizations use the Bourne shell because it is the most commonly available portable scripting language across UNIX systems.
This makes the Bourne shell the easiest choice for deriving your own scripts from the example scripts and propagating your changes across Apex releases. But this does not preclude you from using another language for your own scripts.
On UNIX, you may use any language, as long as the scripts may be invoked and executed on the Apex host UNIX platform.
On Windows, Apex NT has to use an extension-based mechanism to determine what interpreter should be invoked to execute a script. This reduces the possible choices for scripting languages.
When Apex NT has to invoke script X, it will try the following, in that order:
- if X.exe exists, it will execute it directly, as an executable;
- if X.bat exists, it will invoke the cmd.exe Windows command interpreter to execute it;
- if X.pl exists, it will invoke perl.exe to execute it;
- if X.sh exists, it will invoke sh.exe to execute it;
- if X.csh exists, it will invoke csh.exe to execute it.
Note: Using Perl, Bourne shell or C-shell scripts with Apex NT requires a third-party interpreter to be installed on the Apex host Windows platform.
Writing Scripts
To modify and create scripts, you need all available documentation for your target compilation system.
Note: In general, do not modify non-labelled areas in required scripts. If you do need to make changes, limit them to calls to separate scripts and label them clearly. In future releases, these scripts may be modified and you will need to recreate your modifications.
Required scripts include the following message:
######################################################## ########################################################
# NOTE TO CUSTOMIZERS: This file is required for RCI base functionality. Avoid modifying code not labeled for customization. Changes can affect RCI processes. This file may change in future releases of the product. To minimize upgrade impact, modify this file with calls to additional shell scripts where you provide code specific to your customization.
######################################################## ########################################################Areas of code that you can modify in required scripts are located in the following box:
##################################### # # CUSTOMIZABLE CODE # Hints :- # body of code here..... # # END CUSTOMIZABLE CODE # #####################################Limit your changes to these areas.
You can use the .Rational/Rci directory of your host view as the area where you can create and modify any files for the view, for example, import lists. The example customizations create target imports related files here, and the RCI maintains the target_names.sf file (host to target unit name mapping state file), and the .rci unit attribute files in this directory.
Documenting Scripts
As you modify existing scripts and create new ones, you need to document the scripts in your compiler key directory. Use the following guidelines:
- Start every script with a header that contains the following:
- The name of the script
- A line indicating which operations invoke it and how
- A line indicating which operations it calls
- Is the script required or optional for RCI functionality?
- Return values of the script (What codes are returned?)
- Parameters, each with a brief description
- Brief description of the script
- Customization hints
- The "NOTE TO CUSTOMIZERS" text (shown above)
- Enclose any customizable segment within a comment box titled "CUSTOMIZABLE CODE" (shown above). Include hints, if available, relating to customizing this portion.
- Add information about each script to the compiler key directory README file. This file should contain a list of all files and hooks in the directory, with a brief description of each. This entry is described in Documenting your Customization.
Required ScriptsThe basic RCI requires that some scripts are present in all customizations. The RCI and Apex provide basic operations through these scripts. You are limited in the areas where you can modify these. You must include the following scripts:
- Summit/CM extensions:
The RCI calls these scripts to extend the Apex operations.
- post_create_view
- post_delete_unit
- post_delete_view
- post_import
- pre_delete_view
- set_key
- unset_key
- Compilation extensions:
The RCI calls these scripts in place of the Apex operations. If you omit one of them, the corresponding Apex operation is not available.
- analyze
- check_rules
- clean
- code
- link
- migrate
- parse
- pretty_print
- RCI specific extensions:
As with the Apex compilation extensions, the RCI calls these scripts only if you include them in your compiler key directory.
- rci_build_target_name
- rci_post_build_script
- rci_post_compile
- rci_post_make_consistent
- rci_post_put
- rci_runon
Library ManagementThe RCI directly or indirectly calls Summit/CM-related Apex operations in the process of managing target libraries. It supports and enhances the following operations through scripts:
- Target library creation/deletion
- Imports management
- Target unit deletion
Depending on the requirements of your target compiler, the RCI uses some or all of the following scripts and associated sub-scripts:
- post_create_view
- post_create_view.mkdir
- post_delete_unit
- post_delete_unit.rm
- post_delete_view
- post_delete_view.rmdir
- post_import
- post_import.do_imports
- pre_delete_view
- set_key
- unset_key
The following table shows the commands that call these scripts and the order of those calls:
Note: File > New > New View, File > Copy Object, and File > Delete Object are for view operations.
Note: Apex calls post_delete_unit if, and only if, the object being deleted is a unit.
Note: pre_ and post_delete_view are only called if the DESTROY_EXISTING switch is set.
Library Creation and Deletion
To create and delete target libraries for your target compiler, you need to generate the correct commands for the target compilation platform. To modify your customization to do this, you typically need to substitute the commands for your compiler in the appropriate locations in the following scripts:
- post_create_view.mkdir
- post_delete_view.rmdir
To delete the target library, the example customization simply removes the target directory. Your compiler may require other target-specific operations.
For most customizations, a single host view maps directly to a single target directory. For some compilation systems, you may need to map multiple host views to a single target directory. In this case, you must modify your customization to take the appropriate actions when creating and deleting target directories.
Target unit deletion
To delete a unit in a target library for your target compiler, you need to generate the correct commands for the target compilation platform. To modify your customization to do this, you typically need to substitute the commands for your compiler in the appropriate locations in the post_delete_unit.rm script.
This may simply involve removing the target unit source file (and possibly associated files) form the target directory. Your compiler may require other target-specific operations.
Imports management
The strategy you use for imports in your customization depends on your target compiler.
Your target compiler uses one of several basic import models:
- Import by library: (similar to Rational Apex) a library can include or import other libraries; everything in an imported library is visible in every library that imports it.
- Import by specific unit: (Alsys model) each unit needed by a library must be imported separately.
- Hierarchical imports (DEC Ada model): libraries are visible to libraries below them in a hierarchical directory structure.
See the Apex manual set for more information on how Apex manages host imports.
Define your importing scheme in the following scripts:
- post_import
- post_import.do_imports
You can use the .Rational/Rci directory of your host view as the area in which to create and store import-related files.
The kind of mapping between host views and target libraries, one-to-one, or many-to-one (not generally recommended), impacts imports. You must modify your import scripts to take the appropriate action for your target compiler.
Import by Library
For most standard compilers using import by library, the imports are handled by one or the other of these two methods:
- creating a file that contains a list of imported libraries.
- issuing commands to the target compiler to import libraries; the target compiler maintains the import list.
For these methods, you create the file that will contain the list or issue the appropriate command to your target compiler. For each imported host view:
- 1 . Check whether or not the view is host-only; if so, you may need to include it or not, depending on whether the target compiler needs an explicit import or not.
- 2 . Using the host view name, find the target directory name associated with the view. Determine the correspondence between the host view and the target directory, and include the target directory information.
- 3 . Add the target directory to the import file or issue the appropriate command to the target compiler.
- 1 . Get the current import list, if needed, from the target compiler.
- 2 . Get the new host view import list.
- 3 . Convert the host view names to the corresponding target directory names.
- 4 . Compare the lists, to determine which target imports need to be added or removed.
- 5 . Modify the import file or issue commands to the target compiler to add or remove target imports.
Import by Unit
When you import on a unit-by-unit basis, as required by Alsys compilation systems, the import operations must be done before you compile the units. You can handle the import operations when you issue an import command or at the time you compile the unit. However, importing at compile time may not be the most efficient method for your customization.
A possible approach might be as follows: as each unit is compiled, it is imported into each target library that is associated to a view that imports the view which contains the unit. To do this, you must keep track of what views import each host view. You can do this in the post_import script. When view B imports view A, post_import must update a file in view A to indicate that B imports target library units from view A. You can modify the rci_post_compile script to use that list, when a unit is compiled, to import the unit into each target library that needs that unit.
While the RCI does not usually use export sets, you may want to consider using them for Alsys customizations to improve efficiency. See the Apex documentation for more information.
Hierarchical Imports
When you import using hierarchical directory structures (as with the DECAda compiler), create and update the structures correctly to provide visibility to the imports. Use the scripts to manipulate the search paths for the target directories.
Remodelling Views
Under some circumstances, for example, when copying an RCI view to an Apex view, the operation changes the existing compiler key for the new view. During this process, Apex calls unset_key from the old compiler key, and set_key from the new compiler key when it remodels the view. You may want to modify these scripts to handle additional actions, for example, removing the .Rational/Rci directory from the new Apex view.
When you upgrade from one RCI release to another, you need to remodel existing views. Use set_key and unset_key to make changes if necessary. You may need to modify these scripts to accommodate new RCI compiler keys during the upgrade, or temporarily disable actions in these scripts.
Compilation ManagementCompilation extensions handle compile and link operations for your customization.
Apex calls the RCI script as a compiler extension in place of the Apex operation; the RCI script then calls the Apex function. If there is no RCI script, the Apex function is not called and the Apex operation does not work. You should not need to make changes to these scripts under normal circumstances. Use them to extend RCI compilation to include features of your target compiler, for example, the VADS preprocessor. In unusual circumstances, you may need to alter target naming or imports using them.
Extensions to Apex compilation functions include the following scripts:
- analyze
- check_rules
- clean
- code
- link
- migrate
- parse
- pretty_print
For example, as it executes the code operation, Apex calls the corresponding RCI script which calls the host Apex compiler. This passes the compilation command defined in rci_op.spec to the rci_runon script to handle target compilation. You can modify the compilation extensions either in the compilation scripts or in scripts used as calls to the target compiler.
The version of the Apex compiler is host-platform specific, but for all versions, your scripts must use the command name rada to invoke it.
RCI Extensions and UtilitiesThe RCI can also call scripts that provide extensions to existing RCI commands.
An RCI extension script begins with the prefix rci_. To make it possible to invoke a script that already exists in your compiler key directory, change the script name (if necessary) from rci_script_name.txt to rci_script_name, and set the execute permissions.
You can extend RCI-specific operations with the following scripts:
- rci_build_target_name: target unit naming
- rci_post_build_script: batch operations
- rci_post_compile:
- Setting up "import-by-unit" compiler imports
- Retrieving associated files or return values
- Extending unit-by-unit operations
- rci_post_make_consistent: host/target consistency management
- rci_post_put: unit transfer
- rci_runon: utility for target command execution
The following table shows the commands that call the RCI extension scripts and the order in which they are called:
Compile > Code RCI > Compare to Target RCI > Accept Target Changes RCI > Create Script
rci_build_target_name 1
rci_post_put 2
rci_post_compile 3 1
rci_post_make_consistent 1 1
rci_post_build_script 1
The Apex compiler calls the rci_runon script to execute target compiler commands.
In addition, most RCI customizations include calls to rci_runon in the scripts post_create_view.mkdir, post_delete_unit.rm, post_import.do_imports, post_delete_view.rmdir, rci_group_compile and recursive_mkdir.
Batch Operations
The RCI calls the rci_post_build_script when generating a batch compilation script.
When the GENERATE_BATCH_COMPILE_COMMANDS RCI operational characteristic is set to True, the RCI generates a default batch compilation script before calling rci_post_build_script. In this case, the rci_post_build_script extension is optional, but may be used to customize the generated script (taking actions such as: customize any output files, optimize the batch compiler invocations, check nodes to optimize machine load, clean up storage after a compile operation) and to transfer the script to the target platform.
When GENERATE_BATCH_COMPILE_COMMANDS is not set, no default batch script is generated, and the RCI relies on rci_post_build_script for creation of the batch script.
Target Unit Naming
The RCI creates a unit's target name when it first codes the unit. If you do not want to use the default naming schemes that the RCI uses to create target unit names, modify the rci_build_target_name script to implement your own naming scheme.
When the HOST_NAME_EQUALS_TARGET_NAME RCI operational characteristic is set to True, the RCI uses the host unit name (Ada name) as the base for the target unit name. The Ada name is transformed according to the operational characteristics for unit name composition defined in rci_op.spec.
When HOST_NAME_EQUALS_TARGET_NAME is not set (or if the name generated above would be too long), the RCI by default generates unique target unit names, based on operational characteristics for unit name composition defined in rci_op.spec.
To use your own naming scheme, unset the HOST_NAME_EQUALS_TARGET_NAME operational characteristic in the rci_op.spec file and provide a rci_build_target_name script. The RCI will then call your script to generate target names.
From the host unit name, build the target name you want to use.You can use values for the unit-name related operational characteristics defined in rci_op.spec as components of the names.
If you choose to change the target naming scheme for an existing view, clean the host view, and remove the target_names.sf state file in the .Rational/Rci directory of the view, to rebuild the new target names at the next compile (it may also be necessary to re-create the target library for the view, so that the target compiler does not get confused by the unit name changes).
Transferring Units
The RCI calls rci_post_put for each unit that it transfers in interactive mode.
When using the default download scheme (USE_DEFAULT_DOWNLOADING RCI operational characteristic set to True), the RCI itself creates the target units, as links from the target directory to the host view. This assumes that the host view directory is visible (typically through NFS) from the target platform. The rci_post_put script is not needed in that case.
If you need customized downloading (non-NFS target platform or transfer through tape for a secure environment), unset USE_DEFAULT_DOWNLOADING in the rci_op.spec file, and modify the rci_post_put script to perform the transfer operation.
Consistency Management
The rci_post_make_consistent script allows you to modify the method you use to compare host and target units to support the ability to compare by timestamp or by source.
For some customizations, you must upload source files from the target compilation platform to the host and then compare them on the host. In other cases, you need to return a value from the target indicating the result of the compare. You may choose to modify the compare command you use for source files.
If you are using the default download scheme, the target unit files are maintained as links and are thus always consistent.
Remote Execution
The rci_runon script is a utility that handles downloading and connection to the target compilation platform. Use this script to control remote execution on and communication with your target compilation platform. If you are running UNIX, or a UNIX-like environment, you should not need to make major changes. The example customization script uses the UNIX rsh command for communication. If you have different requirements for your hardware or operating system, modify the script.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |