		The Debian 3.0 GNU compiler suite setup
		=======================================

Abstract
--------

In Debian 3.0, the gcc-3.0 compiler first appeared. This is the next
major release of the FSF GNU compiler suite. This version was released
just before the Debian release freeze, so the gcc-2.95 compiler still
exists for its stability on all major platforms. Also, the gcc
2.7.2.3 C compiler is still available for compatibility reasons (such
as compilation of 2.0.xx kernels).

At the end you can find a summary of modifications on gcc that Debian
has made for its gcc version.


Introduction
------------

Debian 3.0 has three main sets of compiler(related) packages:

- One based on gcc-3.0.x. These include the compilers g++, gobjc, g77,
  chill, gcj and libraries libstdc++3, libobjc1, libgcj2 and libgcc1.
  On some architectures, this is the preferred C compiler which
  is called `gcc' (hppa).

- One based on gcc-2.95. These include the compilers g++, gobjc,
  g77, chill and gcj and libraries libstdc++2.9(-dev), libg++2.8.1.3(-dev).
  On most architectures gcc-2.95 provides the preferred C compiler which
  is called `gcc'.
  NOTE for ia64: The default compiler for ia64 is 2.96.

- One based on the FSF's GNU CC Compiler version 2.7.2.3
  (http://www.fsf.org/software/gcc/gcc.html).  This only encompasses the
  package `gcc272'. g++272 and libg++272 do not build from source on our
  glibc-2.1.3 based systems anymore. Please get these packages from the
  slink distribution (Debian 2.1).
  [Other distributions, i.e. Redhat cheat by including a compiled libg++272
   binary in the source package].


Why three compiler/library suites?
--------------------------------

The rationale for having two compiler/library suites is that they have
different strengths and weaknesses:

- gcc-3.0 brings a completely ANSI C++ compliant library (v3) with a
  stable ABI. Integrated Java compilers, broader architecture support.

- gcc-2.95 brings many improvements over 2.7.2.x and gcc 2.8.x: Much
  better ANSI C++ conformance, integrated SGI's STL (the standard template
  library) implementation, new compilers for Java and Chill.

- FSF gcc 2.7.2.x provides a reliable C compiler that has been used in the
  development of the 2.0.x (stable) series of Linux kernels (from which the
  Debian 2.1 default kernel is derived).
  The optimisation behaviour of gcc-2.95 is different and has caused
  gcc-2.95-compiled 2.0.x kernels not to function properly [*]; therefore
  we need an FSF gcc 2.7.2.x C compiler.

[*] If you insist on using egcs gcc-2.9x, gcc 2.8.1 or PGCC for compiling
    2.0.x kernels, you can find patches for the problems that have been found
    so far at http://www.suse.de/~florian/kernel+egcs.html .


How are the default compilers selected?
---------------------------------------

Starting in Debian 3.0, there is now a gcc-defaults package set. This
creates the actual packages for gcc, gpc, g++, gobjc, chill, g77 and gcj.
These packages will depend on the corresponding default compiler for that
architecture. For example, on i386, "gcc" depends on "gcc-2.95", which
means that the "gcc-2.95" package will install a binary called "gcc-2.95",
which is symlinked to in the "gcc" package as "gcc".

This may seem confusing, but what it allows you do to is install two
versions of the GCC compiler suite at the same time, making sure you are
always using the one preferred for that architecture. To use the other
compiler, simply set CC=gcc-3.0, or similar.

With this method, each architecture can choose its own preferred compiler,
and that preference can change without requiring a complete rebuild of both
compiler packages for all architectures. (to change the names), and simply
requires updating the small gcc-defaults package set, to point the symlinks
correctly.


Practical implications
----------------------

The most important practical implications are in the merging/linking
of object files built with different compilers; If you use the 2.7.2.x
C compiler, you should use the `gcc272' compiler driver for all your work.
When configuring sources, use

    CC=gcc272 ./configure <configure options> 	# bash
    setenv CC gcc272; ./configure <options>	# csh

When calling make, use `make CC=gcc272'.

To compile a 2.0.xx kernel the gcc272 package should be used. If you use
the Debianized kernel source (package kernel-source-2.0.38), then gcc272
is used by default. If you compile upstream source, make sure to use gcc272
in the toplevel makefile.

C++ libraries
-------------

Some notes on porting applications from libstdc++-2.90 (or earlier versions)
to libstdc++-v3 can be found in the libstdc++3-doc package. After the
installation of the package, look at:

/usr/share/doc/gcc-3.0-base/libstdc++/html/17_intro/porting-howto.html

There have been some upstream changes in the C++ libraries that can create
confusion. With gcc 2.7.2.x, there was only one upstream C++ library: libg++
(in older Debian releases: libg++272 and libg++272-dev). This contained both
the C++ standard library, a (hacked up?) version of the C++ standard template
library (reflecting the draft version of that available at the time gcc
2.7.2.x was released) and a large number of GNU-specific classes. In the
time between the release of gcc 2.7.2.x and the current egcs version, the
development of the STL proceeded (incorporating a lot of functionality
similar to that in the GNU-specific classes of libg++ 2.7.2.x)) and the
ANSI/ISO C++ draft was extended, refined and finally accepted.

As a result of these developments, with the release of gcc 2.8.0 (i.e. at
the starting point of the egcs project) libg++ was broken up into three parts
upstream:
- gperf, the perfect hash function generator.
- libstdc++ 2.10 (in Debian: libstdc++2.10 and libstdc++2.10-dev), containing
  only the standard C++ library and the STL.
- libg++ 2.8.x (in Debian: libg++2.8.1.3 and libg++2.8.1.3-dev), containing only
  the GNU-specific classes. As most of the functionality in these is present
  in standardised fashion in libstdc++, there will be no further development
  of this. If you maintain code that uses the GNU-specific classes, you
  are strongly encouraged to move to using the standard classes of
  libstdc++ .

Code compiled with gcc-2.95.2 has to use the libstdc++2.10 libraries. Many
programs however are still linked with libstdc++2.8, which was part of
the egcs-1.0.x compilers.

Now, with the gcc-3.0 compiler, we also have the libstdc++3 libraries,
deprecating the libg++ libraries all together, and bring a stable ABI to
GCC's C++ interface. Also, 2.95 and prior always had a libgcc.a library
that was linked to by all applications that gcc built. This has now been
made available as a shared library, libgcc.so, which is in the libgcc300
package.

Java
----

gcj currently has no documentation besides the online documentation found at

	http://sourceware.cygnus.com/java/

To compile a simple Hello World program:

	gcj --main=HelloWorld -o HelloWorld HelloWorld.java

Objective-C
-----------

The Objective-C runtime changed from gcc version 2.7 to 2.8. ObjC-Code
compiled with gcc 2.7.2 is not compatible with ObjC-code compiled with
gcc 2.8, egcs or gcc-2.95.2. The ObjC compiler is normally called like the C
compiler (`cc'). Debian/Linux only has the ObjC compiler from the
2.95.2 code base.

You have to link your ObjC programs with the thread library
(-lpthread), because ObjC was built to support threads.

Pascal
------

In the gcc-2.95 packages, a Beta version of GNU Pascal 2.2 is included.
Curently gpc doesn't build with gcc-3.0.

Bugs
----

Before submitting a bug, please read README.Bugs in this directory.

Feedback appreciated
--------------------

Feedback about this document is appreciated; preferably as a Severity:
wishlist bug against Package: gcc-3.0 . For general discussions and
questions, subscribe and/or email the debian-gcc@lists.debian.org mailing
list.


Maintainers of these packages
-----------------------------

Matthias Klose <doko@debian.org>
Ray Dassen <jdassen@debian.org>
Philip Blundell <pb@debian.org>			(arm-linux)
Ben Collins <bcollins@debian.org>		(sparc-linux)
Christopher C. Chimelis <chris@debian.org>	(alpha-linux)
Randolph Chung <tausq@debian.org>		(ia64-linux)
Dan Jacobowitz <dan@debian.org>			(powerpc-linux)
Gerhard Tonn <GerhardTonn@swol.de>		(s390-linux)
Roman Zippel <zippel@linux-m68k.org>		(m68k-linux)

===============================================================================

Patches applied in this version:

gcc-version:

glibc-version:
  fix glibc version at 2.2

libg++-update:
  2000-03-12  Manfred Hollstein  <manfredh@redhat.com>
  
  	* Fix.h (Fix::Rep): Move definition into public context.

bootstrap:
  Make bootstrap: restartable at any point
  From: Donn Terry <donn@interix.com>

cpp-macro-doc:
  cpp.texi: add a node documenting macro varargs.

gcc-default-arch:
  set the default architecture to i386; even if gcc is configured
  with i386-linux, it builds with Pentium instructions, tuned for i386.

libstdc++-out-of-mem:
  Throw exception instead of aborting when out of memory

libstdc++-wstring:
  enable definition of wstring type, if __ENABLE_WSTRING is defined.

libstdc++-bastring:
  Here is a patch to /usr/include/g++-2/std/bastring.h which makes it
  work for me (though note that I have not tested the c_str() method as
  such):

gcc-manpage:
  Document exit codes.

cpp-dos-newlines:
  Handle DOS newlines after backslashes.
  Patch from http://www.cygnus.com/ml/egcs/1999-Jan/0784.html

libio-doc:
  iostream.texi (Files): Use octal numbers in examples.

gcc-doc:
  extend.texi (Nested Functions): Update URL of Usenix paper.
  invoke.texi Fix typo (-fstd -> -std).

strength-red:
  From: Alan Modra <amodra@bigpond.net.au>
  To: gcc-patches@gcc.gnu.org
  Subject: gcc-2.95 strength reduction fix
  Date: Mon, 3 Dec 2001 14:51:31 +1030
  This particular problem was fixed on the mainline by
  http://gcc.gnu.org/ml/gcc-patches/2000-04/msg00576.html, which is a
  much nicer fix than the following but a minimal change may be preferred
  for the 2.95 branch.
  
  	* loop.c (strength_reduce <giv loop>): Set up maybe_multiple for givs.
  	(record_giv): Pass in maybe_multiple.
  	(find_mem_givs): Likewise.

gcc-messages:
  avoid setlocale(LC_MESSAGES, ...) not to set LC_MESSAGES, because
  some environment except for setting LANG=C fail to display libc 
  message.

gcc-gas-hidden:

ppc-fsirl-updates:
  Various updates from Franz Sirl, including DWARF EH support.
  ftp://devel.linuxppc.org/users/fsirl/
  this patch includes the following Debian patches:
  - gcc-weaksym
  excluded:
  - gcc/version.c
  - objc-testsuite

gcc-names:
  versioned gcc names

libio-names:
  versioned iostream info names

chill-names:
  versioned gcc names

g77-docs:
  Update g77 documentation as proposed in 
  http://gcc.gnu.org/ml/gcc-bugs/1999-11/msg00846.html

libf2c-mkstemp:
  use mkstemp in libf2c/libI77
  taken from http://gcc.gnu.org/ml/gcc-patches/2000-11/msg00708.html

g77-names:
  versioned g77 names

libobjc:
  Find header file for Boehm garbage collector.

objc-data-references:
  Subject: PATCH: use non-readonly data section for objc references 
  From: Todd Vierling <tv at wasabisystems dot com> 

reporting:
  <compiler> --help gives hint to /usr/share/doc/debian/bug-reporting.txt

gpc-2.95:
  The gpc patch from the gpc tarball.

gpc-updates:

gpc-names:
  versioned gpc names

arm-pic:
  Some fixes for ARM from Philip Blundell

arm-nested-func:
  ARM patch for nested functions

arm-various:
  Some fixes for ARM from Philip Blundell

arm-exception:
  ARM patch for PIC exception handlers

arm-const-double:
  ARM patch for const_double, courtesy Richard Earnshaw

arm-tune:
  ARM patch for default tuning and optimized return

arm-output-int:
  ARM patch for large constant generation

libgcc-umodsi3:
  <your description>
  2000-08-22  Nick Clifton  <nickc@redhat.com>
  
  	* config/arm/lib1funcs.asm (__umodsi3): Before performing any
  	restorative additions, test for bottom bits of IP being set,
  	rather than relying upon the RORs not matching.
  	(__modsi3): Ditto.
