Solaris-2 Developer's Kit release 1.0
*************************************

This product includes software developed by the University of California, Berkeley and its contributors.

This file is copyright © 1992 Cygnus Support

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions

Overview
********

Cygnus Support Developer's Kit

Solaris-2 Release 1.0

Sun has unbunded its compilers---selling them separately from the Solaris 2.0 operating system.  Many Sun users were unhappy that their next upgrade might take away their C compiler.

In response, Cygnus Support ported the GNU C compiler and supporting tools to Solaris 2.0.  The result is a full set of development tools---ANSI and traditional C compiler (with supporting libraries), debugger, parser generator, and lexical analyzer generator---freely available to everyone.

The GNU C compiler can be used to compile any kind of program: public domain, copyleft, or proprietary.  Your binaries have the same copyright status as your sources and libraries.  The only provision of the GNU General Public License that applies to users of the compiler (as opposed to people who make copies of the compiler, or modify it) is the lack of warranty (section 11 and 12).  FSF does not provide a warranty to anyone, but Cygnus gives a 1-year limited warranty (a year of support) to customers.

Contributors to GNU C for Solaris-2
***********************************

Cygnus Support and the FSF are grateful to the forward-looking individuals and organizations that sponsored this project.

We are glad to be able to thank publicly:

  * Amoco Production Company (Houston, Texas)

  * BBN Communications (Cambridge, Massachusetts)

  * Boston Technology (Wakefield, Massachusetts)

  * Cirrus Logic (Fremont, California)

  * Compaq Computer Corporation (Houston, Texas)

  * Deere & Company (Moline, Illinois)

  * ELF Commnuications (San Francisco, California)

  * European Computer-Industry Research Centre GMBH (Munich)

  * Fidelity Investments (Boston, Massachusetts)

  * FTP Software, Inc. (Wakefield, Massachusetts)

  * Gallagher & Robertson (Oslo, Norway)

  * GTE Laboratories (Waltham, Massachusetts)

  * Ingres Corporation (Alameda, California)

  * Inland Sea (Dexter, Michigan)

  * Los Alamos National Laboratory (Los Alamos, New Mexico)

  * Miller/Howard Investures (Cobleskill, New York)

  * MIT Lincoln Laboratory (Lexington, Massachusetts)

  * NASA Lewis Research Center (Cleveland, Ohio)

  * Optimation Software (Melbourne, Australia)

  * PFU Limited (Tokyo)

  * Philips Laboratories (Briarcliff Manor, New York)

  * Pure Software (Los Altos, California)

  * Qualix Group, Inc. (San Mateo, California)

  * Schlumberger-Doll Research (Ridgefield, Connecticut)

  * Kevin Sheehan (Melbourne, Australia and elsewhere)

  * State University of New York (SUNY) at Buffalo

  * SunSoft, Inc. (Mountain View, California)

  * Technische Universitaet Muenchen (Munich)

  * Telecom Finland (Helsinki)

  * Telecom Research Labs (Victoria, Australia)

  * Union Bank of Switzerland (Zurich)

  * University of Pennsylvania (Philadelphia)

  * University of Washington (Seattle)

  * UUNET Technologies, Inc. (Falls Church, Virginia)

  * Warwick University (Coventry, England)

  * Xerox Palo Alto Research Center (Palo Alto, California)

We are also grateful to six other organizations and individuals who contributed to this project, but prefer to remain anonymous.

Closest FSF Versions
********************

Cygnus Support devotes much of its effort to integrating and improving free software.  In fact, Cygnus employees are the primary developers of several important components of the GNU tool-chain (on behalf of the Free Software Foundation).  However, especially for programs whose FSF releases are issued elsewhere, our releases are often slightly ahead of the nearest corresponding FSF version (and sometimes slightly behind it).  We reintegrate our sources with the FSF as frequently as possible without compromising the stability of the integrated toolchain.

These are the nearest corresponding FSF releases of the GNU development tools:

Program
     Last merged with FSF version

gcc
     2.0 (but many improvements from 2.1 and 2.2 incorporated)

gdb
     4.6 (maintained at Cygnus)

New in This Release
*******************

GCC
     Near command-line compatibility with the SVID specification for cc, and with the SVr4 cc.  ELF output (with embedded stabs format debugging information; this is compatible with Sun's compilers).  Many bug-fixes (from the base FSF level, and from our Progressive--920318 release for SunOS).

CPP
     New directive #assert; you can use this directive, together with enhancements to #if, to declare and test for particular system properties.

GDB
     GDB understands the debugging format used by Solaris-2 compilers (both ours and Sun's): stabs debugging information embedded in ELF object files.

     Since our Progressive--920318 release for SunOS, we have also made these improvements to GDB:

     Many bug fixes.

     GDB now uses a new memory manager called mmalloc, an enhancement of GNU malloc.  It can greatly speed up the startup of GDB by using a pre-parsed symbol table in a mmalloc-managed heap. Since memory-mapped files are available on Solaris-2 through the mmap system call, you can have GDB write the symbols from your program into a reusable file.

FLEX and BYACC
     Release 1.0 for Solaris 2 includes flex, the fast lexical analyzer generator, and byacc, the parser generator---both from UC Berkeley.  There are no restrictions on what use you can make of lexical analyzers generated by flex, or parser generators built by byacc.

     Since flex and byacc are of interest only to a specialized audience, we ship only on-line documentation for them. See flex.info, or the man pages flex.1 and byacc.1.

Problem Reports
     The script install_cid is now available to record your Cygnus customer ID for the problem-reporting utility, send_pr, on your system.

     A blank Problem Report form is now included in the Introduction to your Developer's Kit manuals, in case FAX is more convenient than electronic mail to send us problem reports.

     Since these programs are free software, many people who receive them will not get them directly from Cygnus Support.  We will be glad to support you no matter where you got the software.  If you have not yet bought support from Cygnus for this set of tools, you can call us at +1 415 322 3811 for a support contract, and start reporting problems and getting fixes.

Limitations and Warnings
************************

Our major goals in this release was compatibility: with the System V Interface Definition (SVID), with other Solaris-2 tools, and with the SPARC Application Binary Interface (ABI).

We have been largely successful: our toolchain complies with the SVID specifications for compilation tools, most of the tools are also command-line compatible with the Sun offerings (even in cases where these go beyond the SVID), and we know of only one violation of the ABI.

The following sections give details on the few remaining compatibility issues.

Some Solaris-2 cc options are not accepted
==========================================

In porting the GNU C compiler to Solaris-2, we wanted to have command-line compatibility with several compilers:

  * SVID specification for cc

  * Other GCC configurations

  * Unix SVr4 implementation of cc

  * Sun compiler for Solaris-2

Unfortunately, these specifications are not altogether compatible; we have compromised in some areas, giving the most weight to the SVID specification and to GCC on other platforms.

Here is a list of command line options not accepted by gcc, but meaningful in one of the other command-line specifications listed:

-Bstatic
-Bdynamic
     Use -static or -symbolic instead.  (-Bstatic and -Bdynamic are supported by Sun compilers, but are not in the SVID.)

-dy
-dn
     These Solaris-2 linker options conflict with GCC debugging options. Again, use -symbolic or -static instead; or pass the linker options directly to the linker using -Xlinker or -W.

-f
     GCC has a large family of options that begin with -f.  All of these options are supported as in other versions of GCC.  The SVr4 specification describes this option as accepted, but ignored; in the SVID, it is used to specify floating-point emulation.

-J sfm
     This SVr4 option appears to specify linking against a special-purpose subroutine library.  It is not in the SVID, and GCC does not support it.

-K
     GCC does not support -K.  To specify position-independent code output, use -pic.

-P
     This preprocessor option retains its usual GCC meaning, which is slightly different from the SVID and SVr4 descriptions (which are not quite identical with one another).  It is used to generate preprocessor output---similar to -E, but without embedding #line directives.  However, for GCC, the output still goes to stdout rather than to a .i file.  To place output in a .i file, use command-line output redirection.

-q
     This option is defined as implementation-specific by the SVID. This implementation does not include it.

-V
     Displays version information for only the assembler and linker.

-v
     Displays the full invocation of each compiler pass, as usual for GCC.  This option is not defined in the SVID, but the SVr4 documentation describes it as similar to the GCC options -pedantic or -pedantic-errors.  We recommend using those options instead.

-W
-Y
     In this implementation, -W and Y are restricted to controlling the assembler and linker (the other compiler passes used by GCC do not exactly correspond to those in the SVID).

-X
     This option is not in the SVID, but is used in SVr4 to give a little control over the dialect of C.  For this purpose, you can use the standard GCC options -traditional, -ansi, or the other options described in Options Controlling Dialect (Using gcc).

For full descriptions of the GCC command line options in this release, see the manual Using gcc, or the man page gcc.1.

Using gdb on Sun Compiler Output
================================

By default, the Sun compiler cc and the system assembler as omit debugging information from the final linked output file, assuming the debugger will look in the .o files for this information.  gdb will not do this.  If you have the Sun compiler cc and want to debug its output with gdb, you must include the command-line flag -xs when you run cc, to instruct it to place debugging information where it will be copied to the linked output file.  Similarly, if you call the system assembler as directly, use its command-line option -s for the same purpose.

The long double datatype violates SPARC ABI
===========================================

The SPARC Application Binary Interface (ABI) specifies that numbers of type long double take up 16 bytes.  In this release, gcc only emits 8-byte numbers for long double.

This is the only known violation of the ABI.  We will fix this problem in a future release.

No independent verification of ABI compliance
=============================================

We have made every effort to comply with the SPARC ABI, and we are aware of only one violation (noted above).  However, there is as yet no independent verification of our compiler's compliance.

SPARC International is preparing an ABI compliance test suite, but it won't be available until sometime in the autumn of 1992.  We will seek verification of our compiler's compliance as soon as SPARC International is ready.