TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Key Features

Rational Apex® is an easy-to-use software-engineering environment that helps develop large, complex projects on time, within budget, and with superior quality. Apex offers:

A conceptual view of the Apex components is illustrated in Figure 1.

Figure 1 Conceptual View of Apex Components


About This Chapter

This chapter gives you an overview of Apex features. Topics introduced in this chapter are:


User Interface

Rational Apex provides a rich user interface that is customizable to the individual user, the work group, or the installation. Commands are accessed using an OSF/Motif(TM) style graphical user interface (GUI) or a text-based command line interface. Both the GUI and command line interface can be used at the same time.

Graphical User Interface (GUI)

The GUI is a full screen, color X windows application. Each window contains a set of menus related to the window. Most aspects of the windows are customizable including display (color/black-white/gray-scale,) menu contents, and default values.

Data entry is done via dialog boxes which provide a list of options whenever possible.

The GUI is tightly coupled with the online documentation allowing context-sensitive help at each step. In addition, all documents are accessible online for easy reference. Online documentation is indexed, easily accessible, and quickly navigated via hypertext links.

The Apex GUI is described in detail in Using and Customizing the GUI and the Online Reference.

Command-Line Interface

The command-line interface provides UNIX commands from a special UNIX shell window. Each command has an associated man page that documents its parameters and use. A command line interface window can be created by:

The command-line interface is described in detail in the Command Reference. and in the online man pages.


Software System Architecture

The architecture of a software system defines how the system will do the things it is required to do by:

Software systems can be organized into cohesive components with controlled interfaces between them. Each component exports only those portions of the interface that need to be visible to other components. The Apex import/export construct is an extension of the class/package model. Imports are similar to withs or includes. For Ada, exports are similar to specifications defining which objects are visible outside the package in Ada. For C/C++, exports are similar to objects defined as public.

Subsystems are the fundamental units of organization for software systems in Rational Apex. Each subsystem represents a component of a larger software system that can be developed, tested, and released independently. The library context of an object is either the Rational Subsystem (Apex/ClearCase) or the Apex/Summit view (Apex/Summit).


Subsystems and Views (Apex/Summit Only)

Two important features of Apex are subsystems and views. Detailed information on these Apex features can be found in the Concepts Guide.

Subsystems

Subsystems in Apex/Summit are composed of logical entities called objects. Each subsystem has an associated version control database, which is used to manage the versions of the objects. The version control database also provides facilities to coordinate multiple developers working in the subsystem in order to avoid conflicts. A subsystem is a section of a larger software system. In the UNIX file-and-directory hierarchy, a Rational subsystem is a directory with a .ss filename extension.

Views

In Apex/Summit, each subsystem contains a set of Summit/CM views. Each view is an alternative specification or implementation of the subsystem. A view contains actual files that represent the logical objects in the subsystem.

A view is a subdirectory inside a subsystem directory. This subdirectory provides a means of grouping certain files, or objects, for a particular project. A view contains specific version of the files in a subsystem. For example, you have a subsystem that contains three objects, rabbit.march, door.mouse, and hatter.mad. To build version 4 of a software product called TeaParty, your view might need files rabbit.march version 3, door.mouse version 8, and hatter.mad version 7, but not hatter.mad version 8, which might be used by another view. This example is illustrated in Figure 2.

Figure 2 Example of Different Views of a Subsystem

Apex also integrates the management of version control with the compilation information in a view to maintain consistency and to reduce the recompilation effects of version control operations.

Apex uses two types of views, either working views, which have a .wrk filename extension or release views, which have a .rel filename extension. Working views contain objects currently being developed and release views store release versions of software systems.

Working Views

Working views are areas used for development and integration.

Release Views

Release views represent the products of the development process that occurs in a subsystem. To provide flexibility for different methodologies, three different kinds of release views are provided: development, stable, and frozen.


The Summit/CM System (Apex/Summit only)

Subsystems are the focal point of the Rational Summit Configuration Management (Summit/CM) system. Summit/CM supports a check-in/check-out reservation system for the source files in a project and maintains a change history for each object in the project.

Summit/CM helps you:

Summit/CM is described in detail in Using and Customizing Summit/CM.

Version Control

Version control requires a special command to be executed before a file can be modified. Then, while a file is being modified by one developer, another developer cannot generally change it. Apex version control gives the developer control over this change process. The version control mechanisms track file changes, coordinate access to shared files, coordinate the work of multiple developers, and propagate changes. In general, each file in a view may be placed under version control. When a file is controlled, it must be checked out to be modified. Checking out a file reserves it for editing. When the file is updated and tested, it is checked in, making it available to other users.

Controlled and Uncontrolled Files

Files in views must be explicitly placed under Apex/Summit control for Apex to track changes in them and control access to them. Only files in views can be placed under Apex/Summit control.

The Apex/Summit Database

The Apex/Summit database is central to Apex version control. Apex maintains an Apex/Summit database that tracks a file's development by recording the changes made to each controlled file. Each time a file is checked in, a new version of the file is created in the Apex/Summit database.

Version Histories and Version History Families

When files are checked out, modified, and checked in repeatedly, the result is a time-ordered, numbered sequence of versions, called a version history. The Apex/Summit database maintains version histories by recording all changes made to every controlled file. The default version history family is named Common.

For example, File A in the following illustration has three versions, each one containing an image of the file as it appeared at the time it was checked in. The latest version of File A is identified as the simple name A. To access version 2 of File A, use the Control > Set Version Attribute command to set the file version to 2 for File A and then use the simple name, A to reference version 2 of File A. The version history for file A is illustrated in Figure 3.

Figure 3 Version History

Version History Families

A version history family is a set of version histories. A version history family includes at most one version history for each file in the subsystem. A version history family composed of the version histories of three files is illustrated in Figure 4. Version history families can be used to group together version histories that are related in some way. Each file under Apex/Summit control is a member of a named version history family. Version history families are properties of subsystems.

Figure 4 Version History Family

A view of the subsystem can be used to develop enhancements, fix problems in older releases, test the current version, or create new releases. A view is the method to specify which version of each file in the subsystem belongs in the view. Views are like filters in that they let at most one version of each file be in the view. In each subsystem, the Common version history family is used by default for controlling files.

Uses of Version History Families

In this manual, the Common version history family illustrated in Figure 4 is depicted as illustrated in Figure 5. "A 1 2 3 "is the version history of file A. Note there is no requirement to have the same number of versions for each file. Also, all versions of files (that have been saved) are contained within the database. A working view can be created using any combination of versions contained within the database. Version 2 of file A is simplified to A (2). Version 2 of file A from the Common version history family is simplified to A (Common-2).

Figure 5 Version History Family Representation in this Manual

An example of using different version history families is illustrated in Figure 6 . If in subsystem SS, view A and view B both contain version 2 of file W from the Common version history family, view A and B contain the same file. However, if view C contains version 2 of the file W from the Special version history family, it is not the same file.

Figure 6 Version History Families Example

Apex/Summit Full Version Name

Files that have different contents are placed in different version history families. By specifying three items, the file's version history family name which includes the subsystem name, the file name, and the version number, a version can be fully identified in the Apex/Summit database.

To specify version 2 of file A illustrated above, we use the format:

<full subsystem pathname> <file> <history> <version>

If we assume file A is in the my_sub subsystem, the complete version name is /home/my_dir.ss A Common 2


Design Concepts of Apex/ClearCase (Apex/ClearCase only)

ClearCase, a version control and configuration management tool comes in two flavors:Base ClearCase and UCM. Base ClearCase consists of powerful tools to establish an environment in which developers can work in parallel on a shared set of files, and project managers can define policies that govern how developers work together. UCM is one prescribed method of using ClearCase. UCM is available in ClearCase 4.0 or higher. More information on ClearCase can be found in Managing Software Project with ClearCase.

Apex/ClearCase is built so that any ClearCase action initiated from Apex/ClearCase results in the ClearCase cleartool command being run. The integration is lightweight to allow users access to all areas of ClearCase functionality while being independent of the ClearCase version.

The configuration management capabilities focus on tasks software developers are expected to perform. ClearCase administrative tasks, such as creating VOBs, Clearcase views, and metadata, backing up VOB data, etc. are done using ClearCase directly. ClearCase can be accessed using the CM > Native ClearCase GUI command or the cleartool commands from a shell window.

Apex/ClearCase uses the ClearCase terminology throughout the GUI and the command line commands. Apex/ClearCase assumes you are familiar with ClearCase. A quick review of ClearCase concepts may be found in Appendix B.


Rational Subsystems (Apex/ClearCase only)

Ada and C++ development is supported by Rational subsystems. When a Rational subsystem is controlled by making it an element in a ClearCase VOB, the following files and directories are controlled:

In addition to the above files and directories, the following are also controlled in a C++ Rational subsystem:

Note: A Rational subsystem can be created anywhere in a directory hierarchy except in another Rational subsystem —— subject, of course, to normal permission restrictions; however, it must be in a ClearCase VOB to be controlled.

Models

One important characteristic of a Rational subsystem is its model. A model is a Rational subsystem or an Apex/Summit view that serves as a prototype for a Rational subsystem. The model provides a base structure of subdirectories, policies (compiler options, target keys, etc., by way of switches), and a base set of Imports. For Ada, a model provides a standard set of imports that make package Standard and built-in Ada packages, such as Text_Io.2.ada visible. For C/C++, a model provides access to the standard C/C++ library. Apex/ClearCase provides a default model for programs that are compiled and run using the same platform architecture that Apex/ClearCase uses. For more information on Models, see Programming with Apex.


Apex/ClearCase Development (Apex/ClearCase only)

With Apex/ClearCase, you must create ClearCase repositories (VOB(s) and ClearCase views) for your Rational subsystems. Summit/CM views are not used inside of Rational subsystems. An integrated system is illustrated in Figure 7. The Apex/ClearCase features include:

Figure 7 Apex/ClearCase Session Running in a ClearCase Setview


Apex Access Control (Apex/Summit only)

Apex access control provides methods for controlling access to the objects in subsystems and views. Apex access control also provides management of UNIX permissions and groups for subsystems, views and the files within them. More details on access control can be found in the Concepts Guide.


Apex Editing

The Apex text editor is a full-screen text editor. Traversal browsing is supported. The general text editor is described in the Programming with Apex.

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 development and integration.

For Ada, language-specific editing and pretty-printing assist in following a consistent programming style, increasing productivity, and reducing maintenance problems. The Apex Ada editor is described in the Programming with Apex.

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 on-line Ada 83 Reference Manual for the Ada Programming Language or the online Ada 95 Reference Manual for the Ada 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 a C/C++ file 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.

More information about the C++ editor is provided in Programming with Apex.


Apex Ada Compilation Management (Ada only)

Apex manages the compilation contexts of all Ada programs within a library context. A compilation context includes switches, imports, and exports. In managing compilation, the Apex system:

All configuration management operations may be applied to language objects including being placed under version control. For more information about compiling programs under Apex, see the Programming with Apex and the Ada Compiler Reference.

Compiling a Program

Compilation can be done in any of set 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

Each C/C++ function is accessed from Ada code using the Interface pragma. Please see the Ada Compiler Reference for more information.


Apex C/C++ Build Management (C/C++ only)

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.

Detailed information on Build Management is found in the C++ Compiler Reference.

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, which are views for Apex/Summit or Rational subsystems for Apex/ClearCase. 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 (used to control Apex characteristics) 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:

Library contexts utilizing the standard C/C++ build keys and models are created by the File > New > Subsystem - Working and File > New > Subsystem - Release commands and copied by the File > Copy Object command. Generally C/C++ library context 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.

If using the Apex C/C++ compiler, C/C++ source files are compiled by running the Compile > Code command. The integration between 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 or by their subsystem-relative name.

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. For Apex Duo, 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 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, see Using the Apex Debugger.


Remote Development (Apex/Summit only)

The remote development facilities of Apex provide support for managing distributed development at different sites of a wide-area network, which are connected by NFS. Views of the same subsystem can be distributed to different sites enabling development, compilation, and testing to occur locally and requiring communication between sites only at synchronization points.

Remote development is discussed in detail in the Programming with Apex.


Keyword Replacement

Keyword replacement occurs as part of a number of different Apex commands and provides a flexible way in which users can customize Apex operations or get access to Apex information sources.

In its simplest form, keyword replacement provides a way in which strings containing special tokens called keywords are evaluated in order to produce result strings in which the keywords have been replaced by the names or attributes of Apex objects. For example, the keyword <subsystem> is always replaced by the name of the current subsystem. Apex keyword replacement also provides capabilities to:

Keyword replacement is discussed in detail in Programming with Apex.


Using Apex

Apex runs under the X Window System using a graphical users interface that is compliant with OSF/Motif(TM) style guidelines. The examples in this guide are based on the Motif Window Manager (mwm).

