
                    Compaq C Compiler Beta 6.5 for Linux Alpha
                    README


                    April 2002

              ________________________________________________________________

               2002 Compaq  Information Technologies Group, L.P.

              Compaq and the Compaq logo are trademarks of Compaq Information
              Technologies Group, L.P. in the U.S. and/or other countries.
              
              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.


              Compaq shall not be liable for technical or editorial
              errors or omissions contained herein. The information in
              this publication is subject to change without notice and is
              provided "as is" without warranty of any kind. The entire
              risk arising out of the use of this information remains
              with recipient. In no event shall Compaq be liable for any
              direct, consequential, incidental, special, punitive, or
              other damages whatsoever (including without limitation,
              damages for loss of business profits, business interruption
              or loss of business information), even if Compaq has been
              advised of the possibility of such damages. The foregoing
              shall apply regardless of the negligence or other fault
              of either party and regardless of whether such liability
              sounds in contract, negligence, tort, or any other theory
              of legal liability, and notwithstanding any failure of
              essential purpose of any limited remedy.

              The limited warranties for Compaq products are exclusively
              set forth in the documentation accompanying such products.
              Nothing herein should be construed as constituting a
              further or additional warranty.


        1 Introduction

	      ccc is the Compaq C compiler for Linux Alpha. It is a port
              of the same compiler that is available on the Compaq
              Tru64 UNIX platform (and also on OpenVMS Alpha). 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 Compaq's Tru64 UNIX,
              including:

              o  No support for feedback-based optimization.

              o  No support for parallel programming (that is, no
                 OpenMP).

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

              o  No structured exception handling.

              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 has additional
                 properties that are not present on Tru64 UNIX systems.
                 See the ccc manpage for more information.

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

              o  The -[x]taso feature and pointer_size pragmas may or
                 may not be available, depending on the particular
                 version of the linker used on your system. And when
                 it is available, it has not been well-tested.

              While the compiler accepts some gcc extensions, and
              successfully builds many of the SRPMS coded in C that are
              shipped with Red Hat and SuSE distributions, the compiler
              is primarily a standard C and K&R compiler. To the extent
              that gcc extensions are supported, they are mostly limited
              to features that are in common with the C99 standard
              (ISO/IEC 9899:1999), such as variable-length arrays and

              initializers with designators, and to gcc features commonly
              encountered in source packages and header files even when
              configured for using a compiler other than gcc.

              Note that an official copy of the C99 standard can be
              purchased and downloaded as a PDF file for less than $20US
              from either NCITS at http://www.techstreet.com/cgi-bin/detail?product_id=232462
              or ANSI at http://webstore.ansi.org/ansidocstore/product.asp?sku=ANSI%2FISO%2FIEC+98 99%2D1999.

        2 Supported Linux Alpha Distributions

              Compaq C Beta 6.5 no longer supports Red Hat 5.2,
              because the compiler is now linked dynamically against
              glibc 2.1 in order to enable compile-time support for
              multibyte locales when processing strings and character
              constants and their wide variants. This does not work when
              the compiler is invoked on a glibc 2.0 system like Red
              Hat 5.2. The compiler has primarily been tested on Red Hat
              6.0, 6.1, 6.2, 7.0, and 7.1 and 7.2-beta, as well as
              SuSE 6.1, 6.3, 7.0, and 7.1 distributions. Users have also
              had success on Debian, Kondara, and other distributions,
              but no other configurations have been tested by the Compaq
              compiler team.

              The basic support mechanism for Compaq C is provided by
              the UNH web site identified at the end of this document.
              In addition, Compaq offers per-incident support for
              specific Linux distributions, which can be extended to
              include Compaq C on those distributions (for an additional
              charge).

        3 Summary of Changes from V6.4:

              o  Upgraded to a new baselevel of the GEM backend,
                 called BL48.  This has the latest support for
                 EV7 processors.

              o  New command line option "-annotations all", to add
                 information about optimization decisions to
                 source listings.

              o  All #pragma directives may be specified with an
                 optional "_m" or "_nm" suffix on the name.  The "_m"
                 suffix forces the tokens of the pragma to undergo
                 macro expansion, regardless of its default behavior
                 (in general, "older" pragmas undergo macro expansion
                 by default, while more recent pragmas do not, as
                 noted in the Programmers Guide).  Similarly, adding
                 the "_nm" suffix to a pragma name prevents it from
                 undergoing macro expansion.

              o  The compiler now implements the C99 _Pragma operator.
                 Note that the gcc implementation of _Pragma has an
                 extension to the C99-specified behavior: it permits
                 a sequence of string literals as the argument, while
                 C99 specifies that the argument is a single string
                 literal.  Note that in both the orginal C89 standard
                 and in C99, concatenation of adjacent string literals
                 is specified to occur in translation phase 6, while
                 #pragma directives (C89) and the _Pragma operator (C99)
                 are processed in translation phase 4.  Thus concatenating
                 string literals within the operand of _Pragma is
                 not consistent with the standard-specified ordering
                 of translation phases.  There is a certain convenience
                 to being able to use adjacent string literals within
                 the operand when using _Pragma within a macro definition.
                 However, the same effect can usually be achieved in the C99
                 form by defining a macro as shown in the example of
                 using _Pragma in the C99 standard:
                      #PRAGMA(x) _Pragma(#x)
                 Using this, arguments can be effectively concatenated
                 before the string is formed, so string concatenation
                 is not needed.  E.g.
                      #define NOT_ZERO(x) PRAGMA(__assert __non_zero(expr))

              o  C99-defined behavior for concatenation of adjacent
                 character and wide character string literals is

              o  C99-defined behavior for concatenation of adjacent
                 character and wide character string literals is
                 implemented.

              o  In V6.4, specifying the -ieee command line qualifier
                 when compiling the source file containing function
                 main() would force a reference to function
                 __setfpe_mode().  This function is defined in libcpml,
                 so it would then be necessary to add -lm (or -lcpml)
                 to the link command line even if the program used
                 no math library routines (or no floating point at
                 all).  This problem has been addressed by making
                 it a weak reference - the call will be made to set
                 the mode for the cpml library only if there are other
                 calls that get resolved to cpml library routines.
                 

              o  The following are predefined identifiers to provide
                 the C99 functionality of constants with the value of
                 ieee NaN and Infinity, although these are not
                 integrated into the headers with standard macros
                 for them:

                     __decc_float_ieee_Infinity
                     __decc_float_ieee_NaN
                     __decc_double_ieee_Infinity
                     __decc_double_ieee_NaN
                     __decc_long_double_ieee_Infinity
                     __decc_long_double_ieee_NaN

              o  The gcc practice of allowing an empty set of braces
                 in an initializer to designate all zero values is
                 now supported, as well as more gcc-compatible
                 treatment of function prototype declarations
                 followed by a subsequent K&R-style function
                 definition (the prototype "wins").



        4 CDROM

              The Compaq C compiler may be packaged on various
              CDROMs with other software.  The precise contents of the
              CDROMs may differ, but in general it contains in its
              root directory the software packages for installation,
              as well as a README file that points to this README file
              (the file you are reading) and to other documentation files
              under a directory named docs. The docs directory contains
              documentation files for the different software components,
              each in its own subdirectory named after its package name.

              The software components relevant to the C compiler are:

              o  Common Compiler Support Libraries (package libots)

              o  Compaq Portable Math Library (packages cpml_ev5 and
                 cpml_ev6)

              o  Compaq C compiler (package ccc)

              o  Compaq Ladebug debugger (package ladebug)

              Use the supplied Red Hat Package Manager (RPM) files to
              install each of the components listed above.





        5 Installation Requirements and Instructions

              To use Compaq C, the following packages should be installed
              in the order listed below.

              1. libots-2.2.7-2.alpha.rpm

                 Compaq C depends on the libots runtime library provided
                 for all of Compaq's Alpha Linux compilers in the libots
                 package. You need to install libots in order to use the
                 compiler, and libots must be installed before cpml is
                 installed.

              2. cpml library

                 The ccc command adds -lcpml to the options passed to the
                 linker whenever you specify -lm or -ieee on the command
                 line, so one of the two following packages also needs to
                 be installed:

                 o  cpml_ev5-5.1.0-4.alpha.rpm

                    This package has code that runs best on Alpha chips
                    prior to the EV6 (21264) processor. The code will
                    also run on EV6 machines, but the ev6 version of the
                    package provides code that runs significantly faster
                    on EV6 processors.

                 o  cpml_ev6-5.1.0-4.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).

              3. ccc-6.5.6.002-1.alpha.rpm

                 The C compiler package.

              4. ladebug-4.0.65-19.alpha.rpm

                 This package is optional. The code produced by ccc can
                 be debugged by gdb. But for those accustomed to the
                 Tru64 UNIX ladebug debugger, and because of its superior
                 support for Fortran and C++ debugging, ladebug has been
                 ported to Linux Alpha. Ladebug might also work better
                 than gdb on some ccc-compiled code because gcc does not
                 yet generate DWARF2 debugging records on Linux Alpha by
                 default, and so its DWARF2 support on Linux Alpha is not
                 as robust as its stabs support.

              To install each of these packages (if the package is not
              already installed), use the following command:

              rpm -i package-file-name

              To see if any of these are already installed, and what
              versions they are, use the following command:

              rpm -q libots cpml_ev5 cmpl_ev6 ladebug ccc

              If you already have a package of sufficient version
              installed, there is no need to reinstall.

        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 Tru64 UNIX
              compiler. Options that do not have Tru64 UNIX equivalents
              are silently ignored by default. But overall, there is a
              reasonable probability that a makefile that works on Linux
              Alpha using the gcc compiler could be used to build the
              same application with the ccc compiler by changing only the
              compiler invocation command from gcc (or cc) to ccc.

              There is also a reasonable probability that a Tru64 UNIX
              application will build on Linux Alpha from its Tru64 UNIX
              makefile (if it is GNU compatible) by changing only the
              compiler invocation command from cc to ccc.

              A quick way to try building with ccc is to set an
              environment variable named CC to ccc, and then invoke make
              with the -e option to override the makefile's definition
              of the CC macro. In order to find out just what the ccc
              compiler is doing with your command-line options, you
              can add -v to the command line to see the programs it
              is invoking and the options it is passing to them. You
              can also set an environment variable named DRV_DUMP to
              the value 1, which causes the compiler to report any gcc
              options that are simply being parsed and consumed by the
              compiler driver without having any effect.



        6.1 Simple Optimization

              If you can successfully build your application with ccc,
              you might want to try making it run faster. There is a good
              chance that you will get some speedup over gcc by default.
              But if you've really tuned your build with gcc-specific
              optimization controls that ccc will ignore, you might have
              to do some tuning with ccc to see improvements.

              A good first attempt would be just to add -fast to the
              beginning of your compiler options. Note that the -fast
              option by default tells the compiler to generate the
              fastest code for the machine the compiler is running on.
              So if you compile on an advanced processor like EV6 (e.g.
              DS10), 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, but in this case be
              careful to verify your performance because -O4 can produce
              either faster or slower code than -O3.

              The ccc(1) man page and Programmer's Guide 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 ccc with .s or .S Files

              The ccc compiler driver has only rudimentary support for
              handling assembly language source files (.s or .S files).
              It invokes the native preprocessor (/lib/cpp) and assembler
              (/usr/bin/as) to handle these types of files, but it does
              not understand all of the command-line options that may
              be passed to them. To pass non-ccc switches through the
              ccc command line to the assembler, prepend -Wa, to the
              switch, and change any blanks that separate switch letters
              from their arguments into commas. To pass non-ccc switches
              through to the preprocessor, prepend -Wp, instead of -Wa,.

              For example, to pass -Wall to the preprocessor, enter ccc
              -Wp,-Wall foo.S. This results in -Wall being passed to the
              /lib/cpp command line.


              Switches that are handled without the need for -Wp, or -Wa,
              include:

                 -C
                 -D
                 -E
                 -I
                 -U

              If you are having problems, you can use the -v switch to
              see the transformed command line. From there you can verify
              that the switches made it through the transformation. If
              not, then use the -Wp, or -Wa, prefixing described above.
              Alternatively, you might want to change your build to avoid
              using ccc to process assembly language source files, and
              invoke gcc directly.

        7 Documentation

              NOTE:  Although the following documents are in this
              initial Beta kit, they have not yet been updated from
              the V6.4 versions.

              The man pages provided are ccc(1) and protect_headers_
              setup(8).

              A Programmer's Guide and a Language Reference Manual are
              provided in both HTML and PDf format. The ccc package
              installs these in subdirectories Programmers_Guide and
              Language_Reference under /usr/doc/ccc-6.5.6.002, with an
              index.htm file in the parent directory. All of the files
              for each document (.htm, and .pdf) are in the document's
              subdirectory. On the CDROM, the subdirectories are under
              /docs/ccc.

              Documentation for cpml is installed under /usr/doc/cpml_
              ev?-5.1.0. On the CDROM it is in /docs/cpml.

              Documentation for ladebug is a man page, ladebug(1), and
              what is installed under /usr/doc/ladebug-4.0.65. On the
              CDROM, it is in /docs/ladebug.

              libots is undocumented because the routines in it are
              intended to be called only by compiler-generated code.





        8 Redistributing Runtime Libraries with Applications

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

              If the application is linked with the -non_shared option,
              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 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 cmpl_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 6.0, 6.1, 6.2, 7.0, and 7.1 distributions
              or SuSE 6.1, 6.3, 7.0 and 7.1 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.

        9 Known Problems

              The following problem is a permanent restriction:

              o  Problems with gcc command-line options for the assembler
                 or preprocessor, as noted above under "Using ccc with .s
                 or .S files".




        10 gcc Compatibility

              There are a number of extensions to the C language that
              are documented for gcc in the GCC and CPP manuals at
              http://gcc.gnu.org/onlinedocs/ .

              As noted earlier, Compaq C implements a number of these
              extensions but not all of them. The major themes for Compaq
              C are performance, reliability, and standards compliance.
              Language extensions that are not standardized are usually
              only implemented to address a specific identified need. So
              gcc extensions that are the most likely to be implemented
              are those that match C99 features. Also, features that
              are very heavily used in applications that "ought" to
              be compiled by Compaq C for performance reasons are good
              candidates.

              While gcc does represent a defacto standard for portability
              because of its availability on so many platforms, source
              code that stays within the bounds of the formal ANSI/ISO
              standard is much more portable. It is not a goal to make
              the Compaq C compiler 100% compatible with gcc, but rather
              to reduce the difficulty of building "fairly portable"
              source code that has become somewhat dependent on gcc
              features.

              We would appreciate feedback on specific features we do not
              implement that you find would make a significant difference
              to the ease of building your code with this compiler if we
              did implement them.

        10.1 Unsupported Extensions

              The following extensions are unsupported.:

              o  enum types are compatible with unsigned int.

                 This is not an extension as much as a different
                 implementation choice. The C standard requires each
                 enum type to be compatibile with some integer type. gcc
                 chooses unsigned int (on both Tru64 UNIX and Linux),
                 while Compaq C chooses signed int (on both Tru64 UNIX
                 and Linux). This difference seems unlikely to present a
                 problem large enough to warrant a change.

              o  Preprocessor Assertions

                 The #assert/#unassert directives, and the predefined
                 assertions #system, #cpu, and #machine do not seem to be
                 in common use in user-space source code.

              o  #pragma once

                 This is already noted in the CPP manual as obsolete, and
                 Compaq C has done automatic detection of header files
                 "guarded" by conditionals to include only once for quite
                 some time.

              o  Statements and Declarations in Expressions

                 A compound statement enclosed in parentheses may appear
                 as an expression in GNU C.

              o  Locally Declared Labels

                 Support for __label__

              o  Labels as Values

                 Ability to take the address of a local label using the
                 && operator.

              o  Nested Functions

                 Ability to define a function within another function.

              o  Constructing Function Calls

                 Using any of the following:

                 o  __builtin_apply_args

                 o  __builtin_apply

                 o  __builtin_return

              o  Naming an Expression's Type

                 Using the typedef <name> = <expression> syntax.

              o  Generalized Lvalues

                 Allowing the following as lvalues if their operands are
                 lvalues: compound expressions, conditional expressions,
                 and casts.

                ________________________ Note ________________________

                ccc does accept a very limited subset of this
                capability if the K&R mode switch (-std0) is

                specified.

                ______________________________________________________

              o  Conditionals with Omitted Operands

                 Using the ?: operator without a second operand.

              o  Case Ranges

                 Specifying a range of consecutive values in a single
                 case label.

              o  Cast to a Union Type

                 Casting a scalar type to a union type.

              o  Declaration Attributes of Functions

                 Using the __attribute__ qualifier.

              o  Specifying Attributes of Types

                 Using the __attribute__ keyword on a type.

              o  Controlling Names Used in Assembler code

                 Using the asm keyword in a declaration.

              o  Variables in Specified Registers

                 Using the asm keyword in a declaration.

              o  Built-in functions

                 ccc and gcc provide a different set of built-in
                 functions. There may or may not be a ccc equivalent
                 for a gcc built-in. See the Programmer's Guide
                 and the /usr/lib/compaq/ccc-<version>/alpha-
                 linux/include/machine/builtins.h header file.

              o  Objective C

                 Compaq C tries to remain closer to standard C.

              o  Casting an expression to a union

                 An expression can be cast to a union if the union
                 contains a member of the expression's type.

        10.2 Supported or Partially Supported Extensions

              The following extensions are supported or partially
              supported in the current version of Compaq C (There are
              many other minor gcc features and behaviors in common with
              Compaq C not listed here):

              o  Prototypes and Old-Style Function Definitions

                 Using a function prototype declaration to override a
                 later old-style definition.

              o  Incomplete enum Types

                 Defining an enum tag without listing its values
                 is allowed in -std0 mode.

              o  An empty set of braces {} can be used in an initializer
                 to designate all zero values.

              o  va_start

                 The second operand to va_start can be parenthesized.

              o  #include_next

                 This is very useful in adapting to various
                 irregularities in system-supplied header files without
                 having to provide or generate entirely new versions to
                 make them compatible with the compiler.

              o  Constructor Expressions

                 Using the construct (type-name){initializer-list}. This
                 is what C99 refers to as a compound literal.

              o  Referring to a Type with typeof

                 ccc only supports the __typeof__ spelling of this
                 operator. It does not support the typeof spelling.

              o  Arrays of Length Zero

                 When arrays of zero length appear in a struct or union
                 or parameter declaration, ccc treats them the same way
                 gcc does.

                 When arrays of zero length appear elsewhere, ccc issues
                 a diagnostic and treats the array as if it were declared
                 with one element.

              o  Inquiring on Alignment

                 gcc supports the __alignof__ operator. ccc supports a
                 similar __builtin_alignof operator.

              o  Specifying Attributes of Variables

                 Although ccc does not support the __attribute__
                 keyword on declarations, it does provide some similar
                 capabilities.

                 The gcc aligned attribute corresponds to the __align
                 storage-class modifier on ccc.

                 Some of the gcc nocommon, section attributes can be set
                 using #pragma extern_model in ccc.

              o  Inline Functions

                 Both gcc and C99 define an inline (__inline) qualifier
                 for functions, and allow it to be applied to functions
                 with external linkage. Some of the details differ-in
                 particular the conditions under which a function body
                 with an external symbol is generated in the object
                 module.

                 To get the gcc behavior (the default on Linux), use the
                 command-line option -accept gccinline.

                 To get the C99 behavior (the default on Tru64
                 UNIX systems) use the command-line option -accept
                 nogccinline.

              o  Assembler Instructions with C Expression Operands

                 The compiler provides a simple but powerful form of
                 inline-assembler capability that resembles the gcc
                 feature because it looks like a function call. But the
                 detailed syntax and semantics differ substantially.
                 The Compaq C form is simple and flexible to use and
                 generally works well with the optimizer without the need
                 for semantic annotations that are often required with
                 the machine-description-based notation used by gcc.

                 See the Programmers Guide and the /usr/lib/compaq/ccc-
                 <version>/alpha-linux/include/c_asm.h header file.

              o  Function Names as Strings

                 The compiler implements the C99 __func__ predeclared
                 variable that is equivalent to the gcc variable
                 __FUNCTION__.

                 By default, the ccc driver provides a macro equivalence:
                 D__FUNCTION__ = __func__.

              o  The restrict keyword

                 In its default mode of compilation, gcc does not
                 recognize the new C99 keyword restrict (it only
                 recognizes __restrict). While ccc does recognize
                 restrict as a keyword in its default mode, the command-
                 line option -accept norestrict_keyword will give the gcc
                 behavior.

              o  Complex Numbers

                 C99 defines builtin types for complex numbers that are
                 somewhat different from the current gcc implementation.
                 ccc provides the C99 version, but not a gcc-compatible
                 variation.

              o  Macros with Variable Number of Arguments

                 C99 provides the __VA_ARGS__ identifier for in macro
                 definitions specified with ellipsis as the last formal
                 parameter.

              o  Hex Floats

                 C99 provides a means to specify floating point constant
                 values using a hexadecimal radix, e.g. 0x1.fp3.

        10.3 Likely Future Extensions

              None planned.

        11 Downloading Updates and Learning about Related Products

              For more information about software tools for Linux Alpha,
              please see the following Web page and look for the link
              for "Power Tools":

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

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

              http://www.alphalinux.org/

        12 Technical Support

              Technical support for this software is available only
              through the Peer to Peer Support program hosted at the
              University of New Hampshire:

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