




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
























              Compaq Computer Corporation
              Houston, Texas

 






              ________________________________________________________________

              Copyright 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.

              This document prepared using DECdocument, Version 3.3-1b.

 














     _________________________________________________________________

                                                              Contents



           1     Introduction..................................      1
           2     Differences between Compaq C++ and the C++
                 International Standard........................      2
           3     Supported Linux Alpha Distributions...........      4
           4     Contents of the Compaq C++ CD-ROM.............      4
           5     Downloading and Installing the Kits...........      5
           5.1       Installation Requirements.................      5
           5.2       Installation Instructions.................      7
           6     Invoking the Compiler.........................      7
           6.1       Simple Optimization.......................      8
           6.2       Using GNU Development Tools with Compaq
                     C++.......................................      8
           7     Documentation.................................      9
           8     Redistributing Run-Time Libraries with
                 Applications..................................      9
           9     Known Problems and Restrictions for the Linux
                 Alpha Operating System........................     10
           9.1       Known Problems............................     10
           9.2       Restrictions..............................     10
           10    Known Library Restrictions....................     12
           11    Downloading Updates and Learning about Related
                 Products......................................     12
           12    Suggestion/Problem Reporting..................     12











                                                                   iii

 







        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[R] 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:

              o  No support for feedback-based optimization.

              o  No support for precompiled headers.

              o  No support for Tru64-based performance tools like cord,
                 atom or om.

              o  No -[x]taso features or pointer_size pragmas.

              o  The wchar_t type on Linux is unsigned int; on Tru64 UNIX
                 it is signed.

              o  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).

              o  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.

              o  Compiler-generated .s files cannot be assembled by the
                 assembler.

              o  The compiler and libraries are not multithread-safe.

              o  There is no task library.

              o  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:

              o  #include_next

                                                                        1

 







              o  The __inline keyword is enabled and is equivalent to
                 inline. On non-Linux platforms this keyword is available
                 by specifing -std gnu.

              o  The -std gnu option can provide additional
                 compatibility. For details, see the cxx(1) reference
                 page.

                _______________________ Caution _______________________

                The Compaq C++ compiler is not link-compatible with
                the GNU C++ compiler. This means that object files
                or libraries produced with one compiler cannot be
                linked with object files or libraries produced with
                the other. The GCC documentation, "info gcc trouble
                Interoperation" states:
        GNU C++ does not do name mangling in the same way
        as other C++ compilers. This means that object files
        compiled with one compiler cannot be used with another.

                      This effect is intentional, to protect
                      you from more subtle problems. Compilers
                      differ as to many internal details of
                      C++ implementation, including: how class
                      instances are laid out, how multiple
                      inheritance is implemented, and how
                      virtual function calls are handled. If
                      the name encoding were made the same,
                      your programs would link against libraries
                      provided from other compilers-but the
                      programs would then crash when run.
                      Incompatible libraries are then detected
                      at link time, rather than at run time.

                ______________________________________________________

        2 Differences between Compaq C++ and the C++ International
          Standard

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

              o  The export keyword for templates (Standard 14,
                 paragraph 6; Stroustrup 9.2.3)

        2

 







              o  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:

                 o  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

                 o  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.

                                                                        3

 







                 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

        3 Supported Linux Alpha Distributions

              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:

              o  Compaq C++ compiler (cxx) command and associated tools

              o  Compaq C compiler (ccc) command and associated tools

              o  Compaq C++ Run-Time environment

              o  Compaq C++ libraries

              o  Compaq Ladebug debugger

              o  Compaq Portable Math Library (CPML) routines (called by
                 Compaq C++ intrinsic procedures)

              o  Common Compiler Support Libraries (libots)

              o  A version of GNU binutils that supports Compaq C++

              o  A version of gdb that minimally supports Compaq C++

        4

 







              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:

              o  The libots Run-Time library

              o  The Compaq Portable Math Libraries (CPML)

              o  The Compaq C compiler

              o  The GNU compiler system

              o  The GNU development tools (binutils)

              The following are optional:

              o  The Compaq Ladebug debugger

              o  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:

                                                                        5

 







              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:

              o  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.

              o  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.

                ________________________ Note ________________________

                If you encounter problems with the Ladebug debugger,
                try using the -gall option.

                ______________________________________________________




        6

 







        5.2 Installation Instructions

              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-4.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.65-19.alpha.rpm
              rpm -i ccc-6.4.9.005-1.alpha.rpm
              rpm -i cxx-6.5.9.20-1.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

                                                                        7

 







              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.



        8

 







        7 Documentation

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

              o  This README document

              o  Using Compaq C++ for Tru64 UNIX and Linux Alpha

              o  Standard Library Locales

              o  Standard Library I/O

              o  Class Library Reference Manual

              o  cxx(1)

              o  demangle(1)

              o  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.

                                                                        9

 







              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:

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

        9.2 Restrictions

              Restrictions are as follows;

              o  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:





        10

 







                 #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;
                 }

              o  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.

              o  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.


                                                                       11

 







        10 Known Library Restrictions

              The following are restrictions:

              o  The Class Library task package is not supported on the
                 Linux Alpha platform.

              o  The Class and Standard Libraries are not multithread-
                 safe.

        11 Downloading Updates and Learning about Related Products

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

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

        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.











        12
