TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Unit and File Development

This chapter discusses the concepts of unit and file development —— editing, compiling, and debugging. It includes the following topics:


The Problem

Once the concepts of version control and configuration management are understood, The process of creating and developing individual files must be understood. Apex provides tools to aid editing, compiling, and debugging units and files.


Apex Editing

The language-specific editors are powerful editors designed specifically for writing and editing Ada and C/C++ source code. To help the users program more efficiently, the editors include features for language-specific editing, pretty-printing, syntactic and semantic analysis, and traversal browsing in Ada and C/C++. The editors and debugger are integrated to facilitate rapid code develoment and integration.

Language-specific editing and pretty-printing assist in following a consistent programming style, increasing productivity, and reducing maintenance problems.

Syntactic and semantic analysis highlights errors and supplies error messages that help the users correct programs immediately. If more help is needed in understanding an error, the user may go to the relevant page of the Apex on-line Reference Manual for the Ada 83 Programming Language or Reference Manual for the Ada 95 Programming Language.

Traversal browsing in Ada allows the user to go to an object's definition or to all the places where an object is used in a program. Traversal browsing in C/C++ allows the user to go to an include file containing a variable's definition or to a file containing a function's declaration. Exploring programs in this manner aids understand them. This is especially true for complex programs where the user is not the original developer.


Apex Ada Compilation Management

Apex manages the compilation contexts of all Ada programs within a library context, which is an Apex view (Apex/Summit) or a Rational subsystem (Apex/ClearCase). A compilation context includes switches, imports, and exports. In managing compilation, the Apex system:

For more information about compiling programs under Apex, see the Programmer's Guide, C/C++ Compiler Reference Guide, and the Ada Compiler Reference Guide.

Compiling a Program

Compilation can be done in any of the library contexts that are being developed. The following can be compiled using the Compile > Code command:

Linking a Program

For Ada Programs

Any parameterless procedure can serve as the root of an Ada program that can be linked to produce an executable. There are some special pragmas that can be applied to units that are to be linked to produce executables, such as pragma Main. One thing the presence of pragma Main does is to mark the unit explicitly as a main procedure that is to be linked.

If main procedures contain a pragma Main (usually in the body), then a library context or subdirectory can be specified in a Compile > Link command and all contained procedures that have pragma Main will be linked as a result.

For Ada Interfacing to C/C++ Programs

Programs written in more than one language must have the main program written in Ada. Each C/C++ function is accessed from Ada code using the Interface pragma. Please see the Ada Compiler Reference Guide for more information.


Apex C/C++ Build Management

Apex Build Management for C and C++ provides facilities for the definition, management and customization of build environments. In addition to the general facilities for the definition of build environments, Apex Build Management also provides standard models of build environments which can be used with little or no modification.

Standard Models for C/C++ Build Management

Standard models for C/C++ build management provide an "out-of-the-box" solution which supports the common build activities of compilation, construction of libraries, and linking of executables. In addition, the standard models provide their own methods for customization which are less complex than constructing a build management model from scratch.

The standard build management models provide the following:

Basic Concepts

This section presents a brief overview of how the standard C/C++ build management facilities are used to support compilation and other activities.

All build activities occur in library contexts.The specific characteristics of build activities in a library context are determined by the library context's build key which is specified by a switch of the same name in the library context's switch file. The build key is usually derived from the model which was provided when the library context was created. The standard models for C/C++ build management are based on standard build keys which contain the following:

For Apex/Summit, views utilizing the standard C/C++ build keys and models are created by the File > New > New View - Working and File > New > New View - Release commands and copied by the File > Copy Objects command. For Apex/ClearCase, Rational subsystems utilizing the standard C/C++ build keys and models are created by the File > New > New Subsystem command and copied by the File > Copy Objects command. Generally C/C++ library contexts are created using the default C/C++ model which is available in the session switch APEX_CPP_MODEL. When a library context is created with a standard C/C++ model, all makefiles and directory structures required by the build system are created.

C/C++ source files are usually created by either the File > New > New C or File > New > New C++ commands. These commands create C/C++ header and source files with initial contents that are based on special prototype files. C/C++ files may also be copied into library contexts by Apex commands or by UNIX shell commands. Regardless of how files are created, makefiles and related directory structures are updated appropriately by Apex prior to running any build commands. C/C++ source files are compiled by running the Compile > Code command. The integration between Apex Build Management and the Apex C/C++ compilers automatically manages the dependency information that is used by make to detect obsolescence of object files.

C/C++ source files may directly include any header file within the same library context. Header files in other library contexts may only be included if architectural relationships have been established. Namely the library context containing the header file must export the header file and the library context containing the include must import the library context which exports the header file. Within include directives which satisfy architectural relationships, header files may be named either by their simple name (e.g. #include "file.h") or by their subsystem-relative name (e.g., #include "subsystem/file.h").

Entire library contexts may be compiled by running the Compile > Code command on the library context itself. Compiling a library context causes all source files in the library context to be compiled and in addition creates any required libraries. The creation of libraries is controlled by the build policy associated with the library context. Different build policies are defined by the standard build keys to allow libraries to be built with different contents or allow externally constructed libraries to be managed. By default, when libraries are constructed all object files are checked and regenerated if they are obsolete including the object files associated with template instantiations.

Prior to linking a main program, the source file containing the main entry point must be registered by running the Compile > Maintenance > Register Main Program command. Actual linking occurs when the Compile > Link command is run on the registered main program file. The closure of a main program is the set of object files, libraries and option settings which must be passed to the linker in order to link the main program. The closure of a C/C++ main program is computed by first identifying appropriate library contexts and then querying library contexts to determine the contribution which each library context will make to the overall closure. Support is also provided for linking C/C++ code in the closure of Ada main programs.

All Summit/CM operations may be applied to C/C++ files. C/C++ files may be placed under version control. When C/C++ files are created, deleted, or copied between library contexts by Summit/CM operations, all appropriate makefiles and directories are automatically updated.

A number of mechanisms are provided for customization of the standard build operations. The customization operations allow standard operations to be augmented or completely redefined.


Debugging

The Apex debugger helps in analyzing the behavior of programs as they run. The Apex debugger provides commands to:

For more information on debugging, see Using the Apex Debugger.


Creating a New Unit or File

Each unit or file in a software system goes through a creation process. There are two basic ways to create a new unit or file. The choice is based on personal preferences. One method creates the unit or file, tests it, and then controls it as illustrated in Figure 24.

The other method is to create a controlled unit/file, check it out, edit and test it, and then check it in as illustrated in Figure 25.

Figure 24 Create an Object Method 1 - Create, Edit and Test, Control

Figure 25 Method 2 - Create Controlled, Check Out, Edit and Test, Check In


Normal Unit/File Development

Once a unit/file is controlled, a typical unit/file development update cycle consists of the steps in Figure 26 and Figure 27.

Figure 26 Normal Unit/File Development (Apex/Summit)

Figure 27 Normal Unit/File Development (Apex/ClearCase)

For Apex/Summit, the Control > Check Out, Control > Check In and Control > Update Objects commands are explained in detail in Using and Customizing Summit/CM. For Apex/ClearCase, the CM > Checkin, and CM > Checkout commands are explained in Getting Started and the contents and format of the config spec file are defined in the ClearCase User's Guide.


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