![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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:
- Getting Started
- Building Your Customization
- Testing Your Basic Customization
- Customization Process Summary
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 StartedCollecting 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:
- comp.spec, the grammar for the RCI Spec Language which is used in the specification files starting in Apex 3.0.
- translate, which will read in old format characteristics files and write RCI Specification Language files.
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
<rational_dir>/base/ada key.ss/ rci_<arch>_<os>_<cust_name>.(ada95|ada83).<rel#>.rel/ ...specification files, compiler options files, scripts lrm.ss/ rci_<arch>_<os>_<cust_name>.(ada95|ada83).<rel#>.rel/ model.ss/ rci_<arch>_<os>_<cust_name>.(ada95|ada83).<rel#>.rel/ predefined.ss/ rci_<arch>_<os>_<cust_name>.(ada95|ada83).<rel#>.rel/ rci.ss/ <arch>_<os>_<cust_name>.ada83.<rel#>.rel/ comp.spec translate
distributed_systems.ss/ rci_<arch>_<os>_<cust_name>.ada95.<rel#>.rel/ Ada95 specific annex information_systems.ss/ rci_<arch>_<os>_<cust_name>.ada95.<rel#>.rel/ Ada95 specific annex numerics.ss/ rci_<arch>_<os>_<cust_name>.ada95.<rel#>.rel/ Ada95 specific annex real_time_systems.ss/ rci_<arch>_<os>_<cust_name>.ada95.<rel#>.rel/ Ada95 specific annex systems_programming.ss/ rci_<arch>_<os>_<cust_name>.ada95.<rel#>.rel/ Ada95 specific annexWhen 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:
rci_<host_arch>_<host_OS>_<target_compiler_name> .(ada83|ada95).<apex_release_no>.relA compiler key name, as an example of this form, is
rci_sun4_solaris2_gnat.ada95.3.0.0.rel
Rational provides the following compiler keys in the <rational_dir>/base/ada/key.ss subsystem:
- rs6k_aix, sun4_solaris2, mips_irix5, hppa_hpux, or alpha_osf1 (in both Ada83 and Ada95 flavors for the host platforms).
- Example RCI customization compiler keys (VADS Ada83 and GNAT Ada95).
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:
- Create your compiler key view.
- Copy required compilation and library management scripts from a similar customization.
- Create the specification files, options files and Compiler_Properties file in the compiler key.
- Create the lrm, predefined, and model views.
- Create and code package System in the lrm view to create package Standard.
Building Your CustomizationCreating 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:
$APEX_BASE/ada/key.ss
Be sure to use one of the existing null models when you create the compiler key view, so that your compiler key view will have the correct initial structure, with no imports.
$APEX_BASE/ada/model.ss/ <arch>_<os>.(ada83|ada95).null.<rel#>.rel
- 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:
% $APEX_BASE/ada/rci.ss/<view
>/translate \ -source <new_compiler_key
> \ -destination <new_compiler_key
>\ -target_name <target_compiler_name
>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.
% apex check_rci_specification \ -directory <new_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:
- Standard (this is a special case; the RCI builds it from values you provide through templates. See Defining Package Standard Values.)
- System. This package must be included in the minimum customization.
- Calendar (Ada 83) or Ada.Calendar (Ada 95)
- Unchecked_Conversion (Ada83) or Ada.Unchecked_Conversion (Ada95)
- Unchecked_Deallocation (Ada 83) or Ada.Unchecked_Deallocation (Ada 95)
Packages that must be in the lrm.ss subsystem if the target compiler requires them are:
- Machine_Code (Ada 83) or System.Machine_Code (Ada 95)
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:
$APEX_BASE/ada/lrm.ss
using File > New > New View with any RCI model, create a new RCI_Host_Only, Interface_Only view with a name that matches the following template:
rci_<arch
>_<os
>_<cust_name
>.(ada83|ada95
).<rel
#>.wrk
Ignore any messages about imports.
- b .
Edit the file Imports/Description.cfg in the new view and remove all imports.- c .
Edit the file Policy/Switches to the new view and change the value of COMPILER_KEY to the compiler key you defined for your customization.- d .
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 refreshes the imports.- 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:
% touch standard_.1.ada
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:
- LRM predefined I/O packages
- Target-dependent packages such as those for tasking, condition handling, and runtime operations.
Warning: It is illegal to copy or upload these units from the remote compilation system. Contact your compiler vendor for information about your license and restrictions. You must have written permission from your compiler vendor to copy Ada units.
Units that Apex requires in the predefined.ss subsystem are:
- Direct_Io (Ada 83) or Ada.Direct_Io (Ada 95)
- Io_Exceptions (Ada 83) or Ada.Io_Exceptions (Ada 95
- Sequential_Io (Ada 83) or Ada.Sequential_Io (Ada 95
- Text_Io (Ada 83) or Ada.Text_Io and Ada.Wide_Text_Io (Ada 95)
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:
rci_<arch>_<os>_<cust_name>.(ada83|ada95).<rel#>.wrk
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:
- LANGUAGE: Ada
Specifies the language supported by compilation.
- ADA_DIALECT: Ada_95 (leave out for Ada 83 customizations)
- HOST_ARCHITECTURE: rs6k_aix, sun4_solaris2, hppa_hpux, alpha_osf1, or mips_irix5
Specifies the host architecture for your compiler and its components.
- TARGET_ARCHITECTURE: rs6k_aix, sun4_solaris2, hppa_hpux, alpha_osf1, mips_irix5
Specifies the target architecture for your compiler. This specifies the architecture for object files and executables in a view. (This must be the same as HOST_ARCHITECTURE regardless of your RCI target-compiler architecture.)
- REUSE_ATTRIBUTES: True
Controls whether or not a compiler can reuse its attribute files (for example, object files and Diana trees); if True, these files are reused when views are moved or copied.
- CLASS: Extended
Specifies the class of compiler customization, that is, which operations are supported through customization. (This must be Extended for the RCI.)
- RCI_VERSION: <target_compiler_name.version string>
Uniquely identifies the customization (if the first four letters are `vads' or `apex', the Apex Ada compiler will utilize built-in knowledge about the semantics of the target VADS or Apex compiler)
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:
- Customizer: who originally created the customization?
- Modification by: who has made changes to the customization?
- Version information: which releases of Apex, RCI, target OS, and target compiler does the customization use?
- List of Files: a list of all files in the keys directory. Each entry should contain the following information:
Testing Your Basic CustomizationThis 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.
Customization Process SummaryThis 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
% $APEX_BASE/ada/rci.ss/<view
>/translate \ -source <new_compiler_key
> \ -destination <new_compiler_key
>\ -target_name <target_compiler_name
>
- e .
Create the Compiler_Properties file in the compiler key view.
LANGUAGE: Ada ADA_DIALECT: Ada_95
(leave out for ADA 83 customizations)
HOST_ARCHITECTURE: rs6k or sun4_solaris2 or ... TARGET_ARCHITECTURE: rs6k or sun4_solaris2 or ...
(This must match HOST_ARCHITECTURE, regardless of your RCI target-compiler architecture.)
REUSE_ATTRIBUTES: True CLASS: Extended RCI_VERSION: <target_compiler_name.version>
- 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:
% apex check_rci_specification \ -directory <new_compiler_key
>
- 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:
rci_<arch>_<os>_<cust_name>.(ada83|ada95).<rel#>.wrk
- 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:
<rational_dir
>/base/ada/model.ss
create a new view (using any RCI model) with the same name you used for your compiler key, lrm and predefined views:
rci_<arch
>_<os
>_<cust_name
>.(ada83|ada95).<rel
#>.wrk
- 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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |