TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Building A Basic Customization

This chapter describes the steps necessary to build a basic customization. It focuses on building a simple working customization which you can enhance with the addition of advanced features (covered in Defining Basic Characteristics and Building Semantic Characteristics). The customization you build in this chapter contains enough information to be tested on the host platform. The reader will be able to build and test a basic customization using the instructions in the chapter.

This chapter expands on the steps for creating an RCI customization that were presented in "Customization Process Overview".

This chapter is organized by the order of the main steps to set up and test a basic customization. If you use the procedures in this chapter in the order that they are presented, you will be able to correctly create an RCI customization. The sections are:

If you are already familiar with the customization process, use the Customization Process Summary as a quick reference checklist of customization steps.

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.


Getting Started

Collecting Documentation for your Customization

To gather information for your customization, you need documentation for your target compilation system, remote operating system and target architecture, RCI and the Rational Apex Environment.

For the Target Compilation System

Documentation for the target compilation system includes any operating system manuals, user guides for the target compiler, reference manuals, and your vendor's Ada LRM.

For the Customization Interface

The RCI customization interface code resides in the <rational_dir>/base/ada/rci.ss subsystem. ($APEX_BASE has the same value as <rational_dir>/base.) This code provides the (now-obsolete) Ada interface to build the specification files.

Files in rci.ss views which will prove useful to post-Apex 3.0 customizers include:

Setting Up Customization Views and Compiler Key

When Apex/RCI is correctly installed on your system, the components reside in the structure shown in Figure 2.

Figure 2 RCI release area

When you customize RCI, you will create new views in the key, lrm, predefined and model subsystems, and additional views as needed to match the target library structure you are modeling (additional views corresponding to predefined target libraries are typical but may not be required).

Defining a Compiler Key

This describes the guidelines for selecting components of the compiler key name for your customization and includes recommendations and examples. You will use these components to create names for the compiler key view in <rational_dir>/base/ada/key.ss, names for views in lrm.ss, predefined.ss, model.ss (and possibly other subsystems).

For the RCI user, all RCI operations begin in a host view. To create the host view, the user must specify a model with a particular compiler key. The compiler key informs the Apex Ada Compiler that the view is an RCI view and provides the means for target-specific aspects of compilation (semantic modeling of the target compiler for host operations and remote execution of the target compiler for target operations).

Choose your compiler key view name to avoid conflict with any existing compiler key names. To do this, verify that your compiler key name does not match the name of any key.ss view.

An RCI customization's compiler key view name should have the following format:

A compiler key name, as an example of this form, is

Rational provides the following compiler keys in the <rational_dir>/base/ada/key.ss subsystem:

The structure of the compiler key name distinguishes between different target compilers on the same host platform; for example, between an AIX-based IBM compiler and an AIX-based VADS compiler. This convention ensures uniqueness among possible RCI compiler keys.

Building a Customization

The steps described in the following section give an overview of the basic customization process. For your first customization, you may want to take the minimum action necessary on some steps, then go back later and enhance those areas of customization; for example, you may choose not to customize pragmas for your initial effort. Or, you may choose to provide a minimum set of compiler options in a simple customization, then expand it as your users need more options.

As you customize, keep in mind that you need to complete at least these minimum steps to create a customization:


Building Your Customization

Creating the Compiler Key View

1 . Choose a compiler key name for your customization.

2 . Create a compiler key view using that name in the following location:

3 . Copy the contents (shell scripts, specification files, options files and the Compiler_Properties file) of an existing compiler key view from one of the RCI sample customizations into your newly-created compiler key view.

Be sure you set execute permissions on all scripts in your compiler key view.

Creating the Specification Files

1 . Modify the file rci_op.spec to define the remote operating system characteristics and target compiler/linker options. See Defining Target Command Properties.

    Note: You must complete the basic definitions in this file to create a basic customization.

