![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Migrating from VADS to Apex This manual discusses porting application software from VADS to Apex.
The following topics are covered here:
- A Brief Summary of VADS and Apex Library Structure
- From a VADS library To an Apex/Summit Subsystem/View
- Porting Small Applications
- Porting a More Complex Application
- Comparing VADS Commands To Apex Commands
- Considerations For More Complex Applications
- Compilation Differences
- Execution Differences
- VADS-Supplied Packages
- Appendix F
- Default Initialization with Address Representation Attribute Clauses
- Runtime Configuration
- Hints For an Easier Transition To Apex
A Brief Summary of VADS and Apex Library StructureAn application compiled under VADS is composed of one (or more) VADS libraries. A VADS library is a directory that has been initialized by the VADS a.mklib command.
VADS does not include support for configuration management or version control (Summit/CM). Users must provide their own.
Source code in one VADS library can contain references to source code compiled in other VADS libraries (using with's), if those other libraries are on that library's ADAPATH. The ADAPATH specifies the libraries that are to be made visible, and is usually the transitive closure of those libraries.
An application compiled under Apex is composed of one (or more) subsystems. A subsystem is a source control repository for a set of source files. The files of a subsystem are not directly used during software development. Instead, development is done in a view of the subsystem. A view contains a set of source files from the subsystem, each having a specific version. Views are the Apex mechanism for team development, version control and build management, and for maintaining build and compilation context. There are commands in Apex for creating subsystems and views as well as for performing version control operations such as check in and check out.
If a VADS library references another using the ADAPATH, then all the interfaces in the target library are visible, that is, they are imported to the referencing library. Apex provides mechanisms for a view to control what interfaces get exported to other views. The Apex equivalent to the VADS ADAPATH are a combination of view's exports and imports, which provide compilation unit visibility between subsystems. It is necessary to import only those views to which specific references are made, rather than the transitive closure of the imported views as required by VADS.
Apex provides a configuration management and version control (Summit/CM) system that is highly integrated with the GUI, the compiler, debugger and other tools. Apex is a development environment as well as a compilation system.
The program library structure of both systems is largely similar. However, there are crucial differences in the details. Those differences are the primary focus of this document.
From a VADS library To an Apex/Summit Subsystem/ViewSubsystems are the Apex mechanism for decomposing a software system into manageable components (see Developing a System Architecture). Under VADS, the Ada library is used for the same purpose.
Our examples assume that the software architecture has decomposed the system into components that are each represented by a VADS Ada library. The natural mapping is from a VADS library to an Apex subsystem.
The VADS to Apex porting effort involves creating a subsystem and view(s) for each VADS library in the VADS application and then migrating the sources into the subsystem/view.
In addition to creating and populating subsystems and views, an application's development and system build processes must also be ported. The development process is the engineer's day to day methodology for building the executables on the application. The system build process is the preparation of the application for release.
The following two examples discuss in some detail the mechanics of porting a VADS application to Apex. The first example is quite simple and the second is a little more complicated. The examples concentrate on the application development process. A full discussion of system building and release is larger than the scope of this document.
Porting Small ApplicationsConsider an application that has the following characteristics:
- It is in the VADS library, /usr/src/project.
- It has only one user, eng (engineer).
- All of its source files have the .a suffix.
- main_program is the name of the main unit.
- It was built using a.make with the verbose and files options:
a.make -v main_program -f *.a
To port this application to Apex, follow these steps:
- 1 . Create a subsystem and view for the application:
From the Apex GUI select File > New > New Subsystem and it displays a simple dialogue to create a subsystem.
From an Apex UNIX shell command line, use:
apex create_subsystem /usr/src/project.ss
Note: When a subsystem is created, you must use the complete pathname.
- 2 . Create a view:
From the Apex GUI, select File > New > New View to get a dialogue for creating a view.
From an Apex UNIX shell command line, use the create_working command:
apex create_working /usr/src/project.ss/eng.wrk
A view has many attributes or parameters whose values are initialized at creation time. Some of these parameters are obtained from a model view, which serves as a prototype. In the above create_working command the model is not specified and the value of the Apex session switch APEX_DEFAULT_MODEL is used.
- Is the view going to be used for embedded development or native development?
- Is the language Ada83, Ada95, or C/C++?
- Where should the disk space (storage) for the view be located?
Most important view attributes are presented as choices in the New View dialog in the Apex GUI.
These Apex commands follow Apex conventions for naming subsystems and views. The subsystem's name must end with the .ss suffix and must be a fully-rooted file name. A working view's suffix is .wrk by convention. Release views, created by the create_release command, end with .rel.
The Apex environment requires:
- that the name of the source file specify the fully rooted Ada name of the unit
- that only one unit appear per file
- that the file name or an Ada specification end with .1.ada
- that the file name for a body end with .2.ada if the unit is a body.
The Concepts Guide describes the foundation role that subsystems and views play in software system architecture and the software development, integration, and release process.
- 3 . Migrate the source files from VADS to Apex.
Apex provides a convenient tool to convert from foreign naming conventions into files containing Ada units in the Apex environment. This tool can be invoked as Compile > Maintenance > Import Text Files from the GUI or as apex migrate (or import_text_files) from the command line:
apex migrate -into /usr/src/project.ss/eng.wrk /usr/src/project/*.a
This command creates new Apex source files in the eng.wrk view from the source files in the VADS libraries. The units are also parsed and entered into the Apex Ada library.
The apex migrate command cannot process source files that contain a.app preprocessor commands. See the Preprocessor discussion for some suggestions for handling these files.
- 4 . Build the small application
After running s apex migrate on all the VADS source files (or after parsing all the Ada units), Apex has registered the units in the Ada library.
Just like VADS, only one command is required to compile and link the application. In VADS the command is a.make. Apex has the link command. In the Apex GUI, if you are in a directory view for eng.wrk, select the name of the main unit and click the link... button. From the command line, run the link command specifying the file name of the main unit:
link main_program.2.ada
The Apex compiler compiles any unit required to link main_program.2.ada, and then run the linker to create the executable main_program.
There is no a.make build utility for Apex; the build utility is built into the compiler.
Porting a More Complex ApplicationConsider a slightly more complex application.
- It is composed of three VADS libraries, lib1, lib2, and main_lib.
- The lib2 ADAPATH names lib1.
- The main_lib ADAPATH names both lib1 and lib2.
- The source is in /usr/src/user_id/lib1, /usr/src/user_id/lib2, and /usr/src/user_id/main_lib, where user_id is the user-ID of an engineer.
- All files end in the .a suffix.
Assume there is a team of engineers working on this application and each engineer can and does work on code in any of the VADS libraries.
From VADS Libraries to Rational Subsystem Views
We make the same assumption that we did for the example above, namely that the software architecture has decomposed the system into components that are each developed in a VADS library. As in the small application example, we maintain the existing software architecture by creating one Apex subsystem to correspond to each VADS library.
Building the executable program(s) of a software system must be done from a consistent set of views, one view from each subsystem. There are multiple methodologies possible for configuring views for development. One common methodology is to designate one view in each subsystem as the up-to-date good view. So instead of each engineer having their own view in each subsystem, this designated view can be used by anyone not making changes to the files in that subsystem.
To set up the initial environment, it is easiest to first build up-to-date good views and get them to work. Then individual engineers can copy any of these views they need to work on files in the subsystem.
- 1 . Create the subsystems:
From the GUI, select File > New > New View.
apex create_subsystem /usr/src/lib1.ss apex create_subsystem /usr/src/lib2.ss apex create_subsystem /usr/src/main_lib.ss
After creating the subsystems, cd into /usr/src to make typing the rest of the commands easier:
cd /usr/src
- 2 . Create the views:
From the GUI, select File > New > New View.
In this example we use a special user-id, solid, to designate the VADS libraries where the up-to-date source are maintained. We use this same naming convention for creating the Apex views (remember, our current directory is /usr/src):
apex create_working lib1.ss/solid.wrk apex create_working lib2.ss/solid.wrk apex create_working main_lib.ss/solid.wrk
- 3 . Change the imports for this architecture to reflect the ADAPATHs in the VADS libraries. This step can be done as part of new view creation if working in the GUI. First we have the view in lib2 import from lib1:
apex import lib2.ss/solid.wrk lib1.ss/solid.wrk
Then we have the main_lib view import from both lib1 and lib2 views.
apex import main_lib.ss/solid.wrk lib1.ss/solid.wrk lib2.ss/solid.wrk- 4 . Migrate the sources from VADS into Apex:
apex migrate -into lib1.ss/solid.wrk solid/lib1/*.a apex migrate -into lib2.ss/solid.wrk solid/lib2/*.a apex migrate -into main_lib.ss/solid.wrk solid/main_lib/*.a
- 5 . Build the application (main.2.ada is the main program):
cd /usr/src/main_lib.ss/solid.wrk apex link main.2.ada
- 6 . Copy the views for personal use.
With the initial instance of the application compiled and linked (and tested and working), each engineer can copy any or all of the solid views for their own use.
Apex provides the powerful copy_view command, for copying a set of related views. The copy_view command can be used to copy a single view or an entire configuration at once.
The first step in copying the entire configuration is to use the create_config command to create a configuration file that names each view in the architecture. Create the file /usr/src/solid.cfg, which has the following contents:
/usr/src/lib1.ss/solid.wrk /usr/src/lib2.ss/solid.wrk /usr/src/main_lib.ss/solid.wrk
Use this configuration file to copy the entire solid.wrk configuration as follows:
apex copy_view /usr/src/solid.cfg eng2.wrk
The copy_view command creates each of the views:
/usr/src/lib1.ss/eng2.wrk /usr/src/lib2.ss/eng2.wrk /usr/src/main_lib.ss/eng2.wrk
Copy_view preserves the import structure of the newly created views so that /usr/src/lib2.ss/eng2.wrk imports the newly created copy /usr/src/lib1.ss/eng2.wrk and not the original /usr/src/lib1.ss/solid.wrk.
Remember, it is not necessary for each engineer to have their own view of each subsystem. An engineer needs a view in the subsystems where he is modifying the sources and also in the subsystem where the program is built (linked). For all the other subsystems, the solid views can be used.
Comparing VADS Commands To Apex CommandsThe following list contains the commands provided with a VADS product. Each command is followed by a description of how to get corresponding functionality in Apex.
This table is a quick index into the list:
ada - the Ada compiler
Ada Compilation in Apex is broken down into 4 compilation steps with each step building on the previous one. An Ada unit can be in one of five compilation states. Here is a summary:
Initial State Compilation Step New State
Archived parse Source
Source analyze Installed
Installed code Coded
Coded link Linked
Linked none: run the program
Each compilation step is exposed in the Compile menu on the Apex directory and source viewer window in the GUI. Compile > Code generates an object file for the selected unit. Note that each compilation step performs any of the required previous steps. If you select a file that has never been compiled, for example, archived, and click on Compile > Code, the file is parsed, analyzed, and then coded.
The Compile > Semanticize command is a quick version of the analyze command. It does not look at all the dependency information, just the local unit. It is very handy for doing a quick check to see if the unit you are editing, compiles. Semanticize does not advance the unit to the installed state.
a.app - the Ada preprocessor
The Apex Ada Preprocessor is a subset of the VADS preprocessor, but should work in the majority of situations.
The apex migrate (or import_text_files) command can be used to move VADS source files into Apex views. However, apex migrate cannot process source files that contain a.app preprocessor commands. See the Preprocessor discussion for some suggestions for handling these files.
a.ar - create an archive library of Ada object files
Apex has a much more thorough treatment of packaging software in archives (or libraries) than VADS. An Apex view can be designated a library view by setting the BUILD_POLICY switch.
a.cca - (optional product) code coverage analyzer
The Apex Testmate product is used for code coverage. Refer to the Rational Testmate User's Guide using the Help > Manuals pull-down menu.
a.cleanlib - reinitialize library directory
The Apex clean command is the equivalent of a.cleanlib. From the GUI, select Compile > Maintenance > Clean.
The VADS a.cleanlib command was all or nothing. The Apex clean command lets you clean all units to a certain state, see the compilation states table, above. If you clean all the units to the installed state, all the object files are removed, but not the Diana intermediate files; re-coding all the units is quick.
a.cp - copy unit and library information
The Apex copy command (File > Copy Object from the GUI) copies source files, directories, views, or subsystems. The command takes into account the version control characteristics of the file. The copy/move matrix describes the source and destination interactions.
a.cvt - convert VOX object and executable formats
The VADS converter is a component of the Apex embedded products, known as the Format Converter. You can invoke it with Tools > Convert... or with convert from an Apex shell.
a.das - (disassembly) show generated code for units
To get disassembly of an Ada unit, select the unit in the GUI and select Compile > Show > Disassemble...
a.db - debug Ada and C/C++ programs
The Apex debugger is based on the VADS debugger. It can be invoked from the Apex GUI (see a.xdb below) or invoked from an Apex shell.
Note: Invoking the debugger to debug a native workstation program is different from invoking he debugger to debug an embedded program. Although these invocation methods are different, the debugger in either case behaves pretty much the same. For information about the embedded debugger, Refer to the Embedded Programming Guide for Rational Exec using the Help > Manuals pull-down menu.
When invoked from a shell, the debugger can be run in either line-mode or screen-mode, familiar to VADS users.
When you run the debugger from the GUI, if you set the View > Show Source toggle in the debugger log window, a source window is displayed within the log window. This GUI debugging environment is similar to screen-mode, including most of the single character commands.
a.du - summarize disk usage for Ada libraries
There is no equivalent of this command in Apex. You can use the Unix du tool. Since Apex enforces a strict naming convention and follows that convention everywhere, you can use the du output to accurately attribute disk usage.
a.error - analyze and disperse error messages
If you are interested in a.error, use the Apex GUI to invoke the compiler. It automatically highlights the errors in your source. The message-> and message<- buttons move from error to error. If you click on Help > Explain, the explanation for the error is displayed in the Message Window.
Remember to press the Edit toggle when you want to change the source code. Until you do this, the source is read-only.
a.header - print the information stored in a unit's header
Apex has no single command to display the environment that was in place when a unit was compiled.
a.help - invoke the interactive help utility
Apex has an excellent GUI-based help facility. In Apex all the manualsare in HTML format and can be viewed on-line by a web browser such as Netscape or Microsoft's Internet Explorer.
Apex also has a context-sensitive help facility. For example, you can select Help > On Context and you get a special cursor. Click that cursor on the item for which you want help. If you click it on a highlighted error in your Ada source, the reason for the error is displayed in the messages window. If you click on one of the menu buttons in an Apex window and then on one of the selections (and on one of the subsequent selections ...) you get help on the final item you select.
a.info - list or change VADS library directives
Switches are the Apex mechanism for specifying parameters about the view, compilation, etc. Use Control > Show > Switches to get the current settings of all switches. Control > Maintenance > Set Switch is used to change a switch setting.
a.ld - (prelinker) build and executable from compiled units
The Apex prelinker is invoked as one of the functions when you select Compile > Link in the GUI or use the link command in an Apex shell. Like the VADS a.ld command, Compile > Link searches the program library to find the closure of the selected unit. Since linking a program requires that all units be in the coded state, that is, object files must have been created, the compile codes as necessary. The Compile > Link command is more like a.make than a.ld in this respect.
Once all units are in the coded state, the linker is invoked with all the correct object files. For native development, the host linker is used. For an embedded development, Apex utilizes the same xlink cross linker as VADS.
a.list - produce a source code listing
From within an Apex editor window or a directory viewer, highlight the Ada source files you want to print and select on File > Print.
a.ls - list compiled units
This command provides a list of the units compiled in the current or specified Apex view.
a.make - recompile units in dependency order
The Ada compiler in Apex understands how to recompile all the units in a program's closure necessary to bring a program up to date. It also understands how to recompile these units in dependency order.
If you highlight the main unit of a program, for example, in the directory viewer and select Compile > Link in the GUI or the link command in the Apex shell. the compiler compiles all the necessary dependent units, in the correct order, so that an executable program can be linked.
The a.ld description above discusses this as well.
a.map - print VOX symbol table information
For Apex embedded products, the Tools > Symbol Info command from the GUI is the same as a.map. Also, from an Apex shell the following command works like a.map:
% apex_symbol_info VOX_file_name
a.mklib - create a VADS library directory
An Apex Ada library is an Ada view of a subsystem. The GUI command File > New > New Subsystem (create_subsystem) creates a subsystem. The GUI command File > New > New View (create_working) creates a new view in a subsystem.
Look at Porting Small Applications and Porting a More Complex Application to see some complete examples. The overview in A Brief Summary of VADS and Apex Library Structure describes some general Apex facilities and supplies links to other parts of the manuals.
a.mkvar - create or list an object file archive
Apex has a much more thorough treatment of packaging software in archives (or libraries) than VADS. An Apex view can be designated a library view by setting the BUILD_POLICY switch.
a.mv - move unit and library information
The Apex move command (File > Move Object from the GUI) moves source files, directories, views, or subsystems. The command takes into account the version control characteristics of the file. The copy/move matrix describes the source and destination interactions.
a.path - report or change VADS library search list
Apex has much more sophisticated mechanisms for importing and exporting objects from one Ada library to another than VADS.
In VADS you use a.path to import all the objects of an Ada library into the current Ada library. The similar command in Apex is the import command. Apex also supports the export command which lets you restrict the objects that other views are permitted to import. The imports of a view can be setup when the view is created.
There are additional import-related commands such as show_imports of a view (Control > Show > Imports), remove_import from a view, and more. These facilities are available from the Apex dialogue Control > Change View Properties...
a.pr - format (pretty print) Ada source code
The Apex pretty_print command formats Ada source code.
In the GUI, the Apex Text Editor has the Compile > Pretty Print command, which formats Ada source. There are a set of pretty printer switches that control how the pretty printer works. These are listed in the master index under Pretty Printing Switches. The Ada Editor describes the powerful Ada-specific features of the editor.
a.prof - (optional product) analyze and display profile data
The Tools > Profiling can be used for statistical profiling an executable program. For Apex native systems, either the UNIX prof or gprof may be used.
For Apex embedded products, the support is almost identical to VADS. The File > Run command has cross run options to enable profiling. The File > Run command for Apex Embedded systems invokes the apex_execute command, which can be used from an Apex shell.
a.report - file a deficiency or suggestion
There is an report script available with Apex that works like a.report.
a.rm - remove an Ada unit from library
In Apex, in the directory viewer, click on the unit or units you want to remove, then select File > Delete Object... This brings up a dialogue box. If you click on OK the units are removed. From an Apex shell the discard command may be used.
a.rmlib - remove a VADS library directory
File > Delete Object... is used to remove a view. See also a.rm. As described in From VADS Libraries to Rational Subsystem Views, an Ada view in Apex is the natural equivalent of an Ada library in VADS.
a.run - download and execute a program on an embedded target
From the GUI. File > Download brings up a dialogue for downloading an executable. After it is downloaded use File > Run to execute or debug it. File > Debug can be used directly to debug. The GUI File > Run command for Apex embedded systems invokes the apex_execute command, which also can be used from an Apex shell.
In an Apex directory viewer, if you select an embedded executable and then select File > Run, the program automatically downloads. An xterm pops up and the familiar download dots of the VADS a.run or a.db command are displayed. This xterm is also where output from the program is printed.
In Apex Embedded, if you have not selected a target prior to selecting File > Run, File > Debug, or File > Download then a target control dialogue pops up. If you want to explicitly set up the target to run/debug, that is, make the target known to Apex, select Tools > Target Control... Setting up the program to run and debug programs is described in "Getting Started" in the Embedded Programming Guides for Rational Apex Embedded products.
The following related commands can be executed from an Apex shell: apex_debug, apex_download, apex_execute, apex_profile, and apex_target_control. These and additional commands are described in "Command-Line Interface" in the Embedded Programming Guides for Rational Apex Embedded products.
a.symtab - display symbol information
There is currently no Apex command to provide symbol table information.
a.tags - create a source file cross reference for the vi editor
The Apex GUI editor for Ada understands every name in your source code, assuming the unit has been analyzed. So you can put your cursor on a name and click Visit to be taken to the declaration of the item. This includes the standard Ada packages delivered with Apex such as text_io.
This is a much more powerful facility than provided by a.tags. Most important, the Visit facility understands overloading and takes you to the declaration for the name you selected -- the same one the compiler used when it analyzed the code.
Apex has additional powerful facilities for Ada names in the GUI, notably Compile > Show > Usage lets you view all usages of an object (show_usage from an Apex shell). This feature lets you quickly evaluate the impact of changing an object's declaration by taking you to each usage of that object.
to_srec - convert VOX format to S-record format
See a.cvt. The Apex version of a.cvt has an S RECORD conversion option.
a.trace - (optional product) Tasking Logic Analyzer
Apex fully supports the Tasking Logic Analyzer. It is part of the Apex Analysis product.
This functionality is also available using an Apex shell as apex_trace_driver and apex_xtrace.
a.vadsrc - display versions and create library configuration file
a.view - provide aliases and history for C shell user
In the Apex GUI if you click on Tools > Shell you are brought up in an Apex xterm. This is pretty close to the functionality of a.view.
a.which - determine which VADS library contains a unit
Apex does not require a command like a.which. In the Ada editor in the GUI you can put the mouse cursor on any name, including a unit name, and click Visit to visit the unit. Once you are viewing the source of the unit, select Navigate > Enclosing to get into the directory viewer of the view that contains the unit.
An alternative method is select Navigate > Visit Ada Name which brings up a dialogue for visiting any name.
a.xdb - X window GUI for debugger
The Apex debugger has a GUI interface. If you are using the Apex GUI, the File > Run or File > Debug dialogues give you the option of debugging the program, which automatically brings up the GUI debugger interface.
The Apex debugger is based on the VADS debugger. There are two source display modes in the GUI. One is to use the Apex editor windows. The other is to let the debugger do the display. A VADS user will be most familiar with this second, show source, mode.
a.xref - print cross-reference information
Apex does not provide a cross-reference program. There are two very useful related commands in the GUI: Compile > Show > Usage, which displays the usages of a name and Compile > Show > Unused, which displays unused declarations.
As mentioned in the a.tags section, the Apex GUI editor has powerful navigation facilities for getting to the declaration of a name.
a.xtrace - graph tasking logic analyzer events
In the Apex GUI, when you select Tools > Trace... the Trace dialogue box comes up. Under the Output section if you click on Graphical, trace information is displayed graphically. This functionality is also available using an Apex shell as apex_trace_driver and apex_xtrace
In Apex the environment variable AUTOMATIC_TRACE used by VADS is replaced by APEX_TRACE_DRIVER. This should only be of concern if you are using the command-line interface.
xlink - cross linker
Apex and VADS use the same cross linker. The file that controls the linker's operation is called the Linker Options File in VADS. In Apex it is called the Linker Description File. The Linker Description File is described in "Linking and Executing Programs" in the Embedded Programming Guides for Rational Apex Embedded products.
Considerations For More Complex ApplicationsCircular ADAPATHs
VADS allows two (or more) libraries to reference each other in a circular manner. For example, library lib1 can have library lib2 on its ADAPATH and lib2 can have lib1 on its ADAPATH.
Apex supports the concept of mutual imports which can be used in this situation.
Duplicate Units
VADS allows the duplication of library units in different libraries. If library lib1 contains
unit lib_pack
, and library lib2 contains a different unit namedlib_pack
, a third library can reference either of them, depending upon which of lib1 or lib2 appears first on the third library's ADAPATH.Apex does not allow a unit name to be duplicated within a tower.
There are different approaches that can be used to remove or resolve the duplicate names:
- Isolate duplicate units into separate subsystems where each tower only imports one subsystem.
Create distinct Version History Families so that the duplicate files can be contained in one subsystem but with different version histories in the different views.
Default Access to Files
The default access to created files in Apex is rwxrwxr-x which is Posix compliant but not typically what is desired.
Solutions: Use
pragma Main (POSIX_COMPLIANT => FALSE);
or add theFORM
parameter to the create call. Usingpragma Main
is rather obscure, asMain
is usually a different unit. If you use theFORM
parameter, use the following syntax:FORM => "USER => Read_Write, GROUP => Read_Write, OTHER => Read"
or whatever you want. Note that it is"OTHER"
not"OTHERS"
(the usual UNIX usage).Creating Existing Files
VADS allows you to create a file that already exists if your mode is Out_file. In Apex, Posix access defaults to no replacement, so you get a Use_Error if you attempt to create a file that already exists.
Solutions: Either catch the exception and open the file or add the FORM parameter,
FORM => "REPLACE => TRUE",
to the create call.Preprocessor: VADS and Apex
The Apex Ada Prepocessor handles a subset of the VADS a.app command. We expect almost all source files containing a.app preprocessor commands to work with the Apex Ada Preprocessor. If the preprocessor has been used to parameterize the source for host/target dependencies, you can create new Summit/CM version histories in the appropriate views for those hosts and targets.
apex_migrate
The program apex_migrate is available to help migrate VADS source that contains a.app preprocessor commands to Apex. The program does not work 100% of the time, but it should work in most cases. Apex_migrate is invoked from the command line in an Apex shell.
If apex_migrate does not work, then the strategy for moving files with preprocessor commands into Apex is to first make sure there is one Ada unit per source file and then rename each source file to follow file naming conventions described in the Apex Ada Preprocessor invocation section.
The apex_migrate command takes as input a set of files. For each file, it determines how many compilation units the file contains, breaks the file up so that there is only one compilation unit per file (as Apex requires), and gives each fragment the name required by Apex.
Unlike the apex migrate command, apex_migrate does not parse the input file. It locates the boundaries between compilation units by searching for specific keywords and counting ENDs. This approach has advantages and disadvantages. It means that apex_migrate can succeed on files containing minor syntax errors or preprocessor directives. On the other hand, if the BEGINs and ENDs do not match or if complex preprocessor syntax is used, apex_migrate might get confused. For example, given a file containing the following, apex_migrate does not detect that there are two compilation units:
#if $Extra_Parameter then procedure P (x : integer := 0) is #else procedure P is #end if; begin null; end; procedure Q is begin null; end;
apex_migrate divides the input files at compilation unit boundaries. Each piece is given a name ending in .app or .ada depending on whether that piece contains any preprocessor syntax.
The apex_migrate command line contains a list of files to be migrated and options.
apex_migrate [options
]list_of_files
The position of the options on the command line has no effect on their meaning. The options are:
apex_migrate messages are not in the same format as those of other Apex commands. As this command matures, its messages will adopt the standard Apex format.
Compilation DifferencesPredefined Types
Predefined types in Apex and VADS are compatible with the exception of
Standard.Tiny_Integer.
To comply with the Ada 95 Standard, replace the use ofStandard.Tiny_Integer
withInterfaces.Integer_8
.Directives and Switches
There is a basic correspondence between VADS INFO directives and Apex Switches. Both are used to configure the compiler.
'Ref of Constants
In machine code insertions, VADS permitted references of the form
constant'ref
in a context where a memory operand was required. For example, the following code will compile and execute as expected using VADS,
S: constant boolean := true; Procedure Test_S(v: out boolean) is begin code_2'(lda, T0, S'Ref); code_2'(ld_b, T1, base(t0)); code_2'(move, V, T1); end Test_S;
Under Apex, the reference to
S'Ref
will lead to a compilation error because Apex does not create a concrete representation (a physical memory location) for scalar constants. In most circumstances, the workaround is to declare the constant as a variable:
S: boolean := true;
Execution DifferencesDefault Permissions On Text_io Created Files
The default permissions for created files in Apex is rwxrwxr-x which is Posix compliant. The default permissions for VADS is rw-rw-r--.
Use the FORM parameter to the create call to supply permissions, for example:
FORM => "USER => Read_Write, GROUP => Read_Write, OTHER => Read"
Note: It is
"OTHER"
not"OTHERS"
(the usual Unix usage).Creating Existing Files
VADS lets you create a file that already exists if your mode is Out_file. In Apex, Posix compliance defaults to no replacement so a Use_Error exception is raised. You may either catch the exception and open the existing file or add the form parameter to create the call:
FORM => "REPLACE => TRUE"
Sequential or Direct IO
There are a few minor differences in VADS and Apex for handling files of bytes. For example, if you declare a Direct_Io file with a 512 byte record size:
IO_BLOCK_SIZE: constant := 512; subtype io_block is bytes(0..IO_BLOCK_SIZE - 1); type io_block_ptr is access io_block; package block_io is new direct_io(io_block);
And then open the file and get the size, VADS rounds up if there is a remainder while Apex rounds down;
Block_Io.Siz
e on a 513 byte file returns 1 for Apex and 2 for VADS.Apex May Reorder Record Field Declarations
The layout of a record generated by the Apex compiler may not place the fields in the same order as declared by the record type. This can be overridden with a rep spec.
Address + Integer
The following code is accepted by VADS but is ambiguous in Apex:
a : system.address use system; begin a := a+1;
a := a + integer'(1);
Tiny_Integer
Tiny_Integer
isShort_Short_Integer
in Apex.Unsigned_Tiny_Integer
is available inpackage Unsigned_Types
.Standard_Error
Apex Ada83 does not support
Text_Io.Standard_Error
. Apex Ada95 does.Compiling with Checks Suppressed
VADS-Supplied PackagesVADS predefined packages are provided with Apex. Some of the directories are restructured and file names have been changed to follow the Apex conventions.
The following subsystems have been created in Apex that contain Ada source code usually supplied with VADS.
$APEX_BASE/ada/rts_vads_exec.ss
This subsystem contains the VADSexec interface to the RTS.
$APEX_BASE/ada/rational.ss
This subsystem contains the interface to the runtime system (RTS). Many of the files in this subsystem are from the directory standard that is supplied with VADS.
This subsystem also contains two files from the VADS standard library, language.1.ada and unsigned_types.1.ada.
$APEX_BASE/ada/vads_compatibility.ss
This subsystem contains subdirectories named standard, verdixlib, publiclib, and usr_conf, It also contains the units from those directories from VADS that were not moved to any of the other subsystems listed above.
Importing the VADS-Supplied Packages
Most VADS libraries have the VADS libraries standard and verdixlib on their ADAPATHs. So most Apex views containing VADS source code need to import the rational.ss, and vads_compatibility.ss subsystems.
Applications that have vads_exec on their ADAPATH need to import the rts_vads_exec.ss subsystem.
Appendix FPragmas
Address Clauses
In embedded VADS programs, Ada address clauses for with static addresses are represented by a linker group to prevent overlapping use of the memory associated with address clause variables. This feature is no longer supported by the Apex compiler. The Apex compiler allocates a pointer to the address specified in the address clause and all accesses to the variable are implemented as indirect references through this pointer.
In some circumstances the optimizer is able to optimize away the pointer and make references directly to the specified address. There is no mechanism to assure that the specified memory address isn't allocated by the linker to some other part of the user program.
Default Initialization with Address Representation Attribute ClausesDefault initialization of an object with an address representation attribute clause is different in Ada 83 versus Ada 95. Default initialization for an object may be either implicit initialization as required by the language, or explicit initialization in the data type definition. An address representation attribute is a
"for x use at ?"
clause in Ada 83 and a "for pragma Initializex'address use ?" clause in Ada 95.Implicit default initialization occurs in either Ada 83 or Ada 95 for access types, discriminants of constrained discriminated subtypes, and in Apex 3.0, for filler "gaps" between record or array components. Filler gaps must be initialized because Apex 3.0 code does record comparisons by comparing two data regions without regard for where the data is stored.
Explicit default initialization occurs when a default assignment is specified for a type definition component.
In both Ada 83 and Ada 95, normal objects are always default initialized.
However, when an address representation attribute clause is present, Ada 83 and Ada 95 differ. Ada 83 rules permitted an implementation to ignore any default initialization (implicit or explicit) of an object with an address clause. VADS and Apex 83 both chose to not perform default initialization when an address clause is specified for an object. Apex Ada 83 added the non-standard "
pragma Initialize"
to force default initialization if desired by the user.With Ada 95, the language designers chose to require default initialization even when an address clause is specified for the object. However, the language designers also provided the alternative. Default initialization will not be performed for any object for which
pragma Import
is specified, RM B.1(24).Unfortunately, this means that when converting Ada 83 to Ada 95, all cases where an address representation attribute clause is applied to an object must be examined, and if there is default initialization, the code must be changed appropriately.
For example, consider the following type definition:
type int_pnt is access integer ; type rec is record a : int_pnt ; -- implicit initialization of all access types b : integer := 3 ; -- explicit initialization in the type end record ;
In Ada 83, the following object declaration will have no default initialization:
val_no_init : rec ; for val_no_init use at system.address(16#0A003300#);
In Ada 95, a pragma must be added to have no default initialization:
val_no_init : rec ; for val_no_init'address use system.storage_elements.integer_address(16#0A003300#); pragma Import (Ada, val_no_init) ;
In Ada 83, the following object will have default initialization:
val_init : rec ; for val_init use at system.address(16#0A003300#); pragma Initialize(val_init); -- Apex pragma, non-portable
In Ada 95, the pragma must be removed to have default initialization:
val_init: rec ; for val_init'address use system.storage_elements.integer_address(16#0A003300#);
Note that
pragma Import
does not generate a symbol reference because it uses an "Ada" import with an address clause specified. If"pragma Import(C,val_no_init)"
were used, then there would be a symbol reference that would have to be satisfied during linking.
Runtime ConfigurationIn VADS the runtime system is configured by modifying the body of the package
V_Usr_Conf
in the file usr_conf/v_usr_conf_b.a, and adding a WITHn INFO directive to the library specifying that the object file for that package body be included in any subsequent link.To configure the runtime system in Apex, create a view of the base/usr_conf.ss subsystem and modify the package bodies of
V_Usr_Conf, Real_Time
, andCalendar_Configuration
, as needed. IfReal_Time
orCalendar_Configuration
are modified, they should be named in awith
statement in the context clause of the body of V_Usr_Conf so that the corresponding object files will be linked into your application.Import this view into the view containing the main program procedure for your application. This causes the modified body of
V_Usr_Conf
and its closure to be included in any links of the main program.
Hints For an Easier Transition To ApexThe following are a few tips that may help new Apex users transition from VADS to Apex, and provide some ways to speed up your work.
Basic Command-Line Commands
There are some basic Apex command-line commands that are particularly useful. Note that you do not need to prepend each command with apex, for example you can type visit instead of apex visit.
- To bring up a directory editor for the current directory:
% visit . #where "." is $cwd
- To bring up an Ada object editor for a file:
% visit foo.2.ada
- To compare files:
Select the two items, and click on Control > Show > Differences.
- To see how a file differs from the previous version:
Select only that single file and do Control > Show > Differences.
- To change imports from the command line:
% vi Imports/Description.cfg % apex import -refresh .
- To create a view from the command line:
% cd subsystem % apex create_workingview_name
- To copy a view:
% apex copyfrom_view to_view
- To place all Ada files in a directory under Summit/CM control:
% apex control -note "commentary" *.ada
- To hack in a quick change to a file without using the Ada object editor:
% vi foo.2.ada % analyze foo.2.ada
- To duplicate functionality of a.which:
To code everything in a view:
% % apex codeview_name
To blow away the object code for a view and recompile:
% apex clean . # where "." is $cwd % apex code .
To see all legal Apex commands:
% apex
To see a list of all available Apex man pages:
% man apex
Useful Key Bindings
The following is a list of some useful key bindings for new Emacs users.
Note: Many other tools use the Emacs bindings so your best bet is to give in and learn Emacs ("Resistance is futile!").
These are for use in any text field in any Apex dialog box.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |