Compaq C++  README
	June 2000

This is the README for Version cxx-6.3.9.6-5 of the Compaq C++ compiler for Linux Alpha.

Compaq Computer Corporation
Houston, Texas

© 2000 Compaq Computer Corporation

COMPAQ, the Compaq logo, and Alpha, DEC, Ladebug, OpenVMS, Tru64 UNIX, and VMS are registered in the U.S. Patent and Trademark Office. All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is subject to change without notice.

Confidential computer software. Valid license from Compaq required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Contents

1 Introduction

cxx is the Compaq C++ compiler for Linux Alpha. It is a port of the same compiler that is available on the Compaq Tru64^tm UNIX® and OpenVMS Alpha platforms. The compiler produces excellent optimized code for the Alpha architecture, particularly for floating-point intensive applications.

There are some specific limitations and differences relative to the C++ compiler for Tru64 UNIX, including:

• No support for feedback-based optimization.
• No support for precompiled headers.
• No support for Tru64-based performance tools like cord , atom or om .
• No -[x]taso features or pointer_size pragmas.
• The wchar_t type on Linux is unsigned int ; on Tru64 UNIX it is signed .
• The long double data type is the same as double (Tru64 UNIX Version 5.0 makes long double a 16-byte IEEE quad-precision type).
• The -ieee command-line option on Linux Alpha has additional properties that are not present on Tru64 UNIX systems. See the cxx(1) reference page for more information.
• Compiler-generated .s files cannot be assembled by the assembler.
• The compiler and libraries are not multithread-safe.
• There is no task library.
• The order of static initialization is inverted. For more information, see Order of Static Object Initialization in Using Compaq C++ for Tru64 UNIX and Linux Alpha.

The C++ compiler accepts some gcc extensions, but is primarily a ISO standard C++ compiler. The following enhancements have been made for compatibility with the GNU C++ compiler:

• #include_next
• The __inline keyword is enabled and is equivalent to inline . On non-Linux platforms this keyword is available by specifing -std gnu .
• The -std gnu option can provide additional compatibility. For details, see the cxx(1) reference page.

The following items, specified in the C++ International Standard, are not supported in Version 6.3 but will be supported in a future version:

• The export keyword for templates (Standard §14, paragraph 6; Stroustrup §9.2.3)
• No cname version of headers provided (Standard §17.4.1.2; Stroustrup §16.1.2)
  Compaq C++ does not currently provide <cname> versions of the 18 ISO C library headers because no standard-conforming mechanism has yet been devised that that can be implemented without changing all existing C headers. If and when such a mechanism becomes available, we plan to use it, rather than use the simple-to-implement but nonstandard-conforming mechanism used by other C++ vendors: have the <cname> version include the non- <cname> version.
  The C++ header file inclusion policy for treating ISO C Library headers specifies that for each of the 18 ISO C headers, C++ should provide a <cname> form and a <name.h> form. The <cname> version defines all the symbols defined by ISO C in the corresponding <name.h> header in the std namespace. The <name.h> header defines all the symbols defined by ISO C in the corresponding <name.h> header in both the std and global namespace.
  Some of the problems are are as follows:
  • Because C library headers contain many non-ISO C names, it is impossible to avoid polluting either the std namespace, the global namespace, or both. (Remember that the global namespace is considered a real namespace that must not be polluted.) Namespace pollution is not only incorrect, it can lead to unexpected ambiguities.
    Consider the following program, which includes <cname> and <types.h> directly.

    // name.h includes types.h & brings it into std:: #include <cname> // types.h in global namespace #include <types.h> using namespace std; use something from types // ambiguity

  • Synchronizing the release of C and C++ headers.
  
  Compaq continues to investigate methods for providing this functionality in a way that ensures long-term compatibility with various C and C++ implementations.
  As a workaround, you can conditionalize your modules to use the <cname> versions of the headers when they become available. For example:

  #ifndef __NO_NEW_HEADER #include <cstddef> #include <cstdlib> #include <cstdio> #else #include <stddef.h> #include <stdlib.h> #include <stdio.h> #endif //__NO_NEW_HEADER

Compaq C++ Version 6.3 has been tested primarily under the Red Hat 5.2 Linux distribution for Alpha, which comes with GNU libc 2.0.7 and egcs-1.0.3a. There has also been some limited testing under Red Hat 6.0 and 6.1, and SuSE 6.1, which come with different versions of GNU libc and the GCC compiler. It may work with other distributions and other versions of GNU libc and GCC, but no other configurations have been tested.

4 Contents of the Compaq C++ CD-ROM

The Compaq C++ CD-ROM contains the following software components:

• Compaq C++ compiler ( cxx ) command and associated tools
• Compaq C compiler ( ccc ) command and associated tools
• Compaq C++ Run-Time environment
• Compaq C++ libraries
• Compaq Ladebug debugger
• Compaq Portable Math Library (CPML) routines (called by Compaq C++ intrinsic procedures)
• Common Compiler Support Libraries (libots)
• A version of GNU binutils that supports Compaq C++
• A version of gdb that minimally supports Compaq C++

Each of the components listed above is installed using the supplied Red Hat Package Manager (RPM^tm) files. Documentation files are also provided on the CD-ROM.

5 Downloading and Installing the Kits

The Compaq C++ installation kits are available on the CD-ROM distribution and from the Compaq C++ download site after you have completed the registration form .

5.1 Installation Requirements

Compaq C++ requires the following components:

• The libots Run-Time library
• The Compaq Portable Math Libraries (CPML)
• The Compaq C compiler
• The GNU compiler system
• The GNU development tools (binutils)

The following are optional:

• The Compaq Ladebug debugger
• The GNU debugger (gdb)

The versioning for libots, CPML, and Ladebug is consistent across Compaq C, C++, and Fortran compiler products. If you have already installed these packages and the packages on the download page or the distribution compact disc are not newer, there is no need to install them again. The Ladebug debugger shipped with the initial releases of Compaq C and Fortran did not support C++.

At the time of this document, support for the Compaq C++ compiler was not included in the development tools provided by all current Linux distributions. Compaq provides replacement development tools for those distributions. If Compaq does not provide suitable development tools for your distribution, you can obtain the latest version of the binutils sources that support Compaq C++ from ftp://ftp.varesearch.com/pub/support/hjl/binutils/. To install this version on your system, you must first build a source and binary RPM by entering a command in the following format:

rpm -ta binutils-version.tar.gz

You can also download the latest version of gdb and build with the libiberty provided by the latest binutils to obtain a debugger that supports Compaq C++.

For better performance of math library routines, you should link against the cpml library instead of libm . Specifying -lm on the command line causes the cxx driver to pass -lcpml -lm to the linker. The cpml library comes in two different packages, only one of which can be installed on a given system:

• cpml_ev5-version.alpha.rpm
  This package has code that runs best on Alpha chips prior to the EV6 (21264) processor. The code also runs on EV6 machines, but the EV6 version of the package provides code that runs significantly faster on EV6 processors.
• cpml_ev6-version.alpha.rpm
  This package provides a library that is highly tuned for the EV6 processor, but it will not run on earlier processors (it might produce "Illegal instruction" traps).

The Tru64 UNIX Ladebug debugger has been ported to Linux Alpha. Ladebug is the recommended debugger for Compaq compilers. The GNU debugger (gdb) does not support Compaq C++. Compaq provides a replacement version that has minimal support for Compaq C++. You need this version only if you plan to debug Compaq C++ programs from gdb.

The installation is straightforward with rpm -i if this is the first time the package is being installed, or with rpm -U if the package is being upgraded. The libots package should be installed before either of the cpml packages - the nature of the dependency between them is not handled by rpm 's installation-order dependency checks. You can install the other packages in any order. If you have previously installed a pre-release version of the compiler with a different package name, you should erase that package (using rpm -e ) before installing the cxx package.

For example, to install on an EV6 system running RedHat 6.1, on which you have not previously installed a Compaq compiler, you would enter the following commands:

rpm -i libots-2.2.7-2.alpha.rpm rpm -i cpml_ev6-5.1.0-2.alpha.rpm rpm -U compaq_rh61_binutils-2.9.1.0.23-12.alpha.rpm rpm -U compaq_rh61_gdb-4.18-6.alpha.rpm rpm -i ladebug-4.0.62-16.alpha.rpm rpm -i ccc-6.2.9.505-1.alpha.rpm rpm -i cxx-6.3.9.6-5.alpha.rpm

Packages other than libots contain documentation files that you can list by entering a command in the following format after the package is installed:

rpm -qd package-name

To list the files before the package is installed, enter a command in the following format:

rpm -qdp package-name

6 Invoking the Compiler

The command line for invoking the compiler and linker is mostly compatible with both the gcc compiler and the Tru64 UNIX compiler. Where possible, command-line options for gcc are translated to near-equivalents for the compiler. Options that do not have Tru64 UNIX equivalents are silently ignored by default. Overall, there is a reasonable probability that a makefile that works on Linux Alpha using the g++ compiler can be used to build the same application with the cxx compiler by changing only the compiler invocation command from g++ to cxx . This change causes cxx to compile .cxx and .cpp files and ccc to compile .c files.

6.1 Simple Optimization

Having successfully built your application with cxx , you might want to try making it run faster.

Specifying the -fast option at the end of your compiler options is a good first step. By default, the -fast option tells the compiler to generate the fastest code for the machine on which the compiler is running. If you compile on an advanced processor like EV6 (for example, a DS10 machine), the code might produce "Illegal instruction" traps if you try to run it on an older machine. If you want to try some quick tuning but want to make sure the result will run on any Alpha machine, specify -fast -arch generic . You might also want to try adding -O4 to enable optimizations that could further improve performance. Be aware however, that under some conditions, these optimizations could degrade performance.

The cxx(1) reference page and Using Compaq C++ for Tru64 UNIX and Linux Alpha contain more information about optimization controls and tuning. See the documentation section for the location and status of the documentation in this kit.

6.2 Using GNU Development Tools with Compaq C++

In binutils, some tools demangle by default; others require that you specify the --demangle option. To use the Compaq demangler, you must also specify the --style=compaq option. The --style option was added in binutils version 2.9.5 or later and has been ported to version 2.9.1 in the released kits.

Affected tools are: ld , objdump , gprof , nm , and addr2line .

To use the Compaq demangler in gdb, specify the command set demangle-style compaq .

7 Documentation

The following documentation is provided in HTML format on the installed system under the directory /usr/doc/cxx-6.3.9.6 .

• This README document
• Using Compaq C++ for Tru64 UNIX and Linux Alpha
• Standard Library Locales
• Standard Library I/O
• Class Library Reference Manual
• cxx(1)
• demangle(1)
• Standard Library

The cxx(1) reference page is derived from the cxx(1) reference page for Tru64 UNIX. It has been edited significantly to reflect differences between Tru64 UNIX and Linux Alpha behaviors.

8 Redistributing Run-Time Libraries with Applications

Users with a valid license are permitted to redistribute the libots and cpml Run-Time library packages included in the product, as follows.

If the application is linked with the -non_shared option ( -static in gcc terms), or is linked against the archive library ( .a ) form of these libraries, no redistribution is necessary (although it is permitted).

If the application is linked -call_shared ( -dynamic in gcc terms) and depends on libots.so and/or libcpml.so , then it is necessary for you to provide these libraries along with your application. The libraries should be redistributed in the form of the original RPMs (or updated versions of them) as provided by Compaq, and the users of the application should be advised to install them on the systems that will run the application.

If you redistribute cpml_ev6 , you need to caution your users that it should only be installed on an EV6 or newer version of the Alpha processor. The cpml_ev5 package can be installed on any version of the Alpha processor, but will not provide maximum performance on EV6 or newer processors.

Applications built by Compaq C++ on Linux Alpha systems running the Red Hat 5.2 or 6.0 distributions can be distributed for use on those systems. Distributing those applications on other versions or other distributions of Linux Alpha has not been tested (although there has been limited testing with the SuSE 6.1 distribution).

9 Known Problems and Restrictions for the Linux Alpha Operating System

This section describes known problems and restrictions for the Linux Alpha operating system.

9.1 Known Problems

Known problems are as follows:

• Inputting a pointer to void argument using the standard iostreams insertion operator>>(void*&) does not work.

Restrictions are as follows;

• On some Linux releases, the header file /use/include/wctype.h incorrectly defines wctrans_t as __const unsigned int * , while the Compaq C++ implementation expects __const int * . As a result, you might see an "incompatible parameter" error.
  This error is discretionary and can be disabled by specifying -msg_disable incompatibleprm on the command line or by enclosing your code within a #pragma, as shown in the following example:

  #include <wctype.h> int main() { wint_t w = L'a'; #pragma message save #pragma message disable incompatibleprm towupper(w); // This statement causes the error #pragma message restore return 0; }

• On Linux, the linker command ld supports an option of the form -B<static/dynamic/symbolic> . This option conflicts with the Compaq C++ compiler -B option is not supported.
• The Class Library iomanipulators lock() and unlock() are no-ops. In other words, you can use them, but they do nothing.
  Some undocumented Class Library iostream functions provided on Tru64 UNIX for backward compatibility only are not available on Linux Alpha; for example: streambuf::xsputn() and streambuf::xsgetn() . You should use the documented versions instead ( streabuf::sputn() and streambuf::sgetn() ).
  You cannot use the GNU library headers with Compaq C++ library executables, and you cannot use Compaq C++ headers with the GNU library executables, even if the names of the classes are the same.
  The Class Library, libcxx , is not distributed in shared form. You must use the archive version.
  Some of the Red Hat 5.2 locale files are bad. For example, trying to set locale to the ja_JP.EUC locale does not work. Even on Red Hat 6.0, you may get inconsistent results from Tru64 Unix. For example, the Hungarian thousands_sep() is a space on Tru64 Unix but a null character on Linux Alpha. The discrepancy is due to the differing locale information provided by the two operating systems.

The following are restrictions:

• The Class Library task package is not supported on the Linux Alpha platform.
• The Class and Standard Libraries are not multithread-safe.

For information about downloading updates to Compaq C++, Compaq Ladebug, CPML, and related products for Linux Alpha systems, please see the following Web page:

http://www.compaq.com/linux/

For information about other third-party products for the Linux Alpha platform, please see the following Web page:

http://www.alphalinux.org/

12 Suggestion/Problem Reporting

The University of New Hampshire (UNH), in partnership with Compaq, is developing an innovative support network for Alpha Linux developers. UNH supports a web site and forums for Alpha Linux developers to exchange information and ask questions. Please report any problems with Compaq C++ for Alpha Linux and its components at the UNH website:

http://www.iol.unh .edu/linux/alpha/development

UNH has a direct connection to Compaq's compiler and tools development organization for fast resolution of identified technical problems. You may not receive a personal reply to your query, but we appreciate your input on the product.

Contents

privacy and legal statement