2 . Modify the file rci_predef.spec to define the package Standard values for the target compiler. See Defining Package Standard Values.

    Note: You must complete the basic definitions in this file to create a basic customization.

3 . Modify the file rci_attrib.spec to define the Ada attributes used by the target compiler. See Customizing Attributes.

4 . Modify the file rci_pragma.spec to define the pragmas used by the target compiler. See Customizing Pragmas.

5 . Modify the file rci_rep_spec.spec to define the representation clauses used by the target compiler. See Customizing Representation Clauses.

Note: If you have an existing RCI customization which was created with a version of Apex prior to 3.0, you can create the specification files with the translate executable in the rci.ss view for the Apex release you are upgrading to. We recommend that you copy the existing compiler key view for the customization you wish to translate, naming the copied view according to the recommended guidelines, then run the following command:

Creating the Options Files

Run the command below in an Apex shell any time your compiler and linker options declarations have changed in rci_op.spec. This command will generate the files comp_option_line, comp_option_symbol, link_option_line and link_option_symbol in the compiler key.

Note: if your options were copied from an existing pre-Apex 3.0 customization, you can copy the files named above from that customization; the format has not changed for these files.

Building The LRM Subsystem

Choosing Packages for the LRM Subsystem

Apex requires that some packages must be in the LRM subsystem for RCI to operate. Others must be there only if the target Ada compiler requires them. The vendor's LRM contains information on which packages to include. You can place other packages that your compiler requires in the predefined subsystem.


Warning: It is illegal to copy or upload these packages from the remote compilation system. Contact the compiler vendor for information about licensing and restrictions. You must have written permission from the compiler vendor to copy Ada units.

Units that Apex requires in the lrm.ss subsystem are:

Packages that must be in the lrm.ss subsystem if the target compiler requires them are:

See the lrm.ss view of the sample RCI customizations for examples.

Creating the LRM Subsystem

1 . Create the view on the host that will contain the specifications for all LRM-predefined subprograms. This must be a working view in the LRM subsystem.

a . In the release subsystem:

2 . Create package Standard.

a . From your LRM view, use Tools > Shell to get a UNIX shell window. Run the following UNIX command to create an empty package Standard:

    Note: The filename requires the underscore (_) as a part of the name.

    This creates an empty package. When you code package System, the Apex Ada compiler builds package Standard from the values provided in the file rci_predef.spec in the compiler key.

    Note: Use the UNIX touch command. File > New > New File does not create an empty text file; it includes a prompt.

b . Create the Ada specification for package System (with File > New > New Ada) and enter the package information from your target compiler's LRM Appendix F into it.

c . Code package System. This generates package Standard from the information you specified in rci_predef.spec. At this point, package System may not be semantically correct, (for example, if you have not defined the required pragmas), but it will still be coded. Ignore compiler warnings which are related to undefined semantic characteristics of your target compiler. If you receive compilation errors, on the other hand, you have a choice: go on to the next step, or go back and define the semantic characteristics that are required. If you elect the latter option, clean standard_.1.ada, then retry step c.

3 . Stock the library (copy units with permission from the compiler vendor or type them in from the LRM) with the Ada specifications for all LRM-predefined units for the selected target machine, and code them. "Choosing Packages for the LRM Library" (below) discusses which packages to include in the library. Some predefined routines are required; others are optional.

Use the following steps to add a unit to the predefined library.

a . Open an Ada unit with the package name.

b . Type the LRM-defined contents into the unit.

c . Code the unit. (The units are codable at this stage of customization only if you can code package System and if these files do not contain any undefined pragmas and attributes. If this is not the case, you can code these units later.)

Building Host Library Views

Choosing Packages for the Predefined Library Views

A library view is a host view that contains Ada specifications that are part of the predefined target compiler environment. Such a view needs to be created with the RCI_HOST_ONLY and INTERFACE_ONLY switches set. You many choose to define multiple subsystems in the $APEX_BASE/ada directory to correspond with the target library structure, or you may decide to use the predefined subsystem to hold all host libraries. This is a decision you will have to make based on the complexity and structure (interdependence) of the target libraries.

Library views contain implementation-dependent packages provided in the remote compilation environment by other vendors. Such libraries frequently include math packages, operating system utilities, X system interfaces, etc.

Standard LRM predefined packages or vendor-supplied packages should be included in library views, including:

Units that Apex requires in the predefined.ss subsystem are:

See the predefined.ss view of the sample RCI customizations for examples.

For Ada 95 customizations, Apex requires that the units defined in Ada 95 annexes be, if they are supplied, in the relevant standard Apex predefined subsystem (distributed_systems.ss, information_systems.ss, numerics.ss, realtime_systems.ss or systems_programming.ss), according to the distribution outlined in the Ada 95 reference manual (RM 95 A(2)).

See the predefined views of the sample GNAT Ada 95 customization for examples.

Creating the Predefined Libraries

1 . In the release subsystem:

<rational_dir>/base/ada/predefined.ss

using File > New > New View with any RCI model, create a new RCI_Host_Only, Interface_Only view with the same name you used to create the LRM view:

Ignore messages about imports.

2 . Use Control > Show > Switches to change the value of COMPILER_KEY in <new_view>/Policy/Switches to the compiler key you defined for your customization.

3 . Use Control > Show > Imports to select and update the imports. First use Control > Remove Import to remove any existing imports, then use Control > Add Import to import the LRM view you created in the previous step. If you want to make changes, rather than deleting and then adding the import to the import file, use the following steps:

a . From the Imports window, select Navigate > Import Description.

b . Click Edit to make changes to the file.

c . Edit the imports for your customization.

d . Click Save to save those changes to the imports.

e . Click Close to return to the Imports editor.

4 . Use Control > Maintenance > Remodel to remodel the view. Use all default values. This resets the new view to the compiler key for your customization and updates the imports for the view.

5 . Stock the predefined library and code the units. (The units are codable at this stage of customization only if you can code package System and if these files do not contain any undefined pragmas and attributes. If this is not the case, you can code these units later.)

Repeat the above steps for any additional host library view needed by your customization in addition to the predefined.ss view.

Creating the RCI Customization Model

1 . In the following directory:

<rational_dir>/base/ada/model.ss

using File > New > New View with any RCI model, create a new view with the same name you used to create the lrm and predefined views:

rci_<arch>_<os>_<cust_name>.(ada83|ada95).<rel#>.wrk

Ignore any warnings about imports.

2 . Use Control > Show > Switches to change the value of COMPILER_KEY in new_view/Policy/Switches to the compiler key you defined for your customization.

3 . Use Control > Show > Imports to select and update the imports. First remove any existing imports, then import the lrm and predefined views you created in the previous steps.

4 . Use Control > Maintenance > Remodel to remodel the view. Use all default values. This resets the new view to the compiler key for your customization.

Note: be sure your model view imports all the host library views which are necessary parts of the predefined target compilation environment. The instructions above assume that you have used only the predefined.ss view.

Setting Compiler_Properties

The Compiler_Properties file in your compiler key directory includes information about your host and target environment. The Apex Object Management System (OMS) uses this information to determine whether it can execute certain customizable extensions to Apex and the RCI. It contains the following fields with the recommended values for RCI customization:

If necessary, edit this file to define the correct values for your customization.

Documenting your Customization

The README file in your compiler key directory provides information about the files used in your customization. This file helps you capture information that you need to maintain the customization or report problems. Keep it current!

1 . Create or update the README file for your customization.

2 . Use this file to answer the following questions about your customization:


Testing Your Basic Customization

This section describes the steps to check whether or not the customization has correctly built the LRM, predefined, and model views, and package Standard. This tests the customization only on the host.

1 . Use File > New > New Subsystem to create a test subsystem.

2 . Use File > New > New View to create a test RCI view in your test subsystem. Use the following options:

a . Model: use the RCI model you have created for your customization.

b . Host_Only: select this option, so the RCI does not attempt to handle library management before you have modified the scripts for your customization.

3 . Test a sample package.

a . Create and analyze a test package that contains a variable of type integer.

b . Use your cursor to select the variable of type integer and click on Visit.

Did you get the correct package Standard?


Customization Process Summary

This section outlines the steps that can be done to provide a customized RCI. The previous sections of this chapter have defined the steps in detail. This outline is expanded upon in following chapters.

1 . Collect documentation for your customization: vendor compiler and operating system manuals, vendor LRM, Rational manuals and specs.

2 . Create the compiler key view for your customization.

a . Choose a compiler key name for your desired target compiler. This name should identify the target platform, operating system, and compiler vendor. Follow the naming convention below:

rci_<arch>_<os>_<cust_name>.(ada83|ada95).<rel#>.wrk

b . Create the compiler key view in $APEX_BASE/ada/key.ss with the File > New > New View command (use one of the null models provided in $APEX_BASE/ada/model.ss).

c . Populate the Compiler Key view with copies of the shell scripts from the VADS (Ada 83) or GNAT (Ada 95) example RCI customization as a starting point for your customization.

d . Create and edit the specification files in the compiler key view. Make sure that they have the correct format: Apex 3.0 and later releases require RCI Specification file format. If you copied the specification files from an earlier release, run the command

e . Create the Compiler_Properties file in the compiler key view.

f . Create or update the README file for your customization.

g . Create the compiler and linker options files in the compiler key view (comp_option_line, comp_option_symbol, link_option_line, and link_option_symbol). You can create these files by copying them from a prior release, or by running the following command in an Apex shell:

3 . Create the LRM view.

a . In the following directory:

<rational_dir>/base/ada/lrm.ss

create a new Host_Only, Interface_Only view (using any RCI model) with the same name you used for your compiler key view:

rci_<arch>_<os>_<cust_name>.(ada83|ada95).<rel#>.wrk

Ignore any warnings about imports.

b . Edit the Policy/Switches file in the new view to change the value of COMPILER_KEY to the full path name of the compiler key view.

c . Edit the Imports/Description.cfg file in the new view to remove all imports.

d . Use Control > Maintenance > Remodel to remodel the view to use the new compiler key.

e . Create package Standard:

i From the LRM view, use Tools > Shell to get a UNIX shell window. Run the following command to create an empty package Standard:

    %  touch standard_.1.ada
    

    ii Create package System File > New > New Ada and enter the contents from your compiler vendor's LRM Appendix F information.

    iii Code package System. This generates package Standard from the template information.

f . Stock the library (copy units with permission or type them in from the LRM) with the Ada specifications for all LRM-predefined units from the selected target machine, and code the units.

4 . Create the predefined view(s).

a . In the following directory:

<rational_dir>/base/ada/predefined.ss

create a new Host_Only, Interface_Only view (using any RCI model) with the same name you used for your compiler key and lrm view:

b . Edit the Policy/Switches file in the new view to change the value of COMPILER_KEY to the full path name of the compiler key directory.

c . Edit the Imports/Description.cfg file in the new view to remove all imports.

d . Use Control > Maintenance > Remodel to remodel the view to your new compiler key.

e . Use Control > Show > Imports to import the LRM view you created in the previous step.

Repeat these steps for any additional host library view needed in addition to the predefined.ss view.

5 . Create the model view.

a . In the following directory:

b . Edit the Policy/Switches file in the new view to change the value of COMPILER_KEY to the full path name of the compiler key directory.

c . Edit the Imports/Description.cfg file in the new view to include the lrm and predefined views you created in previous steps.

d . Use Control > Maintenance > Remodel to remodel the view to your new compiler key.

6 . Test your customization.

a . Create a test subsystem.

b . Create an RCI test view.

c . Test a sample package that contains an integer variable.

d . Visit the integer variable and verify that it takes you to the right package Standard.


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