Import of unmodified (but trimmed) gcc-2.7.2. The bigger parts of the

[FreeBSD/FreeBSD.git] / contrib / gcc / cp / reno.texi

\input texinfo       @c                    -*- Texinfo -*-
@setfilename reno-1.info

@ifinfo
@format
START-INFO-DIR-ENTRY
* Reno 1: (reno-1).             The GNU C++ Renovation Project, Phase 1.
END-INFO-DIR-ENTRY
@end format
@end ifinfo

@ifinfo
Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc.

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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore

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.
@end ifinfo

@setchapternewpage odd
@settitle GNU C++ Renovation Project
@c @smallbook

@titlepage
@finalout
@title GNU C++ Renovation Project
@subtitle Phase 1.3
@author Brendan Kehoe, Jason Merrill,
@author Mike Stump, Michael Tiemann
@page

Edited March, 1994 by Roland Pesch (@code{pesch@@cygnus.com})
@vskip 0pt plus 1filll
Copyright @copyright{} 1992, 1993, 1994 Free Software Foundation, Inc.

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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

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.
@end titlepage

@ifinfo
@node Top
@top @sc{gnu} C++ Renovation Project

This file describes the goals of the @sc{gnu} C++ Renovation Project,
and its accomplishments to date (as of Phase 1.3).

It also discusses the remaining divergences from @sc{gnu} C++, and how the
name encoding in @sc{gnu} C++ differs from the sample encoding in
@cite{The Annotated C++ Reference Manual}.
@c This is not a good place to introduce the acronym ARM because it's
@c info-only. 

@menu
* Introduction::        What is the GNU C++ Renovation Project?
* Changes::             Summary of changes since previous GNU C++ releases.
* Plans::               Plans for Reno-2.
* Templates::           The template implementation.
* ANSI::                GNU C++ conformance to ANSI C++.
* Encoding::            Name encoding in GNU C++.
@end menu

@end ifinfo

@node Introduction
@chapter Introduction

As you may remember, @sc{gnu} C++ was the first native-code C++
compiler available under Unix (December 1987).  In November 1988, it was
judged superior to the AT&T compiler in a Unix World review.  In 1990 it
won a Sun Observer ``Best-Of'' award.  But now, with new requirements
coming out of the @sc{ansi} C++ committee and a growing backlog of bugs, it's
clear that @sc{gnu} C++ needs an overhaul.

The C++ language has been under development since 1982.  It has
evolved significantly since its original incarnation (C with Classes),
addressing many commercial needs and incorporating many lessons
learned as more and more people started using ``object-oriented''
programming techniques.  In 1989, the first X3J16 committee meeting
was held in Washington DC; in the interest of users, C++ was going to
be standardized.

As C++ has become more popular, more demands have been placed on its
compilers.  Some compilers are up to the demands, others are not.
@sc{gnu} C++ was used to prototype several features which have since
been incorporated into the standard, most notably exception handling.
While @sc{gnu} C++ has been an excellent experimental vehicle, it did
not have the resources that AT&T, Borland, or Microsoft have at their
disposal.

We believe that @sc{gnu} C++ is an important compiler, providing users with
many of the features that have made @sc{gnu} C so popular: fast compilation,
good error messages, innovative features, and full sources that may be
freely redistributed.  The purpose of this overhaul, dubbed the @var{@sc{gnu}
C++ Renovation Project}, is to take advantage of the functionality that
@sc{gnu} C++ offers today, to strengthen its base technology, and put it in a
position to remain---as other @sc{gnu} software currently is---the technical
leader in the field.

This release represents the latest phase of work in strengthening the
compiler on a variety of points.  It includes many months of
work concentrated on fixing many of the more egregious bugs that
presented themselves in the compiler recently.
@ignore
@c FIXME-- update?
Nearly 85% of all bugs reported in the period of February to September
of 1992 were fixed as part of the work in the first phase.
@end ignore
In the coming months, we hope to continue expanding and enhancing the
quality and dependability of the industry's only freely redistributable
C++ compiler.

@node Changes
@chapter Changes in Behavior in @sc{gnu} C++

The @sc{gnu} C++ compiler continues to improve and change.  A major goal
of our work has been to continue to bring the compiler into compliance
with the draft @sc{ansi} C++ standard, and with @cite{The Annotated C++
Reference Manual} (the @sc{arm}).  This section outlines most of the
user-noticeable changes that might be encountered during the normal
course of use.

@menu
* Summary of Phase 1.3::
* Major changes::
* New features::
* Enhancements and bug fixes::
* Problems with debugging::
@end menu

@node Summary of Phase 1.3
@section Summary of Changes in Phase 1.3

The bulk of this note discusses the cumulative effects of the @sc{gnu} C++
Renovation Project to date.  The work during its most recent phase (1.3)
had these major effects:

@itemize @bullet
@item The standard compiler driver @code{g++} is now the faster compiled
version, rather than a shell script.

@item Nested types work much better; notably, nesting is no longer
restricted to nine levels.

@item Better @sc{arm} conformance on member access control.

@item The compiler now always generates default assignment operators
(@samp{operator =}), copy constructors (@samp{X::X(X&)}), and default
constructors (@samp{X::X()}) whenever they are required.

@item The new draft @sc{ansi} standard keyword @code{mutable} is supported.

@item @samp{-fansi-overloading} is the default, to comply better with
the @sc{arm} (at some cost in compatibility to earlier versions of @sc{gnu} C++).

@item More informative error messages.

@item System include files are automatically treated as if they were
wrapped in @samp{extern "C" @{ @}}.

@item The new option @samp{-falt-external-templates} provides alternate
template instantiation semantics.

@item Operator declarations are now checked more strictly.

@item You can now use template type arguments in the template parameter list.

@item You can call the destructor for any type.

@item The compiler source code is better organized.

@item You can specify where to instantiate template definitions explicitly.
@end itemize

Much of the work in Phase 1.3 went to elimination of known bugs, as well
as the major items above.

During the span of Phase 1.3, there were also two changes associated
with the compiler that, while not specifically part of the C++
Renovation project, may be of interest:

@itemize @bullet
@item @code{gcov}, a code coverage tool for @sc{gnu cc}, is now available
from Cygnus Support.  (@code{gcov} is free software, but the @sc{fsf} has not
yet accepted it.)  @xref{Gcov,, @code{gcov}: a Test Coverage Program,
gcc.info, Using GNU CC}, for more information (in Cygnus releases of
that manual).

@item @sc{gnu} C++ now supports @dfn{signatures}, a language extension to
provide more flexibility in abstract type definitions.  @xref{C++
Signatures,, Type Abstraction using Signatures, gcc.info, Using GNU CC}.
@end itemize

@node Major changes
@section Major Changes

This release includes four wholesale rewrites of certain areas of
compiler functionality:

@enumerate 1
@item Argument matching.  @sc{gnu} C++ is more compliant with the rules
described in Chapter 13, ``Overloading'', of the @sc{arm}.  This behavior is
the default, though you can specify it explicitly with
@samp{-fansi-overloading}.   For compatibility with earlier releases of
@sc{gnu} C++, specify @samp{-fno-ansi-overloading}; this makes the compiler
behave as it used to with respect to argument matching and name overloading.

@item Default constructors/destructors.  Section 12.8 of the @sc{arm}, ``Copying
Class Objects'', and Section 12.1, ``Constructors'', state that a
compiler must declare such default functions if the user does not
specify them.  @sc{gnu} C++ now declares, and generates when necessary,
the defaults for constructors and destructors you might omit.  In
particular, assignment operators (@samp{operator =}) behave the same way
whether you define them, or whether the compiler generates them by
default; taking the address of the default @samp{operator =} is now
guaranteed to work.  Default copy constructors (@samp{X::X(X&)}) now
function correctly, rather than calling the copy assignment operator for
the base class.  Finally, constructors (@samp{X::X()}), as well as
assignment operators and copy constructors, are now available whenever
they are required.

@c XXX This may be taken out eventually...
@item Binary incompatibility.  There are no new binary incompatibilities
in Phase 1.3, but Phase 1.2 introduced two binary incompatibilities with
earlier releases.  First, the functionality of @samp{operator
new} and @samp{operator delete} changed.  Name encoding
(``mangling'') of virtual table names changed as well.  Libraries
built with versions of the compiler earlier than Phase 1.2 must be
compiled with the new compiler.  (This includes the Cygnus Q2
progressive release and the FSF 2.4.5 release.)

@item New @code{g++} driver.
A new binary @code{g++} compiler driver replaces the shell script.
The new driver executes faster.
@end enumerate

@node New features
@section New features

@itemize @bullet
@item
The compiler warns when a class contains only private constructors
or destructors, and has no friends.  At the request of some of our
customers, we have added a new option, @samp{-Wctor-dtor-privacy} (on by
default), and its negation, @samp{-Wno-ctor-dtor-privacy}, to control
the emission of this warning.  If, for example, you are working towards
making your code compile warning-free, you can use @w{@samp{-Wall
-Wno-ctor-dtor-privacy}} to find the most common warnings.

@item
There is now a mechanism which controls exactly when templates are
expanded, so that you can reduce memory usage and program size and also
instantiate them exactly once.  You can control this mechanism with the
option @samp{-fexternal-templates} and its corresponding negation
@samp{-fno-external-templates}.  Without this feature, space consumed by
template instantiations can grow unacceptably in large-scale projects
with many different source files.  The default is
@samp{-fno-external-templates}.

You do not need to use the @samp{-fexternal-templates} option when
compiling a file that does not define and instantiate templates used in
other files, even if those files @emph{are} compiled with
@samp{-fexternal-templates}.  The only side effect is an increase in
object size for each file that was compiled without
@samp{-fexternal-templates}.

When your code is compiled with @samp{-fexternal-templates}, all
template instantiations are external; this requires that the templates
be under the control of @samp{#pragma interface} and @samp{#pragma
implementation}.  All instantiations that will be needed should be in
the implementation file; you can do this with a @code{typedef} that
references the instantiation needed.  Conversely, when you compile using
the option @samp{-fno-external-templates}, all template instantiations are
explicitly internal.

@samp{-fexternal-templates} also allows you to finally separate class
template function definitions from their declarations, thus speeding up
compilation times for every file that includes the template declaration.
Now you can have tens or even hundreds of lines in template
declarations, and thousands or tens of thousands of lines in template
definitions, with the definitions only going through the compiler once
instead of once for each source file.  It is important to note that you
must remember to externally instantiate @emph{all} templates that are
used from template declarations in interface files.  If you forget to do
this, unresolved externals will occur.

In the example below, the object file generated (@file{example.o}) will
contain the global instantiation for @samp{Stack<int>}.  If other types
of @samp{Stack} are needed, they can be added to @file{example.cc} or
placed in a new file, in the same spirit as @file{example.cc}.

@code{foo.h}:
@smallexample
@group
#pragma interface "foo.h"
template<class T>
class Stack @{
  static int statc;
  static T statc2;
  Stack() @{ @}
  virtual ~Stack() @{ @}
  int bar();
@};
@end group
@end smallexample

@code{example.cc}:
@smallexample
@group
#pragma implementation "foo.h"
#include "foo.h"

typedef Stack<int> t;
int Stack<int>::statc;
int Stack<int>::statc2;
int Stack<int>::bar() @{ @}
@end group
@end smallexample

Note that using @samp{-fexternal-templates} does not reduce memory usage
from completely different instantiations (@samp{Stack<Name>} vs.
@samp{Stack<Net_Connection>}), but only collapses different occurrences
of @samp{Stack<Name>} so that only one @samp{Stack<Name>} is generated.

@samp{-falt-external-templates} selects a slight variation in the
semantics described above (incidentally, you need not specify both
options; @samp{-falt-external-templates} implies
@samp{-fexternal-templates}).  

With @samp{-fexternal-templates}, the compiler emits a definition in the
implementation file that includes the header definition, @emph{even if}
instantiation is triggered from a @emph{different} implementation file
(e.g. with a template that uses another template).

With @samp{-falt-external-templates}, the definition always goes in the
implementation file that triggers instantiation.

For instance, with these two header files---

@example
@exdent @file{a.h}:
#pragma interface
template <class T> class A @{ @dots{} @};

@exdent @file{b.h}:
#pragma interface
class B @{ @dots{} @};
void f (A<B>);
@end example

Under @samp{-fexternal-templates}, the definition of @samp{A<B>} ends up
in the implementation file that includes @file{a.h}.  Under
@samp{-falt-external-templates}, the same definition ends up in the
implementation file that includes @file{b.h}.

@item
You can control explicitly where a template is instantiated, without
having to @emph{use} the template to get an instantiation.  

To instantiate a class template explicitly, write @samp{template
class @var{name}<paramvals>}, where @var{paramvals} is a list of values
for the template parameters.  For example, you might write

@example
template class A<int>
@end example

Similarly, to instantiate a function template explicitly, write
@samp{template @var{fnsign}} where @var{fnsign} is the particular
function signature you need.  For example, you might write

@example
template void foo (int, int)
@end example

This syntax for explicit template instantiation agrees with recent
extensions to the draft @sc{ansi} standard.

@item
The compiler's actions on @sc{ansi}-related warnings and errors have
been further enhanced.  The @samp{-pedantic-errors} option produces
error messages in a number of new situations: using @code{return} in a
non-@code{void} function (one returning a value); declaring a local
variable that shadows a parameter (e.g., the function takes an argument
@samp{a}, and has a local variable @samp{a}); and use of the @samp{asm}
keyword.  Finally, the compiler by default now issues a warning when
converting from an @code{int} to an enumerated type.  This is likely to
cause many new warnings in code that hadn't triggered them before.  For
example, when you compile this code,

@smallexample
@group
enum boolean @{ false, true @};
void
f ()
@{
  boolean x;

  x = 1; //@i{assigning an @code{int} to an @code{enum} now triggers a warning}
@}
@end group
@end smallexample

@noindent
you should see the warning ``@code{anachronistic conversion from integer
type to enumeral type `boolean'}''.  Instead of assigning the value 1,
assign the original enumerated value @samp{true}.
@end itemize

@node Enhancements and bug fixes
@section Enhancements and bug fixes

@itemize @bullet
@cindex nested types in template parameters
@item
You can now use nested types in a template parameter list, even if the nested
type is defined within the same class that attempts to use the template.
For example, given a template @code{list}, the following now works:

@smallexample
struct glyph @{
  @dots{}
  struct stroke @{ @dots{} @};
  list<stroke> l;
  @dots{}
@}
@end smallexample

@cindex function pointers vs template parameters
@item
Function pointers now work in template parameter lists.  For
example, you might want to instantiate a parameterized @code{list} class
in terms of a pointer to a function like this:

@smallexample
list<int (*)(int, void *)> fnlist;
@end smallexample

@item
@c FIXME!  Really no limit?  Jason said "deeper than 9" now OK...
Nested types are now handled correctly.  In particular, there is no
longer a limit to how deeply you can nest type definitions.

@item
@sc{gnu} C++ now conforms to the specifications in Chapter 11 of the
@sc{arm}, ``Member Access Control''.

@item
The @sc{ansi} C++ committee has introduced a new keyword @code{mutable}.
@sc{gnu} C++ supports it.  Use @code{mutable} to specify that some
particular members of a @code{const} class are @emph{not} constant.  For
example, you can use this to include a cache in a data structure that
otherwise represents a read-only database.

@item
Error messages now explicitly specify the declaration, type, or
expression that contains an error.

@item
To avoid copying and editing all system include files during @sc{gnu}
C++ installation, the compiler now automatically recognizes system
include files as C language definitions, as if they were wrapped in
@samp{extern "C" @{ @dots{} @}}.

@item
The compiler checks operator declarations more strictly.  For example,
you may no longer declare an @samp{operator +} with three arguments.

@item
You can now use template type arguments in the same template
parameter list where the type argument is specified (as well as in the
template body).  For example, you may write

@example
template <class T, T t> class A @{ @dots{} @};
@end example

@item
Destructors are now available for all types, even built-in ones; for
example, you can call @samp{int::~int}.  (Destructors for types like
@code{int} do not actually do anything, but their existence provides a
level of generality that permits smooth template expansion in more
cases.)

@item
Enumerated types declared inside a class are now handled correctly.

@item
An argument list for a function may not use an initializer list for its default
value.  For example, @w{@samp{void foo ( T x = @{ 1, 2 @} )}} is not permitted.

@item
A significant amount of work went into improving the ability of the
compiler to act accurately on multiple inheritance and virtual
functions.  Virtual function dispatch has been enhanced as well.

@item
The warning concerning a virtual inheritance environment with a
non-virtual destructor has been disabled, since it is not clear that
such a warning is warranted.

@item
Until exception handling is fully implemented in the Reno-2 release, use
of the identifiers @samp{catch}, @samp{throw}, or @samp{try} results
in the warning:

@smallexample
t.C:1: warning: `catch', `throw', and `try' 
       are all C++ reserved words
@end smallexample

@item
When giving a warning or error concerning initialization of a member in a
class, the compiler gives the name of the member if it has one.

@item
Detecting friendship between classes is more accurately checked.

@item
The syntaxes of @w{@samp{#pragma implementation "file.h"}} and
@samp{#pragma interface} are now more strictly controlled.  The compiler
notices (and warns) when any text follows @file{file.h} in the
implementation pragma, or follows the word @samp{interface}.  Any such
text is otherwise ignored.

@item
Trying to declare a template on a variable or type is now considered an
error, not an unimplemented feature.

@item
When an error occurs involving a template, the compiler attempts to
tell you at which point of instantiation the error occurred, in
addition to noting the line in the template declaration which had the
actual error.

@item
The symbol names for function templates in the resulting assembly file
are now encoded according to the arguments, rather than just being
emitted as, for example, two definitions of a function @samp{foo}.

@item
Template member functions that are declared @code{static} no longer
receive a @code{this} pointer.

@item
Case labels are no longer allowed to have commas to make up their
expressions.

@item
Warnings concerning the shift count of a left or right shift now tell
you if it was a @samp{left} or @samp{right} shift.

@item
The compiler now warns when a decimal constant is so large that it
becomes @code{unsigned}.

@item
Union initializers which are raw constructors are now handled properly.

@item
The compiler no longer gives incorrect errors when initializing a
union with an empty initializer list.

@item
Anonymous unions are now correctly used when nested inside a class.

@item
Anonymous unions declared as static class members are now handled
properly.

@item
The compiler now notices when a field in a class is declared both as
a type and a non-type.

@item
The compiler now warns when a user-defined function shadows a
built-in function, rather than emitting an error.

@item
A conflict between two function declarations now produces an error
regardless of their language context.

@item
Duplicate definitions of variables with @samp{extern "C"} linkage are no
longer considered in error.  (Note in C++ linkage---the default---you may
not have more than one definition of a variable.)

@item
Referencing a label that is not defined in any function is now an error.

@item
The syntax for pointers to methods has been improved; there are still
some minor bugs, but a number of cases should now be accepted by the
compiler.

@item
In error messages, arguments are now numbered starting at 1, instead of
0.  Therefore, in the function @samp{void foo (int a, int b)}, the
argument @samp{a} is argument 1, and @samp{b} is argument 2.  There is
no longer an argument 0.

@item
The tag for an enumerator, rather than its value, used as a default
argument is now shown in all error messages.  For example, @w{@samp{void
foo (enum x (= true))}} is shown instead of @w{@samp{void foo (enum x (=
1))}}.

@item
The @samp{__asm__} keyword is now accepted by the C++ front-end.

@item
Expressions of the form @samp{foo->~Class()} are now handled properly.

@item
The compiler now gives better warnings for situations which result in
integer overflows (e.g., in storage sizes, enumerators, unary
expressions, etc).

@item
@code{unsigned} bitfields are now promoted to @code{signed int} if the
field isn't as wide as an @code{int}.

@item
Declaration and usage of prefix and postfix @samp{operator ++} and
@samp{operator --} are now handled correctly.  For example,

@smallexample
@group
class foo
@{
public:
  operator ++ ();
  operator ++ (int);
  operator -- ();
  operator -- (int);
@};

void
f (foo *f)
@{
  f++;          // @i{call @code{f->operator++(int)}}
  ++f;          // @i{call @code{f->operator++()}}
  f--;          // @i{call @code{f->operator++(int)}}
  --f;          // @i{call @code{f->operator++()}}
@}
@end group
@end smallexample

@item
In accordance with @sc{arm} section 10.1.1, ambiguities and dominance are now
handled properly.  The rules described in section 10.1.1 are now fully
implemented. 

@end itemize

@node Problems with debugging
@section Problems with debugging

Two problems remain with regard to debugging:

@itemize @bullet
@item
Debugging of anonymous structures on the IBM RS/6000 host is incorrect.

@item
Symbol table size is overly large due to redundant symbol information;
this can make @code{gdb} coredump under certain circumstances.  This
problem is not host-specific.
@end itemize

@node Plans
@chapter Plans for Reno-2

The overall goal for the second phase of the @sc{gnu} C++ Renovation
Project is to bring @sc{gnu} C++ to a new level of reliability, quality,
and competitiveness.  As particular elements of this strategy, we intend
to:

@enumerate 0
@item
Fully implement @sc{ansi} exception handling.

@item
With the exception handling, add Runtime Type Identification
(@sc{rtti}), if the @sc{ansi} committee adopts it into the standard.

@item
Bring the compiler into closer compliance with the @sc{arm} and the draft
@sc{ansi} standard, and document what points in the @sc{arm} we do not yet comply,
or agree, with.

@item
Add further support for the @sc{dwarf} debugging format.

@item
Finish the work to make the compiler compliant with @sc{arm} Section 12.6.2,
initializing base classes in declaration order, rather than in the order
that you specify them in a @var{mem-initializer} list.

@item
Perform a full coverage analysis on the compiler, and weed out unused
code, for a gain in performance and a reduction in the size of the compiler.

@item
Further improve the multiple inheritance implementation in the
compiler to make it cleaner and more complete.
@end enumerate

@noindent
As always, we encourage you to make suggestions and ask questions about
@sc{gnu} C++ as a whole, so we can be sure that the end of this project
will bring a compiler that everyone will find essential for C++ and will
meet the needs of the world's C++ community.

@include templates.texi

@include gpcompare.texi

@contents

@bye