TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Defining Basic Characteristics

This chapter describes the basic operating characteristics that you must define for your customization. It includes the characteristics that describe package Standard, the remote operating system, and the target compilation system. Using the instructions in this chapter, you will be able to define compiler, operating system, and package Standard characteristics for a basic customization.

This chapter expands on the steps to create a customized RCI that were presented in Building A Basic Customization.

This section describes the following areas of the customization process:

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.


Defining Package Standard Values

This section describes how to define target compiler values in package Standard for semantic checking by the host.

To create the definition for package Standard, modify the file rci_predef.spec in the compiler key to specify the correct integer, float, and fixed types. The RCI automatically builds package Standard from the lists of objects when you code an Ada unit in a view which imports your LRM view if it has not previously been built. If you want to force the compiler to rebuild standard, clean the file standard_.1.ada in your LRM view. This can be a useful step during incremental development of your customizations rci_predef.spec file.

What Information to Gather

Documentation:

RCI Specification Language

RCI Specification Language is used for all of the specification files starting with Apex 3.0. We suggest that you use an editor with a parentheses balancing feature (Emacs is one such editor, and it is provided with Apex).

RCI Spec language is defined in the file comp.spec in your rci.ss view. The language has a simple, fixed format, where each production is completed inside a set of parentheses, leading to nested parenthetical expressions.

The overall format of any RCI specification file is shown in Figure 3, and an example of the rci_predef.spec file is shown in Figure 4.

Figure 3 Top Level Structure of an RCI Specification

There are five RCI Specification files which are part of a customization, corresponding with the five alternatives shown in Figure 3 above (rci_predef.spec, rci_pragmas.spec, rci_attrib.spec, rci_rep_specs.spec and rci_op.spec). Each specification file should have the structure shown above.

RCI Specification Language Notation

In figures which show RCI Specification Language,

Editing the Specification for Package Standard

The specification for Package Standard is built in the file rci_predef.spec in the compiler key.

An example of the rci_predef.spec file is shown by a simple example in Figure 4.

Figure 4 Example Package Standard Specification

Defining Integers

This section describes the specification of the integer types defined by the target compiler package Standard.

For each integer type you need to define, fill in the production for integer descriptor as shown in Figure 5, then take a look at the completed examples in the rci_predef.spec file included in the VADS and GNAT example customizations.

Figure 5 Integer Descriptor

Provide the following values for each integer type T:

Example Integer Types Specification

Figure 6 shows the integer types specification for the VADS example customization.

Figure 6 Example Integer Types Specification

Defining Floating Point Numbers

This section describes the specification of the floating point types defined by the target compiler package Standard.

For each floating point type you need to define, fill in the productions for float descriptor as shown in Step 7 and Figure 8, then take a look at the completed examples in the rci_predef.spec file included in the VADS and GNAT example customizations. Note that the two figures illustrate two kinds of floating point type specifications: IEEE floats (for which the characteristics can be computed by the Apex Ada compiler) and non-IEEE floats (for which the characteristics must be specified).

Figure 7 IEEE Floating Point Types Specification

Note: IEEE floats must have sizes 32 or 64.

Figure 8 Non-IEEE Floating Point Type Specification

Provide the following values for each non-IEEE floating point type T:

Example Floating Point Types Specification

The following example shows the floating point types specification for the VADS example customization. Figure 9 shows the specification without making the simplification that the floats are all IEEE. Figure 11 shows the specification that actually is used in the VADS customization.

Figure 9 Example Non-IEEE Floating Point Types Specification
Figure 10 Example Non-IEEE Floating Point Types Specification, Cont.
Figure 11 Example IEEE Floating Point Types Specification

Defining Fixed Point Numbers

This section describes the specification of the fixed point types defined by the target compiler package Standard.

Note: Duration is the only type you need to define.

For each fixed point type you need to define, fill in the productions for fixed descriptor as shown in Figure 12, then take a look at the completed examples in the rci_predef.spec file included in the VADS and GNAT example customizations.

Figure 12 Fixed Point Type Specification

Provide the following values for each fixed point type T:

Example Fixed Point Types Specification

Figure 13 shows the fixed point types specification for the VADS example customization.

Figure 13 Example Fixed Point Types Specification

Completing Your Specification for Package Standard

If your target compiler supports the used of Latin 1 characters then be sure and include USE_LATIN_1 in your specification for package standard after your declaration of integer types, floating point types and fixed point types. See Figure 4.

Testing Your Specification for Package Standard

When you have finished editing rci_predef.spec, you can test it for syntax by running the following command (in an Apex shell):

After editing rci_predef.spec and rebuilding standard, analyze a unit in an RCI view (with the correct model and compiler key) which declares an integer variable. Visit the integer type to ensure that it takes you to the correct Standard and that your changes took place.

Updating Package Standard

As you use your customization, you may need to make changes to the predefined characteristics, to add new types or to change declarations for existing types.

1 . Edit the file rci_predef.spec in the compiler key.

2 . In your lrm.ss view, clean standard_.1.ada.

3 . In your lrm.ss view, code package System. This causes the Apex Ada compiler to build package Standard.


Defining Operational Characteristics

What Information to Gather

Documentation:

Editing the Operational Characteristics Specification

Operational Characteristics include compilation rules command properties, compiler options and operational_data.

The specification for Operational Characteristics is built in the file rci_op.spec in the compiler key.

The overall format of the rci_op.spec file is shown in Figure 14, followed by definitions of each of the component parts of operational characteristics.

Figure 14 Top Level Structure of an Ada 83 Operational Characteristics Specification


Defining Target Compilation Rules

This section describes how to set the compilation rules in the file rci_op.spec. The compilation rules are included in the file rci_op.spec in your compiler key.

The production for compilation rules is shown in Figure 15.

Figure 15 Compilation Rules Specification

Definitions for each of the components of the Compilation Rules Specification follow. Include each rule in your specification only if it applies:

Fill in the production for compilation_rules as shown in Figure 15, then take a look at the completed examples in the rci_op.spec file included in the VADS and GNAT example customizations.

Example Compilation Rules Specification

Figure 16 shows the compilation rules specification for the VADS example customization.

Figure 16 Example Compilation Rules Specification


Defining Target Command Properties

This section describes how to specify command properties for your target compilation platform. The command properties are included in the file rci_op.spec in your compiler key.

The production for command properties is shown in Figure 17.

Figure 17 Command Properties Specification

The definitions of individual Command Properties are shown in Table 2.

Table 2 Command_Properties
Parameter
Type
Definition
COMMAND_LINE_CASE
Name_Case
Name_Case includes: Upper, Lower, where
Upper -> THIS_NAME
Lower -> this_name

MAX_COMMAND_LINE_LENGTH
Natural
Maximum command line length for the remote operating system.
CONTEXT_COMMAND
String
Command to change the remote context.
CODE_COMMAND
String
Basic command or script name to invoke the remote compiler.
LINK_COMMAND
String
Basic command or script name to invoke the remote linker.
LINK_UNIT_SPECIFICATION_KIND
Link_Unit_Specification_Type
Tells the customization whether the target linker expects the main unit name to be the Ada name of the main unit, or the name of the file containing the main unit; for example, link foo or link foo.ada. Possible values are Ada_Name or File_Name.
EXECUTABLE_OPTION_UNIT_SPECIFICATION_KIND
Link_Unit_Specification_Type
Tells the customization whether the value passed with the executable option should be the Ada name of the main unit or the name of the file that contains the main unit; for example, link -o foo or link -o foo.ada. Possible values are Ada_Name or File_Name.
SPEC_FILENAME_EXTENSION
String
Filename extension for a file containing an Ada spec.
BODY_FILENAME_EXTENSION
String
Filename extension for a file containing an Ada body.
EXTENSION_SEPARATOR
String
File format is:
<filename><EXTENSION_SEPARATOR><appropriate_extension>

ADA_NAME_SUBUNIT_SEPARATOR
String
In using subunit files, this string is used in lieu of '.' in forming target file names based on the ada names of subunits.
For example, if ADA_NAME_SUBUNIT_SEPERATOR = "_", and the customizer has defined a subunit file with filename_type ADA_NAME and extension "TEST", then when subunit A.B.C is compiled/linked, the RCI looks for A_B_C.TEST on the target compilation platform.

ADA_NAME_SPEC_SUFFIX
String
Similar to ADA_NAME_SUBUNIT_SEPARATOR, but is appended to the ADA_NAME of specs.
In the above example, if ADA_NAME_SPEC_SUFFIX is "_", then when A'SPEC is compiled/linked, the RCI looks for the file A_.TEST.on the target compilation platform.

ADA_NAME_BODY_SUFFIX
String
Similar to ADA_NAME_SUBUNIT_SEPARATOR, but is appended to the ADA_NAME of bodies. In the above example, if ADA_NAME_BODY_SUFFIX is "_", then when A'BODY is compiled/linked, the RCI attempts to retrieve the file A_.TEST.
COMMAND_ARG_SEPARATOR
String
Separator between command and argument; for example, " " is the separator on UNIX.
INTER_COMMAND_SEPARATOR
String
Separator between any 2 commands; for example, ";" is the separator on UNIX.
CASE_SENSITIVE
Optional Switch
Include for case sensitive; Omission indicates that case is ignored.
ADA_NAME_IS_LOWER_CASE
Optional Switch
Include if filenames based on the Ada name are lower case?
HOST_NAME_EQUALS_TARGET_NAME
Optional Switch
Include if RCI uses the same file name in the target directory as in the host view. Omit if RCI generates the target file names using the default naming strategy.
GENERATE_BATCH_COMPIL_COMMANDS
Optional Switch
Include if THE_COMPILATION_MODE is batch. If included, RCI writes Ada compile commands into the script file.

Example Command Properties Specification

Figure 18 shows the command properties specification for the VADS example customization.

Figure 18 Example Command Properties Specification


Defining Target Compiler and Linker Options

Apex/RCI invokes the target compiler and linker with options specified in the comp_option and link_option files in the host view on a per-compilation-unit basis. All options that appear in these files must have been declared in the RCI customization. The compiler vendor defines the compiler options, but you, the customizer, decide which options and what names to use for the identifiers that map to those options. The declaration of compiler and linker options forms a part of the operational characteristics specification, so it is found in the file rci_op.spec in the compiler key.

The Apex Ada compiler requires some additional files in your compiler key directory, which it uses to parse the comp_option and link_option files. The files are:

Once your options are declared in rci_op.spec, you can generate the files above with the check_rci_specification command in an Apex shell:

Note: You can customize these options now for the basic customization, or this can be done later in the customization process. Either way, you need to run check_rci_specification to generate the four files listed above in the compiler key before your customization is ready for use (unless you are using options declarations from an existing customization, in which case you can copy the options files from that customization into your compiler key).

What Information to Gather

Use the target compiler reference manual to obtain a list of valid compiler command line options. For each option, you need:

Specification for Compiler Options

Figure 19 shows the specification for compiler options.

Figure 19 Compiler Options Specification

The definitions for the components of Compiler Options are shown in Table 3, and the full specification of Option is shown in Figure 20 and defined in Table 4.

Table 3 Compiler Options
Parameter
Type
Value
EXECUTABLE_OPTION
String
Compiler/Linker option that names the executable file.
value should be "" if no such option exists.

EXECUTABLE_OPTION_IS_PRE_OPTION
Optional Switch
Include if the option goes before the unit name in the command line.
OPTION_SEPARATOR
String
The command line format of a compile/link command is
OPTION_HEADER
String
OPTION_ARGUMENT_SEPARATOR
String

The Specification for Option is shown in Figure 20.

Figure 20 Option Specification

The definitions for the components of an Option specification are shown in Table 4:

Table 4 Options
Parameter
Type
Value
OPTION_NAME
String
Target compiler text to designate the option. This is the text used in the target compilation command.
ACTIVE_PHASES
List of phases (Code, Link)
During which phases is the option legal.
SWITCH_NAME
String
This is the option identifier as it appears in the comp (or link)_option_symbol file.
ALWAYS_ACTIVE
Optional Switch
Is option always on by default?.
OPTION_TAKES_ARG
Optional Switch
Does the option take an argument?
IS_PRE_OPTION
Optional Switch
Should the option (and its argument, if any), be placed before the unit name in the command line?.

Example Compiler Options Specification

Figure 21 shows the Compiler_Options included in the VADS example customization (only a few of the options are included in this example). See rci_op.spec in the VADS customization compiler key view.

Figure 21 Example Compiler Options Specification

Updating Compiler and Linker Options

After you change options in an existing customization, you must rerun the check_rci_specification command to update the new options in the compiler and link options files in your compiler key directory.

Users can specify options on a unit by unit basis by modifying the comp_option_file or link_option_file in their views. See the RCI User's Guide for more information.

You can define option defaults by placing those values in the comp_option_file and link_option_file files in the model view for the customization. Existing views do not automatically inherit the new model, so users must remodel their existing views to get the default values.


Defining Target Operational Data

The Last Component to be defined in Operational Characteristics is Operational Data, consisting mostly of information about the target OS and filesystem characteristics.

The Specification for Operational Data is shown in Figure 22.

Figure 22 Operational Data Specification

The Operational Data components are defined in Table 5:

Table 5 Operational Data
Parameter
Type
Value
MAX_FILENAME_LENGTH
Natural
Maximum filename length for the remote operating system and compiler.
FULL_PATHNAME_LENGTH
Natural
Maximum pathname length for the remote operating system.
DIRECTORY_SEPARATOR
String
A fully qualified filename would be of the following format:

<DPREF>dir_name1<DS>dir_name2<DS>dir_ name2<DS>....

<DS>dir_name_n<DSUF><DUS>unit_name
Where
<DS> => directory_separator,
<DPREF> => directory_prefix,
<DSUF> => directory_suffix,
<DUS> =>
directory_unit_separator.
For example, for the VMS file, [EXP.TESTS.SUB]file,
<DS> -> ".",
<DPREF> -> "[",
<DSUF> -> "]",
<DUS> -> ""
DIRECTORY_PREFIX
String
DIRECTORY_SUFFIX
String
DIRECTORY_UNIT_SEPARATOR
String
USE_DEFAULT_DOWNLOADING
Optional switch
If Included, RCI chooses how to download files. If omitted, RCI downloads by calling the script rci_post_put in your compiler key directory.
CONNECTION_KIND
String
The kind of connection. Valid kinds are nfs_rsh, nfs_rcp.

Example Operational Data Specification

Figure 23 shows the Operational Data included in the VADS example customization.

Figure 23 Example Operational Data Specification

Testing the Operational Characteristics Specification

Once your specification for Operational Characteristics is complete, you can perform two levels of testing. To test the syntax of your specification, in an Apex shell run the following command:

You can perform a series of tests to check the correctness of your customization now, by creating host-target RCI views and attempting to code and link on target. You may find it helpful to set the rci_runon script to verbose, in order to better inspect the parameters it is being passed, and which it is in turn using to build the target command.

Once you have the basic commands working correctly, try setting various combinations of target options in the link_options_file and comp_options_file in your test view, both in the default line and on a file by file basis.


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