HP OpenVMS Systems Documentation
Content starts here
Common Desktop Environment: Programmer's Overview

4 Portability and Maintenance

Contents of Chapter:
Portability Issues
Standards
Makefiles
File-Naming Conventions
Display Support
Common Desktop Environment Motif Widget Binary Compatibility Guidelines
This chapter contains information you can use to write highly portable applications and use to ensure that your application will be compatible with future Common Desktop Environment releases.

Portability Issues

This section presents issues that might affect your application's portability between different platforms that support the Common Desktop Environment.

Standards

To be Common Desktop Environment-compliant, your application must follow the Motif 1.2, ANSI-C, and X11R5 standards. If you are developing your application in C++, use C++ version 2.0 or later. No further assumptions are made that you adhere to any standards, such as POSIX, when you write a Common Desktop Environment application. Applications that use the desktop application program interfaces (APIs) will be portable to other Common Desktop Environment platforms. However, using POSIX can enhance your software's portability.

The POSIX standard, IEEE Std 1003.1-1990, is entitled IEEE Standard for Information Technology--Portable Operating System Interface (POSIX)--Part 1: System Application Program Interface (API) [C Language], ISBN 1-55937-061-0.

The Motif 1.2 standard, IEEE Std 1295, is entitled Standard for Information Technology--X Window System Graphical User Interface--Modular Toolkit Environment.

For information on ordering IEEE Std 1003.1-1990 and IEEE Std 1295, see "Related Books."

Makefiles

Certain libraries that the Common Desktop Environment depends on, for example X11R5, are likely to be installed in different locations on different platforms. Include platform-specific references to accommodate this or write a separate makefile for each platform.

Also, the make program functionality can differ across platforms. If you want to write just one makefile for your application, use the common make functionality used by the platforms to which you want to port your program. Avoid platform-specific make features.

The Common Desktop Environment requires no additional defined constants (-D parameters) to integrate with the desktop. If you do follow a standard, such as POSIX, you might need to compile with additional standard-specific flags. Read about the standard to find out if it includes special compiler considerations.

Each subdirectory of /usr/dt/examples contains sample makefile source files for different platforms. These makefiles take into account system differences. In particular, see the /usr/dt/examples/dtdts directory for generic examples of makefiles.

Compile Options

To enable your application to find the desktop include files, add:

-I/usr/dt/include
to each makefile's compile line.

Link Options

To enable your application to reference desktop libraries, add:

-L/usr/dt/lib -l<libname1> -l<libname2>...
to each makefile's link line, where libname1, libname2 are the names of libraries your application needs to reference. You can include as many desktop library names in this line as you want. For example:

-L/usr/dt/lib -lDtSvc -ltt -lXm
enables your application to reference the Desktop Services, ToolTalk Messaging System, and Motif 1.2 libraries.

File-Naming Conventions

You should limit your application file names, and the file names your application generates, to 14 characters. This will make your application portable to platforms that have this limitation. Some platforms can be configured to have this constraint.

Do not place length limitations on file names that an end user generates.

Display Support

Your application should support the following display options and configurations:

If you use the Icon Editor to create color icons, your application will share colors with other desktop applications more readily. This helps conserve color cells when running on a Pseudo Color display.

Common Desktop Environment Motif Widget Binary Compatibility Guidelines

Any widget subclass that you implement using the standard Xt APIs that rely on the size of data structures of widgets from which you have subclassed might not be compatible with any new version of Motif or the Common Desktop Environment. The reason for this is that new fields may be added to the superclasses in the new version of Motif. An example is that new fields have been added to the XmManager and XmPrimitive classes in Motif 2.0.

The incompatibility occurs because a subclass must contain compiled-in references to its instance fields that are specified relative to the start address of the widget instance. When you install a new Motif library for a widget whose superclass instance structure has been extended, the compiled-in references will point to the wrong memory location.

To avoid this difficulty, Motif provides a mechanism for defining resources and accessing widget fields that allows you to reference all fields in the instance and constraint structures relative to the start of the widget part structure, instead of the overall widget structure. (The overall widget structure includes the superclass part structure.) The mechanism resolves these relative references at run time, when the widget class is first initialized. To resolve references, it factors in the size of the widget's superclass instance structure, which it reads from the currently linked Motif library.

Note: If you implement subclassing, you must use the Motif reference-resolving mechanism if you want your application to be binary compatible with future releases of the Common Desktop Environment.

For details regarding this Motif mechanism, consult the Motif 1.2 XmResolvePartOffsets(3x) and XmResolveAllPartOffsets(3x) man pages and the OSF/Motif Programmer's Reference. You can find example source code in /usr/dt/examples/motif/dogs.