This chapter describes the guidelines and procedures for customizing your language environment. It includes sections on changing your C header files to work with C++, using 32-bit pointers, organizing your C++ files, interfacing to other programming languages, and designing upwardly compatible C++ classes.

3.1 Using Existing C Header Files

C header files that already conform to ANSI C standards must be slightly modified for use by HP C++ programs. In particular, be sure to address the following issues:

• Enable the proper linkage for each language.
• Ensure that C++ keywords are not used as identifiers.
• Reconcile any name space and scoping differences.

The following sections provide details on how to properly modify your header files.

3.1.1 Providing C and C++ Linkage

To modify header files, use conditional compilation and the extern specifier.

When programming header files to be used for both C and C++ programs, use the following convention for predefined macros. The system header files also provide an example of correct usage of the predefined macros.

#if defined __cplusplus /* If the functions in this header have C linkage, this * will specify linkage for all C++ language compilers. */ extern "C" { #endif extern int func1(int); extern int func2(int); . . . #if defined __cplusplus } /* matches the linkage specification at the beginning. */ #endif

See The C++ Programming Language, 3rd Edition for more information on linkage specifications.

3.1.2 Resolving C++ Keyword Conflicts

If your program uses any of the following C++ language keywords as identifiers, you must replace them with nonconflicting identifiers:

asm	bool	catch	class
const_cast	delete	dynamic_cast	explicit
export	false	friend	inline
mutable	namespace	new	operator
private	protected	public	reinterpret_cast
static_cast	template	this	throw
true	try	typeid	typename
virtual	wchar_t

3.2 Using HP C++ with Other Languages

The following are suggestions regarding the use of HP C++ with other languages:

• Passing entities, such as classes, by reference is safest.
• You cannot invoke class member functions from within any language other than C++.
• Every C++ routine that will be called from the other language should be declared in C++ with extern "C" . For example:

  extern "C" int myroutine(int, float);

  
  The extern "C" will cause the routine to have an unmangled name, so that you can refer to it as myroutine from a language such as Cobol or Fortran. Otherwise the routine's link name will be mangled into something like myrout__Xif .

• If the main routine is defined in the other language, you will probably need to use the other language's command-line interface to perform your link step. To include the appropriate C++ libraries and startup file, you will need to add some arguments to the command line. The most reliable way to determine what is needed is to test with a small C++ program as follows:

  cxx -c tiny.cxx cxx -v tiny.o

  
  The -v option causes the compiler to display the command line when it links tiny.o .
  The following is an example of the resulting display on HP Tru64 UNIX Version 4.0 systems or higher and Linux Alpha:

  /usr/lib/cmplrs/cc/ld -g0 -O1 -call_shared /usr/lib/cmplrs/cc/crt0.o \ /usr/lib/cmplrs/cxx/_main.o tiny.o -lcxxstd -lcxx -lexc -lc

  
  In this example, for your link step involving a language other than C++, you would add the following to the command line:

  /usr/lib/cmplrs/cxx/_main.o -lcxxstd -lcxx -lexc

  
  If your language uses the linker directly, you would also need to add the following:

  /usr/lib/cmplrs/cc/crt0.o ... -lc

3.3 Linkage to Non-C++ Code and Data

With linkage specifications, you can both import code and data written in other languages into a HP C++ program and export HP C++ code and data for use with other languages. See The C++ Programming Language, 3rd Edition for details on the extern "C" declaration.

3.4 How to Organize Your C++ Code

This section explains the best way for HP C++ users to organize an application into files; it assumes that you are using automatic instantiation to instantiate any template classes and functions.

3.4.1 Code That Does Not Use Templates

The general rule is to place declarations in header files and place definitions in library source files. The following items belong in header files:

• Class declarations
• Global function declarations
• Global data declarations
• Inline function definitions

The following items belong in library source files:

• Static member data definitions
• Out-of-line member function definitions
• Out-of-line global function definitions
• Global data definitions

Header files should be directly included by modules that need them. Because several modules may include the same header file, a header file must not contain definitions that would generate multiply defined symbols when all the modules are linked together.

Library source files should be compiled individually and then linked into your application. Because each library source file is compiled only once, the definitions it contains will exist in only one object module and multiply defined symbols are thus avoided.

For example, to create a class called "array" you would create the following two files:

Header file, array.h:

// array.h #ifndef ARRAY_H #define ARRAY_H class array { private: int curr_size; static int max_array_size; public: array() :curr_size(0) {;} array(int); }; #endif

Library source file, array.cxx:

// array.cxx #include "array.h" int array::max_array_size = 256; array::array(int size) : curr_size(size) { ...; }

You would then compile the array.cxx library source file using the following command:

cxx array.cxx

The resulting object file could either be linked directly into your application or placed in a library (see Section 3.4.3).

Note that the header file uses header guards, which is a technique to prevent multiple inclusion of the same header file.

3.4.2 Code That Uses Templates

With the widespread use of templates in C++, determining the proper place to put declarations and definitions becomes more complicated.

The general rule is to place template declarations and definitions in header files, and to place specializations in library source files.

Thus, the following items belong in template declaration files:

• Declarations of global function templates
• Declarations of class templates
• Declarations of global function template specializations
• Declarations of class template specializations

The following items can be placed either in the header file with the corresponding template declaration or in a separate header file that can be implicitly included when needed. This file has the same basename as the corresponding declaration header file, with a suffix that is found by implicit inclusion. For example, if the declaration is in the header file inc1.h , these corresponding definitions could be in file inc1.cxx .

• Definitions of out-of-line global function templates
• Definitions of static member data of class templates
• Definitions of out-of-line member functions of class templates

The following must be placed in library source files to prevent multiple definition errors:

• Definitions of global function template specializations
• Definitions of static member data specializations of class templates
• Definitions of out-of-line class member function specializations

These guidelines also apply to nontemplate nested classes inside of template classes.

All these header files should use header guards, to ensure that they are not included more that once either explicitly or by implicit inclusion.

For example, the array class from Section 3.4.1, modified to use templates, could now look as follows:

Template declaration file array.h:

// array.h #ifndef ARRAY_H #define ARRAY_H template <class T> class array { private: int curr_size; static int max_array_size; public: array() :curr_size(0) {;} array(T); }; #endif

Template definition file array.cxx:

// array.cxx template <class T> int array<T>::max_array_size = 256; template <class T> array<T>::array(int size) : curr_size(size) { ; }

You would then create, as follows, the source file myprog.cxx that uses the array class:

// myprog.cxx #include <array.h> main() { array<int> ai; // ... }

3.4.3 Creating Libraries

Libraries are useful for organizing the sources within your application as well as for providing a set of routines for other applications to use. Libraries can be either object libraries or shareable libraries. Use an object library when you want the library code to be contained within an application's image; use shareable libraries when you want multiple applications to share the same library code.

Creating a library from nontemplate code is straightforward: you simply compile each library source file and place the resulting object file in your library.

Creating a library from template code requires that you explicitly request the instantiations that you want to provide in your library. Alternatively, if automatic template instantiation has been used, the instantiation object files in the repository can be placed in your library. See Chapter 7 for details.

If you make your library available to other users, you must also supply the corresponding declarations and definitions that are needed at compile time. For nontemplate interfaces, you must supply the header files that declare your classes, functions, and global data. For template interfaces, you must provide your template declaration files as well as your template definition files.

For more information on creating libraries, see the ar(1) reference page and the loader(1) reference page.

3.5 Using 32-bit Pointers (xtaso)

Normally, HP C++ uses 64 bits for all pointers in generated code. The Extended Truncated Address Support Option (xtaso), and other #pragma directives and compiler options, let code with 32-bit pointers coexist within this 64-bit operating system environment. Such a capability can be useful when the data layout used for pointers must be compatible with the layout on a 32-bit processor.

The 32-bit pointer data type lets application developers minimize the amount of memory used by dynamically allocated pointers. Using 32-bit pointers can sometimes improve performance if the volume of data occupied by pointers is large. In certain instances, the capability can be helpful in porting applications that contain assumptions about pointer sizes, although the following precautions apply:

• Mixing 32-bit and 64-bit pointers may introduce new porting problems if the data structures in system libraries still use 64-bit pointers.
• Anyone who supplies object modules (or libraries) compiled with 32-bit pointers thereby restricts users of those objects to the use of 32-bit pointers and requires those users to be aware of the difficulties of using 32-bit pointers in a mixed 32/64-bit environment.

To use 32-bit pointers, you must use a combination of #pragma preprocessor directives and command-line compiler options. These #pragmas are described in Section 2.1.1 and are summarized in the following table:

pragma Directive	Description
pointer_size	Controls the pointer size of all pointers except virtual function and virtual base pointers in a C++ class object. Has an effect only if you specify one or more of the pointer-size compiler options.
required_pointer_size	Has the same effect as #pragma pointer_size but is always enabled, whether or not you specify any pointer-size compiler options.
required_vptr_size	Controls the size of virtual function and virtual base pointers in a C++ class object. Always enabled, whether or not you specify any pointer size compiler options.

The pointer size compiler options are -xtaso , -xtaso_short , -vptr_size , and -vptr_size_short . Whenever any of these options are specified on the command line, the following actions occur:

• #pragma pointer_size is enabled. This pragma has an effect only if you specify a pointer size compiler option on the command line.
• The cxx command automatically passes the -taso option to the linker. This option causes the linker to load the executable in the lower 31-bit addressable virtual address range and causes memory allocations to be made from the same virtual address page. Thus, your program is limited to a 31-bit virtual address space whenever you use any of the pointer-size compiler options.

Individually, the pointer size options have following effects:

Compiler Option	Description
-xtaso	Sets the default pointer size of the compilation unit to 64 bits (for all pointers except virtual function and virtual base pointers in a C++ class object). This is the normal default unless overridden by -xtaso_short .
-xtaso_short	Sets the default pointer size of the compilation unit to 32 bits (for all pointers except virtual function and virtual base pointers in a C++ class object).
-vptr_size	Makes 64 bits the default size of virtual function and virtual base pointers in a C++ class object. This is the normal default unless overridden by -vptr_size_short .
-vptr_size_short	Makes 32 bits the default size of virtual function and virtual base pointers in a C++ class object.

You cannot reset the size of the this pointer. The this pointer always remains the system default pointer size, which is 64 bits.

When using these #pragma directives and compiler options, you must take particular care if you call functions in any library compiled with different pointer sizes. The approaches that you can use to mix 32- and 64-bit pointers are as follows:

1. Make 64 bits the default pointer size and use 32-bit pointers for particular declarations.
2. Make 32 bits the default pointer size.

The second approach generally is more difficult because of problems in combining your code with code that expects 64-bit pointers. The sections that follow discuss these approaches in more detail.

Approach 1: Making 64 bits the default pointer size

With this approach, most pointers in your application are 64 bits, and 32 bits are used for selected pointers. To use this approach, you must compile with -xtaso to enable #pragma pointer_size and cause the cxx command to pass -taso to the linker.

You use #pragma pointer_size , #pragma required_pointer_size , and #pragma required_vptr_size to control the pointer sizes for particular declarations. For example, to save space in an object, you can declare a class as follows:

#pragma pointer_size save #pragma required_vptr_size save #pragma pointer_size short #pragma required_vptr_size long class Table_Node { char *table; // 32-bit pointers Table_Node *next; Table_Node *(Table_Node::*search)(char *); // pointer to member has // 2 32-bit fields public: #pragma pointer_size long void insert_node(char *); Table_Node *extract_node(char *); Table_Node *search_forward(char *); Table_Node *search_backward(char *); }; #pragma pointer_size restore #pragma required_vptr_size restore

With this approach, you must take care to specify the pointer size #pragma directives after any #include directives, so that header files that assume 64-bit pointer sizes are not affected.

Approach 2: Making 32 bits the default pointer size

To use this approach, compile using the -xtaso_short and -vptr_size_short options on the cxx command. With this approach, the default pointer size is 32 bits; you must take care when interfacing to code that expects 64-bit pointers.

Specifically, you must protect header files so that the pointer size assumptions made in compiling the header file are the same as those made when the associated code was compiled. None of the system header files, including those for the standard C library, are protected. Thus, most programs do not work correctly when compiled with the -xtaso_short option unless you protect the system header files and any other header files associated with code that assumes 64-bit pointers. For more information, see Section 2.1.2.

No matter which approach you use, you must take particular care when passing any data that contains pointers (for example, an array of pointers or a struct that contains pointers) to be sure that the pointer size is the same as expected by the called function.

Pointer expressions are normal sized regardless of the currect pointer size. For example:

int x; int *px; int X::*pXk; sizeof(int*)=4 sizeof(px)=4 sizeof(&x)=8 sizeof(int X::*)=8 sizeof(pXk)=8 sizeof(&X::k)=16

HP C++ does not permit overloading based on pointer sizes. To minimize problems, you should declare functions, including member functions with long pointer sizes. During calls to such functions, the compiler promotes short pointers to long pointers.

3.6 Hints for Designing Upwardly Compatible C++ Classes

If you produce a library of C++ classes and expect to release future revisions of your library, you should consider the upward compatibility of your library. Having your library upwardly compatible makes upgrading to higher versions of your library easier for users. And if you design your library properly from the start, you can accomplish upward compatibility with minimal development costs.

The levels of compatibility discussed in this section are as follows:

1. Source compatibility
2. Link compatibility
3. Run or binary compatibility

The format in which your library ships determines the levels of compatibility that apply:

If you ship your library in ...	The following apply:
Source format	Source compatibility only
Object format	Source and link compatibility
Shareable library format	All three kinds of compatibility

If you break compatibility between releases, you should at least document the incompatible changes and provide hints for upgrading between releases.

3.6.1 Source Compatibility

Achieving source compatibility means that users of your library will not have to make any source code changes when they upgrade to your new library release. Their applications will compile cleanly against your updated header files and will have the same run-time behavior as with your previous release.

To maintain source compatibility, you must ensure that existing functions continue to have the same semantics from the user's standpoint. In general, you can make the following changes to your library and still maintain source compatibility:

• Add new data members and classes.
• Add new virtual and nonvirtual functions (as long as they do not change overload resolution of existing calls).
• Loosen protection.
• Change inline functions to out-of-line and out-of-line functions to inline.
• Change the implementation of functions.
• Add arguments with default values to existing member functions.

3.6.2 Link Compatibility

Achieving link compatibility means that users of your library can relink an application against your new object or shareable library and not be required to recompile their sources.

What can change

To maintain link compatibility, the internal representation of class objects and interfaces must remain constant. In general, you can make the following changes to your library and still maintain link compatibility:

• Change the implementation of an out-of-line function.
• Loosen protection.
• Add a new nonvirtual member function (as long as it does not change overload resolution for existing calls).

What cannot change

Because the user may be linking object modules from your previous release with object modules from your new release, the layout and size of class objects must be consistent between releases. Any user-visible interfaces must also be unchanged; even the seemingly innocent change of adding const to an existing function will change the mangled name and thus break link compatibility.

The following are changes that you cannot make in your library:

• Add, move, or delete data members.
• Add, move, or delete virtual functions.
• Change the signature of virtual and nonvirtual functions.
• Remove nonvirtual functions.
• Change inline function definitions.
• Change functions from out-of-line to inline.

Designing Your C++ Classes for Link Compatibility

Although the changes you are allowed to make in your library are severely restricted when you aim for link compatibility, you can take steps to prepare for this and thereby reduce the restrictions. HP suggests using one of the following design approaches:

• Set aside dummy (reserved-for-future-use) data fields and virtual functions within your classes. This assumes you can foresee how much your classes will grow and change in the future.
• Add a level of indirection to hide your virtual functions and data fields from the user. This lets you add and change data fields and virtual functions without affecting the library user; however, there may be some disadvantages such as in performance. This approach is detailed in Effective C++, Section 34, by Scott Meyers.

3.6.3 Run Compatibility

Achieving run compatibility means that users of your library can run an application against your new shareable library and not be required to recompile or relink the application.

This requires that you follow the guidelines for link compatibility as well as any operating system guidelines for shareable libraries. For example, you need to ensure your version identifier is upwardly compatible between releases. Refer to the ld reference pages for information on creating a shareable library.

3.6.4 Additional Reading

The C++ Programming Language, 3rd Edition offers some advice on compatibility issues. Another good reference is Designing and Coding Reusable C++, Chapter 7, by Martin D. Carroll and Margaret E. Ellis.