Updated 00/04/05 Sun WorkShop(TM) Compilers C++ 6 Readme Introduction This document contains last minute information about the Sun WorkShop 6 C++ compiler. It describes the software corrections addressed by this release and lists the known problems, limitations, and incompatibilities. To view the text version of this document, type the following at a command prompt: example% CC -xhelp=readme To access the HTML version of this document, point your Netscape(TM) Communicator 4 or compatible Netscape version browser to: file:/opt/SUNWspro/docs/index.html Note - If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system. For more information about this product, see: * Sun WorkShop 6 Release Notes -- Describes installation-related and late-breaking information about this Sun WorkShop release. Information in the release notes overrides information in all readme files. * About Sun WorkShop 6 Documentation -- Describes the documentation available with this Sun WorkShop release and how to access it. * What's New in Sun WorkShop 6 -- Describes the new features in this release. These documents are accessible in HTML by pointing your browser to file:/opt/SUNWspro/docs/index.html. If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system. Contents A. About the Sun WorkShop 6 C++ Compiler B. Software Corrections C. Problems and Workarounds D. Limitations and Incompatibilities E. Documentation Errata F. Shippable Libraries G. New Features H. Standards Not Implemented ------------------------------------------------------------------------ A. About the Sun WorkShop 6 C++ Compiler The Sun WorkShop 6 C++ compiler (CC) runs on SPARC(TM) processors running Solaris(TM) SPARC Platform Edition versions 2.6, 7, and 8, and Intel(R) processors running Solaris Intel Platform Edition, versions 2.6, 7, and 8. Information unique to one or more platforms is identified as "(SPARC)" or "(IA)." ------------------------------------------------------------------------ B. Software Corrections Template Syntax Error is No Longer Ignored The following template syntax has never been valid, but Sun C++ 4 and 5.0 did not report the error. template class MyClass { ... }; // definition error template class MyClass; // declaration error In both cases, the "" on "MyClass" is invalid, and must be removed, as shown in the following example: template class MyClass { ... }; // definition template class MyClass; // declaration ------------------------------------------------------------------------ C. Problems and Workarounds This section discusses the following software bugs that could not be fixed in time for this release. For updates, check Hot News for Sun WorkShop 6 (http://www.sun.com/workshop/users/ws.html). 1. Name Mangling Linking Problems 2. Using make With Standard Library Header Files on Versions 2.6 and 7 of the Solaris Operating Environment 3. -ptr Option is Obsolete but No Warning 4. Debugging Tools Erroneously Report Extra Leading Parameter for Member Functions 5. Reference From Template to Non-Global File-Scope Object is Not Supported 6. Standard Header Warning Messages 7. #pragma align Inside Namespace Requires Mangled Names 8. __ctype Not Defined Errors 1. Name Mangling Linking Problems The following conditions may cause linking problems: o A function is declared in one place as having a const parameter and in another place as having a non-const parameter. Example: void foo1(const int); void foo1(int); These declarations are equivalent, but the compiler mangles the names differently. o A function has two parameters with the same composite type, and just one of the parameters is declared using a typedef. Example: class T; typedef T x; // foo2 has composite (that is, pointer or array) // parameter types void foo2(T*, T*) void foo2(T*, x*); void foo2(x*, T*); void foo2(x*, x*); All declarations of foo2 are equivalent and should mangle the same. However, the compiler will mangle some of them differently. New extensions to #pragma weak allow you to work around some mangling problems. o First, if possible, rewrite the function so that it is consistent in its use of typedefs. o Second, in the file that defines the function use a weak symbol to equate a declaration with its definition. For example: #pragma weak "__1_undefined_name" = "__1_defined_name" Note -- Some mangled names are dependent on the target architecture. (For example, size_t is unsigned long for the SPARC V9 architecture, and unsigned int otherwise.) In such a case, two versions of the mangled name will be involved, one for each model. Two pragmas must be provided, controlled by appropriate #if directives. For more information, see the C++ Migration Guide. To access this guide in HTML, point your browser to file:/opt/SUNWspro/docs/index.html. For related information, see Name Mangling Incompatibility With Some Early Access Releases in Section D of this document. 2. Using make With Standard Library Header Files on Versions 2.6 and 7 of the Solaris Operating Environment The standard library file names do not have ".h" suffixes. Instead, they are named istream, fstream, and so forth. In addition, the template source files are named istream.cc, fstream.cc, and so forth. If, in the Solaris 2.6 or 7 operating environment, you include a standard library header in your program, such as , and your makefile has .KEEP_STATE, you will encounter problems. For example, if you include , make thinks that istream is an executable and uses the default rules to build istream from istream.cc resulting in very misleading error messages. (Both istream and istream.cc are installed under the C++ include files directory). Here are possible workarounds: o Use the -r option which disables the default make rules. This solution may break the build process. o Use the dmake utility in serial mode instead of make: dmake -m serial o Avoid the use of .KEEP_STATE. 3. -ptr Option is Obsolete but No Warning The -ptr option is obsolete. However, the compiler will not emit a warning that the option is ignored. 4. Debugging Tools Erroneously Report Extra Leading Parameter for Member Functions In compatability mode (-compat=4), the C++ compiler incorrectly mangles the link names for pointers to member functions. The consequence of this error is that the demangler, and hence some debugging tools, like dbx and c++filt, report the member functions as having an extra leading parameter consisting of a reference to the class type of which the function is a member. To correct this problem, add the flag -Qoption ccfe -abiopt=pmfun1. Note, however, that sources compiled with this flag may be binary incompatible with sources compiled without the flag. In standard mode (the default mode), there is no problem with mangled names. 5. Reference From Template to Non-Global File-Scope Object is Not Supported A program using templates and static objects causes link-time errors of undefined symbols. The compiler currently does not support reference to non-global file-scope objects from templates 6. Standard Header Warning Messages There are known problems with standard headers that cause lots of warnings when +w is used. 7. #pragma align Inside Namespace Requires Mangled Names When you use #pragma align inside a namespace, you must use mangled names. For example, in the following code, the #pragma align statement has no effect. To correct the problem, replace a, b, and c in the #pragma align statement with their mangled names. namespace foo { #pragma align 8 (a, b, c) static char a; static char b; static char c; } 8. __ctype Not Defined Errors The Solaris 8 operating environment has a bug that can cause "__ctype not defined" errors from the C++ compiler when you use MB_CUR_MAX from . The bug will be fixed in an update to the Solaris 8 operating environment. The workaround is to include the standard header as well as the header . ------------------------------------------------------------------------ D. Limitations and Incompatibilities 1. C++ Shared Library Patch A SUNWlibC patch is provided for each version of the Solaris Operating Environment supported by this Sun WorkShop 6 release on each of the supported platforms. Without these patches, some programs will not link and some programs will terminate in unusual ways due to runtime errors. For more information about the shared library patch for C++, see the Sun WorkShop 6 Release Notes, accessible in HTML by pointing your browser to file:/opt/SUNWspro/docs/index.html and clicking on the document title. (If your Sun WorkShop software is not installed in the /opt directory, ask your system administrator for the equivalent path on your system.) 2. Compiler Version Incompatibilities The remainder of this section discusses the incompatibilities between Sun WorkShop C++ compiler versions 4.0, 4.1, 4.2, and the following versions: * Sun WorkShop C++ compiler 5.0 * Sun WorkShop 6 C++ compiler 5.1 a. Cache Version Differences May Cause Compilation Errors b. Name Mangling Incompatibility With Some Early Access Releases c. C++ Interface Incompatibilities d. Using Tools.h++ With iostreams e. Using Multiple Template Repositories; -ptr Option Ignored f. Linking With 4.0.1 Libraries Containing Pointers to const Member Functions g. Linking With Libraries Compiled With Earlier Compilers h. Mixing Object Code From Different Versions 1. Cache Version Differences May Cause Compilation Errors When upgrading compilers, it is always good practice to run CCadmin -clean on every directory that contains a SunWS_cache subdirectory (alternately, you can use rm -rf SunWS_cache). Failure to do so can result in compilation errors such as the following: o SunWS_cache: Error: Database version mismatch /SunWS_cache/CC_version. o "/SunWS_cache/CC_state", line 3: Error: "" not allowed here. ** Assertion ** : 0 2. Name Mangling Incompatibility With Some Early Access Releases Code that is compiled with this version of the compiler will link with code that was compiled with the Sun WorkShop C++ 5.0 compiler. However, code compiled by the early access versions prior to EA5 might not link with code compiled by this version of the compiler because of name mangling incompatibilities. If you have code that was compiled by early access Sun WorkShop 6 C++ compiler versions EA0, EA1, EA2, EA3, or EA4, delete the old .o files and clean the SunWS_cache subdirectories. 3. C++ Interface Incompatibilities The Sun WorkShop 6 C++ compiler is not binary compatible with versions 4.0, 4.1, and 4.2 of the compiler unless the -compat option is used with the Sun WorkShop 6 C++ compiler. The incompatibility is due to the changes in the class layouts, the calling sequences, and the way names are mangled to meet the requirements defined in the ANSI/ISO C++ Standard. The SunWorkShop 6 C++ compiler and the Sun WorkShop C++ compiler 5.0 are binary compatible. See the C++ Migration Guide for more information. To access this document in HTML, point your browser to file:/opt/SUNWspro/docs/index.html. 4. Using Tools.h++ With iostreams The C++ compiler now uses standard iostreams as the default. However, Tools.h++ version 7 is built with classic iostreams. If you use Tools.h++ in standard mode, you must include libiostream as shown in the following compiler option: -library=rwtools7,iostream See the C++ Migration Guide for more information. To access this guide in HTML, point your browser to file:/opt/SUNWspro/docs/index.html. 5. Using Multiple Template Repositories; -ptr Option Ignored In compilers prior to C++ compiler 5.0, the -ptr flag was used to designate repositories for template instantiations. With the C++ compiler 5.0 and with the Sun WorkShop 6 C++ compiler, the -ptr flag is no longer required, as the compilation system reads from the template repositories corresponding to the object files that it reads, and writes template instances into the repository contained in the directory of the output location specified by the CC command. In this release, the -ptr option is obsolete and is ignored by the compiler. Even though the option is ignored, you should remove -ptr from all compilation commands because, in a later release, it may be reimplemented with a different behavior. Note -- Sharing a single template repository for more than one application or library has not been and is currently not supported. Attempting to do so can lead to compilation failure and unpredictable results at runtime because of template redefinitions. 6. Linking With 4.0.1 Libraries Containing Pointers to const Member Functions The C++ 4.0.1 compiler generated different mangled names for pointers to const member functions than the C++ compiler versions 4.1, 4.2, 5.0, and the Sun WorkShop 6 C++ compiler do. If you are using the Sun WorkShop 6 C++ compiler and you are unable to link with a library that was built with 4.0.1 and that contains such names, you should either recompile the library, or compile the rest of the program with the -compat -Qoption ccfe -abirel=4.0.1 flags. 7. Linking With Libraries Compiled With Earlier Compilers The C++ 4.0.1 and C++ 4.1 compilers generated a mangled name that was unparsable for templates instantiated with an extern "C" function. As a consequence, debugging tools behaved incorrectly. We have corrected the problem, but some users may be unable to link objects that are compiled with either the C++ 5.0 compiler or the Sun WorkShop 6 C++ compiler with libraries compiled with earlier compilers. This incompatibility should be extremely rare, but in the event that it does happen, you can either o Recompile the library with the Sun WorkShop 6 C++ compiler, or o Compile the new objects using the Sun WorkShop 6 C++ compiler with the -compat=4 and -Qoption ccfe -abirel=4.1 flags. 8. Mixing Object Code From Different Versions You can mix object code from different versions of the SunWorkShop C++ compiler in the same program, as long as you don't mix compatibility-mode and standard-mode code. However, you must link the final program using a compiler at least as new as the newest compiler version in the mix. ------------------------------------------------------------------------ E. Documentation Errata * Section 1.3.2 "Mixing Old and New Binaries" of the C++ Migration Guide says that you can mix code if no exceptions cross the boundary, but we have found that not to be true. If you mix compat=4 with compat=5 code in the same program, you can use exceptions in the compat=4 code or in the compat=5 code, but not in both. If you have exceptions in the compat=4 code, link libC before linking libCrun. If you have exceptions in the compat5 code, link libCrun before linking libC. * The C++ User's Guide does not mention generic64 and native64 as possible settings for -xtarget, -xarch, and -xchip. See the CC(1) man page for details. ------------------------------------------------------------------------ F. Shippable Libraries If your executable uses a Sun dynamic library listed in the file named below, your license includes the right to redistribute the library to your customer. /SUNWspro/READMEs/runtime.libraries (Replace with the path to your Sun WorkShop installation directory. In a default installation, is /opt.) You may not redistribute or otherwise disclose the header files, source code, object modules, or static libraries of object modules in any form. The License to Use appears in the End User Object Code License, viewable from the back of the plastic case containing the CDROM. ------------------------------------------------------------------------ G. New Features This version of the Sun WorkShop C++ compiler includes the following new features: 1. Partial Specialization 2. Explicit Function Template Argument 3. Non-Type Function Template Parameters 4. Member Templates 5. Definitions-Separate Template Organization Restriction Removed 6. Prefetch Instructions 7. Extern Inline Functions 8. Ordering of Static Variable Destruction 9. Sub-Aggregate Initialization 10. Using Your Own C++ Standard Library 11. Cache Versioning 12. Restrictions on Bitfield Size Removed 13. Warnings About Conversions Between Pointer-To-Function and void* 14. New and Changed Options 1. Partial Specialization A template can be (fully) specialized, meaning that an implementation is defined for specific template arguments. For example: template class A { ... }; //primary template template<> class A { ... }; //specialization A template can also be partially specialized, meaning that only some of the template parameters are specified, or that one or more parameters are limited to certain categories of type. The resulting partial specialization is itself still a template. The following examples use the previous primary template: template class A { ... }; // Example no. 1 template class A { ... }; // Example no. 2 template class A { ... }; //Example no.3 o Example 1 provides a special template definition for cases when the first template parameter is type int. o Example 2 provides a special template definition for cases when the first template parameter is any pointer type. o Example 3 provides a special template definition for cases when the first template parameter is pointer-to-pointer of any type, and the second template parameter is type char. 2. Explicit Function Template Argument If a template argument cannot be deduced from the function arguments, you can now specify it explicitly using the syntax f