Add missing infopages

gnu/usr.bin/cc/doc/Makefile

@@ -0,0 +1,3 @@
+INFO = gcc cpp reno gxxint
+
+.include <bsd.info.mk>

gnu/usr.bin/cc/doc/gpcompare.texi

@@ -0,0 +1,236 @@
+@node ANSI
+@chapter @sc{gnu} C++ Conformance to @sc{ansi} C++
+
+These changes in the @sc{gnu} C++ compiler were made to comply more
+closely with the @sc{ansi} base document, @cite{The Annotated C++
+Reference Manual} (the @sc{arm}).  Further reducing the divergences from
+@sc{ansi} C++ is a continued goal of the @sc{gnu} C++ Renovation
+Project.
+
+@b{Section 3.4}, @i{Start and Termination}.  It is now illegal to take
+the address of the function @samp{main()}.
+
+@b{Section 4.8}, @i{Pointers to Members}.  The compiler produces
+an error for trying to convert between a pointer to a member and the type
+@samp{void *}.
+
+@b{Section 5.2.5}, @i{Increment and Decrement}.  It is an error to use
+the increment and decrement operators on an enumerated type.
+
+@b{Section 5.3.2}, @i{Sizeof}.  Doing @code{sizeof} on a function is now
+an error.
+
+@b{Section 5.3.4}, @i{Delete}.  The syntax of a @i{cast-expression} is
+now more strictly controlled.
+
+@b{Section 7.1.1}, @i{Storage Class Specifiers}.  Using the
+@code{static} and @code{extern} specifiers can now only be applied to
+names of objects, functions, and anonymous unions.
+
+@b{Section 7.1.1}, @i{Storage Class Specifiers}.  The compiler no longer complains
+about taking the address of a variable which has been declared to have @code{register}
+storage.
+
+@b{Section 7.1.2}, @i{Function Specifiers}.  The compiler produces an
+error when the @code{inline} or @code{virtual} specifiers are
+used on anything other than a function.
+
+@b{Section 8.3}, @i{Function Definitions}.  It is now an error to shadow
+a parameter name with a local variable; in the past, the compiler only
+gave a warning in such a situation.
+
+@b{Section 8.4.1}, @i{Aggregates}.  The rules concerning declaration of
+an aggregate are now all checked in the @sc{gnu} C++ compiler; they
+include having no private or protected members and no base classes.
+
+@b{Section 8.4.3}, @i{References}.  Declaring an array of references is
+now forbidden.  Initializing a reference with an initializer list is
+also considered an error.
+
+@b{Section 9.5}, @i{Unions}.  Global anonymous unions must be declared
+@code{static}.
+
+@b{Section 11.4}, @i{Friends}.  Declaring a member to be a friend of a
+type that has not yet been defined is an error.
+
+@b{Section 12.1}, @i{Constructors}.  The compiler generates a
+default copy constructor for a class if no constructor has been declared.
+
+@ignore
+@b{Section 12.4}, @i{Destructors}.  In accordance with the @sc{ansi} C++
+draft standard working paper, a pure virtual destructor must now be
+defined.
+@end ignore
+
+@b{Section 12.6.2}, @i{Special Member Functions}.  When using a
+@i{mem-initializer} list, the compiler will now initialize class members
+in declaration order, not in the order in which you specify them.
+Also, the compiler enforces the rule that non-static @code{const}
+and reference members must be initialized with a @i{mem-initializer}
+list when their class does not have a constructor.
+
+@b{Section 12.8}, @i{Copying Class Objects}.  The compiler generates
+default copy constructors correctly, and supplies default assignment
+operators compatible with user-defined ones.
+
+@b{Section 13.4}, @i{Overloaded Operators}.  An overloaded operator may
+no longer have default arguments.
+
+@b{Section 13.4.4}, @i{Function Call}.  An overloaded @samp{operator ()}
+must be a non-static member function.
+
+@b{Section 13.4.5}, @i{Subscripting}.  An overloaded @samp{operator []}
+must be a non-static member function.
+
+@b{Section 13.4.6}, @i{Class Member Access}.  An overloaded @samp{operator ->}
+must be a non-static member function.
+
+@b{Section 13.4.7}, @i{Increment and Decrement}.  The compiler will now
+make sure a postfix @samp{@w{operator ++}} or @samp{@w{operator --}} has an
+@code{int} as its second argument.
+
+
+@node Encoding
+@chapter Name Encoding in @sc{gnu} C++
+
+@c FIXME!! rewrite name encoding section
+@c ...to give complete rules rather than diffs from ARM.
+@c To avoid plagiarism, invent some different way of structuring the
+@c description of the rules than what ARM uses.
+
+@cindex mangling
+@cindex name encoding
+@cindex encoding information in names
+In order to support its strong typing rules and the ability to provide
+function overloading, the C++ programming language @dfn{encodes}
+information about functions and objects, so that conflicts across object
+files can be detected during linking. @footnote{This encoding is also
+sometimes called, whimsically enough, @dfn{mangling}; the corresponding
+decoding is sometimes called @dfn{demangling}.} These rules tend to be
+unique to each individual implementation of C++.
+
+The scheme detailed in the commentary for 7.2.1 of @cite{The Annotated
+Reference Manual} offers a description of a possible implementation
+which happens to closely resemble the @code{cfront} compiler.  The
+design used in @sc{gnu} C++ differs from this model in a number of ways:
+
+@itemize @bullet
+@item
+In addition to the basic types @code{void}, @code{char}, @code{short},
+@code{int}, @code{long}, @code{float}, @code{double}, and @code{long
+double}, @sc{gnu} C++ supports two additional types: @code{wchar_t}, the wide
+character type, and @code{long long} (if the host supports it).  The
+encodings for these are @samp{w} and @samp{x} respectively.
+
+@item
+According to the @sc{arm}, qualified names (e.g., @samp{foo::bar::baz}) are
+encoded with a leading @samp{Q}.  Followed by the number of
+qualifications (in this case, three) and the respective names, this
+might be encoded as @samp{Q33foo3bar3baz}.  @sc{gnu} C++ adds a leading
+underscore to the list, producing @samp{_Q33foo3bar3baz}.
+ 
+@item
+The operator @samp{*=} is encoded as @samp{__aml}, not @samp{__amu}, to
+match the normal @samp{*} operator, which is encoded as @samp{__ml}.
+
+@c XXX left out ->(), __wr
+@item
+In addition to the normal operators, @sc{gnu} C++ also offers the minimum and
+maximum operators @samp{>?} and @samp{<?}, encoded as @samp{__mx} and
+@samp{__mn}, and the conditional operator @samp{?:}, encoded as @samp{__cn}.
+
+@cindex destructors, encoding of
+@cindex constructors, encoding of
+@item
+Constructors are encoded as simply @samp{__@var{name}}, where @var{name}
+is the encoded name (e.g., @code{3foo} for the @code{foo} class
+constructor).  Destructors are encoded as two leading underscores
+separated by either a period or a dollar sign, depending on the
+capabilities of the local host, followed by the encoded name.  For
+example, the destructor @samp{foo::~foo} is encoded as @samp{_$_3foo}.
+
+@item
+Virtual tables are encoded with a prefix of @samp{_vt}, rather than
+@samp{__vtbl}.  The names of their classes are separated by dollar signs
+(or periods), and not encoded as normal: the virtual table for
+@code{foo} is @samp{__vt$foo}, and the table for @code{foo::bar} is
+named @samp{__vt$foo$bar}.
+
+@item
+Static members are encoded as a leading underscore, followed by the
+encoded name of the class in which they appear, a separating dollar sign
+or period, and finally the unencoded name of the variable.  For example,
+if the class @code{foo} contains a static member @samp{bar}, its
+encoding would be @samp{_3foo$bar}.
+
+@item
+@sc{gnu} C++ is not as aggressive as other compilers when it comes to always
+generating @samp{Fv} for functions with no arguments.  In particular,
+the compiler does not add the sequence to conversion operators.  The
+function @samp{foo::bar()} is encoded as @samp{bar__3foo}, not
+@samp{bar__3fooFv}.
+
+@item
+The argument list for methods is not prefixed by a leading @samp{F}; it
+is considered implied.
+
+@item
+@sc{gnu} C++ approaches the task of saving space in encodings
+differently from that noted in the @sc{arm}.  It does use the
+@samp{T@var{n}} and @samp{N@var{x}@var{y}} codes to signify copying the
+@var{n}th argument's type, and making the next @var{x} arguments be the
+type of the @var{y}th argument, respectively.  However, the values for
+@var{n} and @var{y} begin at zero with @sc{gnu} C++, whereas the
+@sc{arm} describes them as starting at one.  For the function @samp{foo
+(bartype, bartype)}, @sc{gnu} C++ uses @samp{foo__7bartypeT0}, while
+compilers following the @sc{arm} example generate @samp{foo__7bartypeT1}.
+
+@c Note it loses on `foo (int, int, int, int, int)'.
+@item
+@sc{gnu} C++ does not bother using the space-saving methods for types whose
+encoding is a single character (like an integer, encoded as @samp{i}).
+This is useful in the most common cases (two @code{int}s would result in
+using three letters, instead of just @samp{ii}).
+@end itemize
+
+@c @node Cfront
+@c @chapter @code{cfront} Compared to @sc{gnu} C++
+@c 
+@c 
+@c FIXME!! Fill in.  Consider points in the following:
+@c 
+@c @display
+@c Date: Thu, 2 Jan 92 21:35:20 EST
+@c From: raeburn@@cygnus.com
+@c Message-Id: <9201030235.AA10999@@cambridge.cygnus.com>
+@c To: mrs@@charlie.secs.csun.edu
+@c Cc: g++@@cygnus.com
+@c Subject: Re: ARM and GNU C++ incompatabilities
+@c 
+@c Along with that, we should probably describe how g++ differs from
+@c cfront, in ways that the users will notice.  (E.g., cfront supposedly
+@c allows "free (new char[10])"; does g++?  How do the template
+@c implementations differ?  "New" placement syntax?)
+@c @end display
+@c
+@c XXX For next revision.
+@c
+@c GNU C++:
+@c * supports expanding inline functions in many situations,
+@c   including those which have static objects, use `for' statements,
+@c   and other situations.  Part of this versatility is due to is
+@c   ability to not always generate temporaries for assignments.
+@c * deliberately allows divide by 0 and mod 0, since [according
+@c   to Wilson] there are actually situations where you'd like to allow
+@c   such things.  Note on most systems it will cause some sort of trap
+@c   or bus error.  Cfront considers it an error.
+@c * does [appear to] support nested classes within templates.
+@c * conversion functions among baseclasses are all usable by
+@c   a class that's derived from all of those bases.
+@c * sizeof works even when the class is defined within its ()'s
+@c * conditional expressions work with member fns and pointers to
+@c    members.
+@c * can handle non-trivial declarations of variables within switch
+@c   statements.
+@c
+@c Cfront:

gnu/usr.bin/cc/doc/reno.texi

@@ -0,0 +1,752 @@
+\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

gnu/usr.bin/cc/doc/templates.texi

@@ -0,0 +1,235 @@
+@node Templates
+@chapter The Template Implementation
+
+@cindex templates
+@cindex function templates
+@cindex class templates
+@cindex parameterized types
+@cindex types, parameterized
+The C++ template@footnote{Class templates are also known as
+@dfn{parameterized types}.} facility, which effectively allows use of
+variables for types in declarations, is one of the newest features of
+the language.
+
+@sc{gnu} C++ is one of the first compilers to implement many
+of the template facilities currently defined by the @sc{ansi} committee.
+
+Nevertheless, the template implementation is not yet complete.  This
+chapter maps the current limitations of the @sc{gnu} C++ template
+implementation.
+
+@menu
+* Template limitations:: Limitations for function and class templates
+* Function templates::   Limitations for function templates
+* Class templates::      Limitations for class templates
+* Template debugging::   Debugging information for templates
+@end menu
+
+@node Template limitations
+@section Limitations for function and class templates
+
+@cindex template limitations
+@cindex template bugs
+@cindex bugs, templates
+These limitations apply to any use of templates (function templates or
+class templates) with @sc{gnu} C++:
+
+@table @emph
+@item Template definitions must be visible
+When you compile code with templates, the template definitions must come
+first (before the compiler needs to expand them), and template
+definitions you use must be visible in the current scope.
+@c FIXME! Is this a defined property of templates, rather than a
+@c temporary limitation?
+@c ANSWER: It's a limitation, but it's hard to say why it's a limitation
+@c to someone.  We need an infinite link-cycle, in one camp, to
+@c accomplish things so you don't need the template definitions around.
+
+@cindex static data in template classes
+@cindex template classes, static data in
+@item Individual initializers needed for static data
+Templates for static data in template classes do not work.  @xref{Class
+templates,,Limitations for class templates}.
+@end table
+
+@node Function templates
+@section Limitations for function templates
+
+@cindex function template limitations
+Function templates are implemented for the most part.  The compiler can
+correctly determine template parameter values, and will delay
+instantiation of a function that uses templates until the requisite type
+information is available.
+
+@noindent
+The following limitations remain: 
+
+@itemize @bullet
+@cindex template vs declaration, functions
+@cindex declaration vs template, functions
+@cindex function declaration vs template
+@item
+Narrowed specification: function declarations should not prevent
+template expansion.  When you declare a function, @sc{gnu} C++
+interprets the declaration as an indication that you will provide a
+definition for that function.  Therefore, @sc{gnu} C++ does not use a
+template expansion if there is also an applicable declaration.  @sc{gnu}
+C++ only expands the template when there is no such declaration.
+
+The specification in Bjarne Stroustrup's @cite{The C++ Programming
+Language, Second Edition} is narrower, and the @sc{gnu} C++
+implementation is now clearly incorrect.  With this new specification, a
+declaration that corresponds to an instantiation of a function template
+only affects whether conversions are needed to use that version of the
+function.  It should no longer prevent expansion of the template
+definition.
+
+For example, this code fragment must be treated differently:
+
+@smallexample
+template <class X> X min (X& x1, X& x2) @{ @dots{} @}
+int min (int, int);
+@dots{}
+int i; short s;
+min (i, s); // @r{should call} min(int,int)
+            // @r{derived from template}
+@dots{}
+@end smallexample
+
+@item
+The compiler does not yet understand function signatures where types are
+nested within template parameters.  For example, a function like the
+following produces a syntax error on the closing @samp{)} of the
+definition of the function @code{f}:
+
+@smallexample
+template <class T> class A @{ public: T x; class Y @{@}; @};
+template <class X> int f (A<X>::Y y) @{ @dots{} @}
+@end smallexample
+
+@cindex @code{inline} and function templates
+@cindex function templates and @code{inline}
+@item
+If you declare an @code{inline} function using templates, the compiler
+can only inline the code @emph{after} the first time you use
+that function with whatever particular type signature the template
+was instantiated.
+
+Removing this limitation is akin to supporting nested function
+definitions in @sc{gnu} C++; the limitation will probably remain until the
+more general problem of nested functions is solved.
+
+@item
+All the @emph{method} templates (templates for member functions) for a
+class must be visible to the compiler when the class template is
+instantiated. 
+@end itemize
+
+@node Class templates
+@section Limitations for class templates
+
+@cindex class template limitations
+@ignore
+FIXME!!  Include a comprehensible version of this if someone can explain it.
+         (Queried Brendan and Raeburn w/full orig context, 26may1993---pesch)
+   - [RHP: I don't understand what the following fragment refers to.  If it's
+     the "BIG BUG" section in the original, why does it say "overriding class
+     declarations" here when the more detailed text refers to *function*
+     declarations?  Here's the fragment I don't understand:] 
+     there are problems with user-supplied overriding class declarations (see
+     below). 
+@end ignore
+
+@itemize @bullet
+@ignore
+@cindex static data, not working in templates
+@item
+Templates for static data in template classes do not work.
+Currently, you must initialize each case of such data
+individually. 
+@c FIXME!! Brendan to see if still true.
+@c ANSWER: This section presumes that it's incorrect to have to
+@c initialize for each type you instantiate with.  It's not, it's the
+@c right way to do it.
+@end ignore
+
+Unfortunately, individual initializations of this sort are likely to be
+considered errors eventually; since they're needed now, you might want to
+flag places where you use them with comments to mark the need for a
+future transition.
+
+@cindex nested type results vs templates
+@item
+Member functions in template classes may not have results of nested
+type; @sc{gnu} C++ signals a syntax error on the attempt.  The following
+example illustrates this problem with an @code{enum} type @code{alph}:
+
+@smallexample
+template <class T> class list @{
+  @dots{}
+  enum alph @{a,b,c@};
+  alph bar();
+  @dots{}
+@};
+
+template <class T>
+list<int>::alph list<int>::bar()  // @i{Syntax error here}
+@{
+@dots{}
+@}
+@end smallexample
+
+@cindex preprocessor conditionals in templates
+@cindex conditionals (preprocessor) in templates
+@item
+A parsing bug makes it difficult to use preprocessor conditionals within
+templates.  For example, in this code:
+
+@smallexample
+template <class T>
+class list @{
+  @dots{}
+#ifdef SYSWRONG
+  T x;
+#endif
+  @dots{}
+@}
+@end smallexample
+
+The preprocessor output leaves sourcefile line number information (lines
+like @samp{# 6 "foo.cc"} when it expands the @code{#ifdef} block.  These
+lines confuse the compiler while parsing templates, giving a syntax
+error.
+
+If you cannot avoid preprocessor conditionals in templates, you can
+suppress the line number information using the @samp{-P} preprocessor
+option (but this will make debugging more difficult), by compiling the
+affected modules like this:
+
+@smallexample
+g++ -P foo.cc -o foo
+@end smallexample
+
+@cindex parsing errors, templates
+@item
+Parsing errors are reported when templates are first
+@emph{instantiated}---not on the template definition itself.  In
+particular, if you do not instantiate a template definition at all, the
+compiler never reports any parsing errors that may be in the template
+definition.
+@end itemize
+
+@node Template debugging
+@section Debugging information for templates
+
+@cindex templates and debugging information
+@cindex debugging information and templates
+Debugging information for templates works for some object code formats,
+but not others.  It works for stabs@footnote{Except that insufficient
+debugging information for methods of template classes is generated in
+stabs.} (used primarily in @sc{a.out} object code, but also in the Solaris 2
+version of @sc{elf}), and the @sc{mips} version of @sc{coff} debugging
+format.
+
+@sc{dwarf} support is currently minimal, and requires further
+development.