17 Porting Assistant

This chapter provides an overview of the Porting Assistant's features and capabilities. For more detailed information on how to use this tool, choose Help: On Porting Assistant. You can print Help topics using the HyperHelp Viewer.

The Porting Assistant identifies source code that might not compile or run on Digital UNIX Alpha systems. Using the Porting Assistant, you can choose from among a variety of code checks. You can then browse the resulting diagnostic messages in the Builder or editor. Online Help is available on specific diagnostic messages as well as the porting process itself, including porting tips.

Figure Figure 17-1 shows the Porting Assistant main window.

Figure 17-1: Porting Assistant Main Window

Key elements are the major window panes running from the top to the bottom of the window:

Configuration area: Displays basic information about the current project and working directory.
Check definition area: Provides the features for selecting the type of check from the Check options menu. The work area changes contents depending on your choice. Use the toggle buttons, Add and Delete buttons, and list boxes to define the parameters of the check.
Execute check button: Click on this button to begin the check operation.
Information area: Displays information messages and Quick Help on menu items when you press and hold MB1 on the item.

17.1 Summary of Features

The Porting Assistant does the following:

Supports applications written in C, C++, FORTRAN 77, and FORTRAN 90 that run on other UNIX systems and proprietary systems such as the OpenVMS operating system.

Uses existing makefiles or information you provide to determine which application source files to check.

Generates diagnostic messages in the following areas:
- ifdef Code: Conditional code that might also need a Digital UNIX branch.
- Include Files: #include references to files that do not exist.
- 32-Bit Dependencies: Locates C files that might contain 32-bit dependencies.
- Function Calls: Calls to library functions that lack definitions or do not match Digital UNIX definitions.
- Parallel Directives: Maps Fortran compiler parallelizing directives to equivalent Digital UNIX directives.
- Platform-Specific Assumptions: Calls to library functions with different semantics on Digital UNIX.
- Makefiles: Verifies the syntax and structure of your application makefile, verifies that the actions invoked by the makefile exist, and checks a small class of actions (cc, ld, rm, f77, f90, and ar) for differences with other platforms.

Provides pushbutton navigation of diagnostic messages, including online Help on specific diagnostic messages, and quick display of associated source code in your default editor.

Provides features that let you filter out diagnostic messages individually or as a class based on your own needs and understanding of your application's porting requirements.

Provides features that identify an unresolved or multiply-defined function as well as the shareable and archive libraries on Digital UNIX that contain the definition of the function.

Provides features that examine all the function calls in a C or Fortran 77 application. It reports whether the function has a definition and, if so, whether the definition is specific to one of the UNIX operating systems. Furthermore, for any language, you can access features that identify equivalent Digital UNIX functions, if they exist. In the case of Fortran, you can map older LINPACK and EISPACK math functions to their equivalent LAPACK functions.

Supports searching for Fortran Digital Extended Math Library (DXML) functions using one or more keywords from the function's man page description.

Provides online Help on the porting process and porting tips.

17.2 Starting the Porting Assistant

You can start the Porting Assistant in several ways:

Use the command line.

If you have CDE installed, use the Porting Assistant icon.

Use the FUSE Control Panel once FUSE is running.

Use the Tools menu from most FUSE tools.

17.2.1 Use the Command Line

You can start the Porting Assistant from the command line using the following command:

% fuseport [-Xt-Options]

See Appendix Appendix D and the specific reference pages for the command syntax and options.

If the Control Panel is not running, it starts automatically as a minimized icon. If FUSE is already running, the Porting Assistant is placed in the current project.

17.2.2 Use the Porting Assistant Icon from CDE

When you have CDE installed, FUSE provides a FUSE application group icon and icons for the individual tools that make up the FUSE environment.

To invoke the Porting Assistant:

Double click on the Application Manager icon in the CDE Front Panel to display the application group icons.

Double click on the FUSE application group icon to display the icons in the FUSE application group.

Double click on the Porting Assistant icon to start the tool.

17.2.3 Use the FUSE Control Panel

To start the Porting Assistant from the FUSE Control Panel, select Porting Assistant from the Tools menu in the Control Panel.

FUSE first lists the tool in the Control Panel under the current project. Then, either the tool main window appears, or, if you need to specify some initial settings for the tool, the Application Information dialog box. See Section Section 17.3 for more information.

17.2.4 Use the Tools Menu from Most FUSE Tools

Most FUSE tools have a Tools menu. To start a tool, select the tool from the Tools menu.

17.3 Setting Up the Porting Assistant

By default, the Porting Assistant uses the Build Directory as its working directory (the place where you want to build your application and where your source files are located). If there is no Build Directory, it uses the project working directory. You should set the Build Directory (or Working Directory) correctly before you run the Porting Assistant. Use the Project Manager (choose Projects: Show/Modify... from the Control Panel) and choose Builder for the Settings Category options menu.

Enter the appropriate pathname in the Build Directory field. Enter the appropriate makefile name for the porting-specific makefile, which the Porting Assistant requires to carry out its code checks.

If your application consists of many subcomponents built by one build procedure (possibly using recursive makefiles) or by component builds, you should work on components individually. Set up the component build directory and specify the component makefile as the makefile to use.

17.4 Creating a Porting-Specific Makefile

The Porting Assistant needs to have a porting-specific makefile (.portmakefile) to carry out its code checks. This makefile contains targets for all the checks the Porting Assistant might be requested to make.

You use the Application Information dialog box to create the porting-specific makefile:

After you start the Porting Assistant, there are four possible outcomes:

You have a porting-specific makefile from a previous session that is more recent than an existing makefile.
The Porting Assistant main window displays directly in this case.

You have no porting-specific makefile but you do have a makefile for your application.
The Porting Assistant can generate a porting-specific makefile from your makefile, although you still have the option of manually specifying information if you choose not to rely on your makefile.

You have a porting-specific makefile that is older than an existing makefile.
You are asked whether you want to generate a new porting-specific makefile.

You have no porting-specific makefile and no makefile for your application.
You will need to manually specify information about your application so that the Porting Assistant can generate a porting-specific makefile.

The steps to create a porting-specific makefile vary, depending on what you want the Porting Assistant to use as a source of information: your existing makefile or information you provide in absence of an existing makefile or if you choose not to rely on an existing makefile. See the online Help for more details on filling in the Application Information dialog box.

You also can regenerate your porting-specific makefile at any time using the Utilities menu in the Porting Assistant. Typical reasons include the following:

You changed your application makefile, thus making it necessary to update the porting-specific makefile. For example, you added an include file directory pointer to the makefile after an Include Files Check indicated several include files could not be found.

You want to change how you build your application for running porting checks from the current mechanism. For example, you created the porting-specific makefile for building your application based on information you entered manually and you now want to change to using your application makefile, or vice versa.

17.5 Order of Porting Steps

FUSE and the Porting Assistant work best given an ordered set of porting steps:

Make the files accessible.
This task is independent of the Porting Assistant. Note the Porting Assistant can check Fortran 77, Fortran 90, C, and C++ files. If your application consists of many subcomponents built by one build procedure (possibly using recursive makefiles) or by component builds, you should work on components individually. Use the component build directory as your working directory in the Porting Assistant and specify the component makefile as the makefile to use in the Porting Assistant.

Check #ifdef constructs.
You need to examine all the conditional code in your application to identify which sections to include on Digital UNIX. Once you identify those sections, you can conditionally execute those sections using the _alpha identifier (or some other appropriate identifier to use for Digital UNIX). Use the Porting Assistant to run an ifdef Code check to locate existing conditional constructs in your application.

Fix include file differences.
Use the Porting Assistant to run an Include Files check for include files not supported on Digital UNIX. You may need to include new #ifdef constructs to handle the differences between include files on Digital UNIX and the operating system from which you are porting.

Fix 32-bit dependencies.
Use the Porting Assistant to run a 32-Bit Dependencies check. This check identifies problems that occur when moving your code from a 32-bit platform to a 64-bit platform, particularly those that will prevent your application from compiling successfully.

Fix function differences.
The Porting Assistant Function Calls check helps you find functions in C and FORTRAN-77 that can cause problems when you compile your application on Digital UNIX.
Work through all the functions flagged by the check. For FORTRAN-77, the check can find function calls that have no definition/declaration or are inconsistent with their definition/declaration. For C, the check can flag missing prototypes or functions that are inconsistent with their prototypes.
With C, if you do not normally have your calls checked against system prototypes, this operation may point out instances that are not Digital UNIX specific. If you do use prototypes and your code compiles on another platform, the function calls that are flagged are those with a different signature on Digital UNIX.
Use the Function Finder dialog box, the DXML Lookup dialog box for Fortran programs, and the Man Page Browser (see online Help for detailed information on all these tools) during any of these steps to find an equivalent function (including, in the case of Fortran, the LAPACK math functions that are equivalent to the older LINPACK and EISPACK functions) or the correct prototype definition on Digital UNIX.

Port your application makefile.
Before you can attempt to compile and link your application on Digital UNIX, you need to port your application makefile. If, during the initial configuration of the Porting Assistant, you used the application makefile as the basis for generating the porting-specific makefile (necessary to run any of the porting checks), the application makefile has already been checked for syntax errors.
By running the Makefile check, you can make the port easier by verifying two additional characteristics of the makefile:
- That the actions in the makefile exist, that is, the underlying programs (compilers, linkers, and so on) can be found on the current PATH.
- That the options and arguments in the makefile are valid on the new platform. (A common subset of options is checked, for example, compiler and linker options; not all options that are possible.)

Find and fix undefined function calls.
Use the Builder to compile and link your application. The Builder lists any unresolved references during the link. In this way, you can identify functions that are not defined in the set of modules you specify or in system libraries. In addition, use the Search Libraries dialog box to identify system libraries that contain the functions (see online Help).

Fix function calls with different semantics.
When you have your application close to the point of compiling properly, you begin to assess whether it runs properly. Use the Porting Assistant and choose Platform Specific Assumptions from the Check options menu. At this point, you can proceed as follows:
- Choose all the functions in the Category options menu that might cause problems to see which ones the application uses as it executes. Alternatively, you could choose a specific category of functions and see if they apply to your application. You can then use the Explain and Show Man Page buttons to get more information about how the functions are different on Digital UNIX.
- Review and change specific functions. Add one or more functions to the Functions to Find list box and then execute a check operation. When complete, use an editor to review the code. Edit as appropriate.

Eliminate logic differences.
Compile, link, and debug your application to resolve logic differences.

17.6 Typical Porting Process Using FUSE

FUSE and the Porting Assistant support a planned strategy for porting primarily through the Porting Assistant checks, along with functions in the Builder, the editors, and the Search tool. That is, the Porting Assistant helps you to analyze your code to uncover classes of problems before moving directly to compiling your application and dealing with the errors as they occur. Even if your code compiles cleanly, the analysis made possible by the Porting Assistant can help detect run-time problems.

Figure Figure 17-2 summarizes the typical process supported by FUSE for analyzing code you intend to port to Digital UNIX.

Figure 17-2: Porting Process Using FUSE

17.7 Running Specific Checks on Your Code

The Porting Assistant lets you run several classes of portability checks on your application's code. Some of the classes of checks allow you to refine the check operation by toggling buttons on and off in the work area of the main window or selecting options in list boxes. When you finish a check operation, you can use the editors to walk through diagnostic messages and fix individual sections of code.

You can choose from among the following classes of checks:

ifdef Code

Include Files

32-bit Dependencies

Function Calls

Parallel Directives

Platform-Specific Assumptions

Makefile

To run any of the checks on your code, from the main window of the Porting Assistant:

Step	Action
1	Click and drag on the Check options menu to choose the class of check you want to run. The work area below the options menu changes to provide any customize options for this class of checks.
2	For the Include Files check: Accept the default directory search list or use the New Directory Path field and the New button to add new directories to the Search list. Use remaining buttons to make additional changes to the list. For the Function Calls check: No additional options. For the 32-Bit Dependencies check: Click on the toggle buttons to specify the options you want to check for. For the Platform Assumptions check and ifdef Code check: Select options displayed in the list boxes and use the Add and Delete buttons. For the Makefile check: Use toggles, text fields, and options menus to specify details on how you want the the check to be run.
3	Click on the Execute Check button at the bottom of the main window.
4	Use the Builder transcript to see the results of the check operation.
5	Use an editor to review the diagnostic messages while viewing the associated code.

Each of these steps is highlighted in Figure Figure 17-3:

Figure 17-3: Running Checks from the Main Window

17.8 Reviewing Diagnostic Messages

After you complete a build or run checks in the Porting Assistant, you can use navigation features to review diagnostic messages and associated code. In addition, you can get help on many of the diagnostic messages. These features are available in the Builder, FUSE Editor, and Emacs.

The steps vary, depending on the tool you use to view the diagnostic messages. As you review the diagnostics messages, you can choose to fix the associated code, ignore the messages, and filter out the messages.

17.8.1 Reviewing Diagnostics in the Builder

To review the diagnostic messages in the Builder:
Use the First, Next, Previous, and Last buttons in the main window to move the transcript window's focus to the appropriate message. The default editor is invoked automatically. If an editor is already running, the editor changes its focus to the code associated with the message and displays the current message.
You can also double click on a message in the transcript window of the Builder. This invokes the default editor. If an editor is already running, it loads the source file associated with the message and displays the message in the FUSE Editor's information area and in Emacs' minibuffer.

To get help on a message:
Choose Help on Diagnostic from the Buffer menu. This menu item will be dimmed if there is no help associated with the current diagnostic message.

17.8.2 Reviewing Diagnostics in the FUSE Editor

To review the diagnostic messages in the FUSE Editor:
Use the First, Next, Previous, and Last Diagnostic menu items in the Diagnostics menu to display the appropriate message in the information area. The associated code receives input focus in the editor.
The Diagnostics menu is a "tear-off" menu; that is, you can drag it to a convenient location in your work area.

To get help on a message:
Choose Help on Diagnostic from the Diagnostics menu. This menu item is dimmed if there is no help associated with the current diagnostic message.

17.8.3 Reviewing Diagnostics in Emacs

To review the diagnostic messages in Emacs:
In the FUSE menu, use the First, Next, Previous, and Last Diagnostic menu items (assuming you use the menu version of Emacs) to display the appropriate message in the minibuffer. The associated code receives input focus in the editor.
If you prefer to use key bindings or LISP commands, see Using FUSE-Related emacs Commands in the online Help.

To get help on a message:
In the FUSE menu, use the Help on Diagnostic menu item. If you prefer, you can use key bindings or LISP commands.

17.9 Filtering Diagnostic Messages

You can choose to filter out specific diagnostic messages in order to make it easier to find and fix important porting problems in your application. For example, you could decide that a particular class of diagnostic messages represents problems that do not require fixing or that might be fixed at a later date.

You can remove diagnostic messages from those displayed in the Builder, the FUSE Editor, or emacs. You can use regular expressions to filter out more than just the exact text of a specific message.

The Builder's main window contains a Filter toggle button in the Diagnostics frame. Click on the toggle button to filter out any messages that you specify using either of the following two methods:

Quick filtering lets you specify diagnostic messages to remove during the next build as you review them in the Builder, the FUSE Editor, or Emacs.

Detail filtering lets you modify filters, which take the form of specific message text or regular expressions. The Porting Assistant retains the filters for use on subsequent builds. You can add, remove, edit, and create regular expressions as filters.

See the Porting Assistant online Help for details on how to use these two methods to filter your diagnostic messages.