Apex includes extensive online documentation featuring context-sensitive help. All printed documents are available online in HTML and for printing in postscript. All online documentation is indexed, easily accessible, and quickly navigated via hypertext links. A glossary of Apex terms is available in the Concepts Guide.

To handle cases where a text-based interface is desired, Apex provides a command-line interface where commands are entered directly via the UNIX shell. The command-line interface allows you to:

This command-line interface is described in the Command Reference.

Apex provides UNIX-style manual (man) pages for all its text-based commands.


Customizing Apex

You can customize the Apex environment to suit personal or project needs by specifying:

Changes to the button bars can be done interactively using the GUI. Most environment changes are made by editing specific text files. Edit these files with the Apex editor or any UNIX text editor such as emacs, vi, or ed.

Complete directions on customizing the user interface can be found in Using and Customizing the Apex GUI.

Switches

You can control many characteristics of Apex's behavior through switches. The two kinds of switches are session switches and context switches. You can display either or both kinds with the Control > Reports > Switches command.

Note: Switches are discussed in detail in Programming with Apex and listed in the Online Reference.

Context Switches

Context switches apply to commands that are executed in, and objects that reside in, a specific subsystem or view (Apex/Summit). Each subsystem and view (Apex/Summit only) contains a switch file Policy/Switches and that file contains switches that apply only to the enclosing context.

There is a switch that corresponds to each option of every Apex command line commands. These commands are described in Command Reference.

Some switches do not correspond to command options because it would not be useful to be able to specify them on a command line.

Session Switches

Session switches are environment variables whose names begin with APEX_. They are set in the same manner as any UNIX environment variable. Session switch names are case-sensitive and are all uppercase. These are variables that must be set before the Apex session begins. An example session switch is APEX_DEFAULT_MODEL, which is the fully-qualified path name of the library context to use as the default model. Details on session switches are available in the Online Reference. under Switches > Session Switches.

Property Switches

Property switches, like Context switches, are also associated with a context, which is usually a Summit/CM view (Apex/Summit) or subsystem. They are used by Apex to manage various enclosing context properties, such as those associated with build management.


Optional Products

The Rational Apex environment includes a number of optional products which can be used to increase the power and scope of your development effort. Apex contains a list of the available optional products. Contact your Rational sales representative for more information on obtaining any of these products.

Table 1 Optional Products
Product Name
Description
TestMate
TestMate is a software test management system tightly integrated with the Rational Apex software development environment. TestMate provides tools to define test cases, generate functional and structural test cases, run test cases, perform test coverage analysis, and display the results. All files created during the test process can be placed under configuration management and version control.
RCI
The Rational Compilation Integrator (RCI) provides integrated development functionality for Apex. Integrated development is the process of designing, generating, and maintaining software on one machine that is compiled on another machine. Integrated development uses the process of remote compilation to control the target compiler and linker on the target compilation platform. The host platform and target (or remote) platform are connected by sharing files through a network server using the Network File System (NFS).
Ada Analyzer
The major goal of the Ada Analyzer is to locate areas of the user's code that can potentially be improved and to provide the information necessary to the user to make these quality changes.
AXI
Ada X Interface
SoDA
Rational SoDA is a SOftware Document Automation product which provides the capability of automating the process of documenting your software.
Rose
The Rose integration with Apex provides support for a close interaction between these two products. It provides for creation of Rational subsystems and views (Apex/Summit) directly from the Rose model, forward and reverse engineering and interactive visualization, allowing automatic generation of the Rose model from source code, two way navigation, and convenient command access from both Apex and Rose.
Summit/TM (Apex/Summit only)
Rational Summit/TM provides Task Management and Process Control functionality. Although especially tuned to the needs of software development, Rational Summit/TM is customizable and can be adapted to help monitor and control the work flow of many business activities.
Rational Exec Integration
Apex for Rational Exec provides embedded capabilities enabling the development of powerful, real-time systems. It provides all the functionality of the standard Apex development environment layered on the Rational Exec runtime.
Tornado Integration
Apex for Tornado is also designed to facilitate the development of advanced, real-time systems. Layered on the Wind River Tornado operating system, this product provides all the capabilities of the standard Apex development environment and toolset as well as the high-performance, real-time capabilities of Tornado.
LynxOS Integration
Apex for LynxOS is also designed to facilitate the development of advanced, real-time systems. Layered on the LynxOS operating system, this product provides all the capabilities of the standard Apex development environment and toolset as well as all the capabilities of LynxOS.


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