TOC PREV NEXT INDEX DOC LIST MASTER INDEX



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:

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 Customization

Certain 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:

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:

Areas of code that you can modify in required scripts are located in the following box:

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:


Required Scripts

The 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:


Library Management

The 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:

Depending on the requirements of your target compiler, the RCI uses some or all of the following scripts and associated sub-scripts:

The following table shows the commands that call these scripts and the order of those calls:


File >
New >
New View

File >
Copy Object

File >
Delete Object

Control >
Change View Properties


Control >
Maintenance >
Remodel

RCI >
Refresh Target
Imports

RCI >
Create Target Library

RCI >
Delete Target Library

post_create_view
1
1




3

post_delete_view


2



2
2
post_delete_unit


1





post_import
2
2

1

1
4

pre_delete_view


1



1
1
set_key




2



unset_key




1



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:

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:

See the Apex manual set for more information on how Apex manages host imports.

Define your importing scheme in the following scripts:

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:

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.

To update existing imports:

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 Management

Compilation 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:

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 Utilities

The 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:

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.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS