|
|
|
|
|
 |
HP C++
|
| Previous | Contents | Index |
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++, organizing your C++ files, interfacing to other programming languages, and designing upwardly compatible C++ classes.
The C++ compiler implements section 17.4.1.2 - Headers [lib.headers] "C++ Headers for C Library Facilities" of the C++ Standard. See also Stroustrup's The C++ Programming Language, 3rd Edition sections 9.2.2 and 16.1.2.
The implementation consists of eighteen <cname> headers defined in the C++ Standard:
<cassert> <cctype> <cerrno> <cfloat> <ciso646> <climits> <clocale> <cmath> <csetjmp> <csignal> <cstdarg> <cstddef> <cstdio> <cstdlib> <cstring> <ctime> <cwchar> <cwctype> |
As required by the C++ Standard, the <cname> headers define C names in the std namespace. In /NOPURE_CNAME mode, the names are also inserted into the global namespace. See the description of the /[NO]PURE_CNAME compiler qualifier.
The <cname> headers are located in the same TLB library that contains the C++ standard library and class library headers: SYS$SHARE:CXXL$ANSI_DEF.TLB.
| #1 |
|---|
#include <cstdio>
void foo() {
getchar(); // OK in /NOPURE_CNAME mode
// %CXX-E-UNDECLARED in /PURE_CNAME mode
}
|
| #2 |
|---|
#include <cstdio>
void foo() {
std::getchar(); // OK in both modes
}
|
| #3 |
|---|
#include <stdio.h>
void foo() {
getchar(); // OK in both modes
std::getchar(); // OK in both modes
}
|
C header files that already conform to ANSI C standards must be modified slightly to be usable by HP C++ programs. In particular, be sure to address the following issues:
The compiler provides some C header files that have been modified to work with C++, including standard ANSI C header files. These headers are in the SYS$LIBRARY directory.
The following sections provide details on how to properly modify your headers.
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
# if defined __DECC || defined __DECCXX
/* If you are using pragmas that are defined only
* with DEC C and DEC C++, this line is necessary
* for both C and C++ compilers. A common error
* is to only have #ifdef __DECC, which causes
* the compiler to skip the conditionalized
* code.
*/
# pragma __extern_model __save
# pragma __extern_model __strict_refdef
extern const char some_definition [];
# pragma __extern_model __restore
# endif
/* ...some data and function definitions go here... */
#if defined __cplusplus
} /* matches the linkage specification at the beginning. */
#endif
|
See §r.7.4 of The C++ Programming Language, 3rd Edition for more information on linkage specifications.
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 |
Alternative representation keywords are as follows:
and, and_eq, bitand, bitor, compl, not, not_eq, or, or_eq, xor, xor_eq |
Distinctions between ANSI C and C++ include slight differences in rules concerning scope. Therefore, you may need to modify some ANSI C header files to use them with C++.
The following sample code fragment generates an error regarding incompatible types, but the root cause is the difference in scope rules between C and C++. In ANSI C, the compiler promotes tag names defined in structure or union declarations to the containing block or file scope. This does not happen in C++.
struct Screen {
struct _XDisplay *display;
};
typedef struct _XDisplay {
// ...
} Display;
struct Screen s1;
Display *s2;
main()
{
s1.display = s2;
}
|
The offending line in this sample is s1.display = s2 . The types of s1.display and s2 are the same in C but different in C++. You can solve the problem by adding the declaration struct _XDisplay; to the beginning of this code fragment, as follows:
struct _XDisplay; // this is the added line
struct Screen {
struct _XDisplay *display;
};
typedef struct _XDisplay {
// ...
} Display;
// ...
|
The C compiler special built-in macros defined in the header files <stdarg.h> and <varargs.h> . These step through the argument list of a routine.
Programs that take the address of a parameter, and use pointer arithmetic to step through the argument list to obtain the value of other parameters, assume that all arguments reside on the stack and that arguments appear in increasing order. These assumptions are not valid for HP C++. The macros in <varargs.h> can be used only by C functions with old-style definitions that are not legal in C++. To reference variable-length argument lists, use the <stdarg.h> header file.
The OpenVMS calling standard mechanism for returning structures larger than 8 bytes by value uses a hidden parameter. The parameter is a pointer to storage in the caller's frame. The va_count macro includes this parameter in its count.
The following are suggestions regarding the use of HP C++ with other languages:
extern "C" int myroutine(int, float); |
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 §4.4 of The C++ Programming Language, 3rd Edition for details on the extern "C" declaration.
This section explains the best way for compiler users to organize an application into files; it assumes that you are using automatic instantiation to instantiate any template classes and functions.
The general rule is to place declarations in header files and place definitions in library source files. The following items belong in header files:
And the following items belong in library source files:
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, arrayInt.hxx:
// arrayInt.hxx
#ifndef ARRAY_H
#define ARRAY_H
class arrayInt {
private:
int curr_size;
static int max_array_size;
public:
arrayInt() :curr_size(0) {;}
arrayInt(int);
};
#endif
|
Library source file, arrayInt.cxx:
// arrayInt.cxx
#include "arrayInt.hxx"
int array::max_array_size = 256;
arrayInt::arrayInt(int size) : curr_size(size) { ...; }
|
You would then compile the arrayInt.cxx library source file using the following command:
cxx/include=[.include] arrayInt.cxx |
The resulting object file could either be linked directly into your application or placed in a library (see Section 3.5.4).
The header file uses header guards, which is a technique to prevent multiple inclusion of the same header file.
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:
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 .
The following must be placed in library source files to prevent multiple definition errors:
These guidelines also apply to nontemplate nested classes inside of template classes.
Do not place definitions of nontemplate class members, nontemplate functions, or global data within template definition files; these must be placed in library source files. |
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.5.1, modified to use templates, would now look as follows:
Template declaration file, array.hxx:
// array.hxx
#ifndef ARRAY_HXX
#define ARRAY_HXX
template <class T>
class array {
private:
int curr_size;
static int max_array_size;
public:
array() :curr_size(0) {;}
array(int size,const T& value = 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,const T& value ) {... ; }
|
Then you would create a source file myprog.cxx that uses the array class as follows:
// myprog.cxx
#include "array.hxx"
main() {
array<int> ai;
// ...
}
|
Figure 3-1 shows the placement of these files.
Figure 3-1 Placement of Template Declaration and Definition Files
You would then compile myprog.cxx in the mydir directory with the following command:
cxx/incl=[.include] myprog.cxx |
In this case, you do not need to create library source files because the static member data and out-of-line members of the array template class are instantiated at the time you compile myprog.cxx .
However, you would need to create library source files for the following cases:
Table 3-1 describes where to place declarations and definitions, as discussed in Section 3.5.1 and Section 3.5.2.
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. 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 OpenVMS Command Definition, Librarian, and Messages Utilities Manual and the OpenVMS Linker Utility Manual.
The SW_SHR sample code consists of several source modules, a command procedure and this description. Table 3-2 lists each of the constituent modules, which are located in the directory SYS$COMMON:[SYSHLP.EXAMPLES.CXX] on your system.
The code creates an OpenVMS shareable image called SW_SHR.EXE that supplies a Stopwatch class identical to the C++ Class Library's Stopwatch class. For detailed information about the Stopwatch class, refer to the HP C++ Class Library Reference Manual .
SW_SHR also provides an instance of a Stopwatch class named G_sw that shows how to export a class instance from a shareable image. The exportation occurs in the same way that cout , cin , cerr , and clog are exported from the C++ Class Library shareable image.
In order to build the example, execute the SW_BUILD.COM procedure, then run the SW_TEST.EXE image.
When you create shared images on OpenVMS systems, you must export guard variables for template static data members or for static variables defined in inline functions. These guard variables, which are prefixed by __SDG and __LSG respectively, ensure that static data is initialized only once. You must also export the static variables in inlined functions and template static data members from the shared image so that they have only one definition.
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:
The format in which your library ships determines the levels of compatibility that apply:
| Library Format | Compatibility Level |
|---|---|
| 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.
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:
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.
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:
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 remain 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:
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:
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. On OpenVMS systems, you need to create an upwardly compatible shareable image using a transfer vector on OpenVMS VAX and a symbol table on OpenVMS Alpha. Refer to the OpenVMS Linker Utility Manual for information on creating a shareable image.
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.
| Previous | Next | Contents | Index |
|
|||||||||||
