
Release Notes   1998-10-30
-------------

This is the third snapshot of the libstdc++ rewrite.  It is still 
incomplet and incorrekt.  

This snapshot is exciting because it is actually usable, more or
less.  A configure/make/make install will actually create something
you can build real programs against.  "hello, world" works!  It
should be quite usable as long as your iostream needs are limited.

It requires a recent snapshot version of Egcs.  (E.g. Egcs-1.1 may 
be insufficient.)  Please note the compiler flags recommended below.

Basic output operations now work, including integer output formatting 
(operator<< via num_put<>::put) but input has not been implemented yet. 
We have an efficient and usable copy-on-write basic_string<>. The STL 
is mostly unchanged from the last snapshot.  Gabriel Dos Reis's valarray 
has had minor improvements.

What works: (noted with the chapter # of the draft standard)
-----------

 - exceptions, op new etc. (18, 19)
 - SGI-STL release 3.11 utilities, containers, algorithms, and iterators.
   (20,23,24,25), and ostreambuf_iterator<>.
 - basic_string<> (21)
 - locale, some facets (ctype, num_put, collate), stubs for the rest. (22)
 - Gabriel dos Reis's valarray<>, and Drepper's complex<>.  (However, 
   note that numeric_limits<> is not tailored for your target.  You 
   must do that by hand.) (26)
 - ios_base, basic_ios<>, basic_streambuf<>, ostream<>, operator<<
   for integers, strings. (27)

What doesn't:
-------------

 - istream, stringstream, operator>>, op<<(double), etc. (27)
 - Most facet implementations are stubs.  (22)
 - No optimizations for small-footprint/low-overhead. (22,27)
 - C headers are not wrapped in std:: namespace; C macros are
   not shadowed.
 - It has not been audited for standard conformance in the areas that
   do work.
 - It has not been made thread-safe.
 - There has been some work to wrap the C headers in namespace std::,
   but it is not complete yet, and probably depends on compiler changes
   that may appear in -fnew-abi.

How to participate:
-------------------

Read:

 - RELEASE_NOTES - this file
 - README        - directory structure
 - HEADER_POLICY - header naming and sub-include structure
 - DESIGN        - overview of the implementation plan
 - TODO          - tasks
 - C++STYLE      - coding style by example
 - BADNAMES      - names to avoid because of potential collisions
 - LICENSE.STD   - the terms of use

The license is similar to, but weaker than, LGPL.  This weakening 
is necessary because the LGPL terms don't work for a library which 
is substantially composed of inline functions and templates; there's 
no simple boundary to make it easy to say "this is library, this is
program".  Thus, like the LGPL it permits linking with the library 
without publishing source code for the whole program, but it does 
not require that users of a program be able to relink with their own 
version of the library.  However, unlike the BSD license, it doesn't 
allow embargoing changes.  Subsequent releases may be under a license
more like LGPL/Gnat's, but details are still being worked out.

The STL portion of the library, under the stl/ directory, is under
a much weaker license specified by HP and SGI, that only requires
that the copyright notices not be stripped off.

Any patches accepted must be assigned under the same copyright terms.
Please contact Brendan Kehoe <brendan@cygnus.com> for further details.

Build and Install
-----------------

Unpack the tarball; it will create a directory libstdc++-2.90.2.

  tar xfz libstdc++-2.90.2.tar.gz

Create a build directory called (say) bld-libstdc++, and cd 
into it:

  mkdir bld-libstdc++
  cd    bld-libstdc++

You must have a recent snapshot release of Egcs built. The 
environment variable CXX should be set to find it when you run 
configure; for example, using bash:

  CXX=g++ ../libstdc++-2.90.2/configure --prefix=${PWD%/*}/H-libstdc++

Then 

  make
  make install

This will create (according to the above configure arguments) a directory
H-libstdc++ containing 

  lib/
  include/g++-v3/
    bits/
    backward/
    ext/

To link against that you can say, for example,

  LIBINC=$(prefix)/include/g++-v3
  g++ -Wall -I$(LIBSTD) -L(prefix)/lib foo.cc -o foo

where prefix is set to the full name of your H-libstdc++ directory.
If you want the SGI STL extensions (e.g. hash tables) you can add
  -I$(LIBINC)/ext 
and/or 
  -I$(LIBINC)/backward

To run it, of course you will need to say

  LD_LIBRARY_PATH=$(prefix)/lib foo

Contact:
--------

Places have changed from previous snapshots.  The web page is now at

  http://sourceware.cygnus.com/libstdc++/

You can join the mailing list by sending "subscribe" to

  libstdc++-v3-request@cygnus.com
   
Obtain the library snapshot (including these release notes) from

  ftp://sourceware.cygnus.com/pub/libstdc++/

The library is maintained by Benjamin Kosnik, Nathan Myers and 
Ulrich Drepper.  Correspondence will be handled on the mailing
list.  We plan to have a separate announcement list soon and, once 
we get the license terms wrestled down, a public CVS archive.


Notes of dependencies:
----------------------

Some parts of the rewrite currently depend upon libio.h, which can be 
obtained from the glibc package, or from the egcs libio tree.

Development tools:
------------------

Testing was done with 

CXX=egcc
CXXFLAGS=  -g -Wall -O3 -fstrict-aliasing -ansi -fnew-abi -fno-honor-std
CXXDEFINES= 
CXXINCLUDE= -I$(LIBDIR)/std -I$(LIBDIR) -I$(LIBDIR)/stl 

If you compile programs -fnew-abi -fno-honor-std, uses of RTTI and 
certain other language features will link only if you build your Egcs 
compiler's libgcc using the same flags.  (The defaults use the old abi.)  
Using -fnew-abi offers real benefits, but note that it is not stable: 
later snapshots will *not* be binary-compatible with code compiled with 
older snapshots.

You will need a recent snapshot version of Egcs.  We have used 
the 1998-10-20 snapshot successfully.

We have updated the Makefile.am to follow what the libtool and automake
maintainers have in mind.  If you start making any changes to the 
automake/configure parts, or add files for compilation, you should

a) get libtool-1.2b from ftp://alpha.gnu.org/gnu/libtool-1.2b.tar.gz

b) get autoconf 2.12.  You might need some patches which are floating
   around.  (I cannot really verify this in the moment since my autoconf
   is far from being the generic version --drepper)  (2.12 seems to
   work for me. --ncm)

c) automake-1.3b.tar.gz with a little patch which follows.  A patched
   tarball can be got from 
     ftp://ftp.cygnus.com/pub/home/drepper/automake-1.3b-ud.tar.gz

If you already have automake-1.3b apply this patch:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--- automake.in-old	Tue Aug 11 19:25:55 1998
+++ automake.in	Thu Oct 15 21:30:56 1998
@@ -6002,8 +6002,17 @@
 		push (@result, $rcurs);
 	    }
 
-	    # "EXTRA" shouldn't be used when generating clean targets,
-	    # all, or install targets.
+	    if ($X eq 'check')
+	    {
+		push (@check, '$(' . $one_name . ')');
+	    }
+	    else
+	    {
+		push (@used, '$(' . $one_name . ')');
+	    }
+
+	    # "EXTRA" shouldn't be used when generating clean targets
+	    # or install targets.
 	    next if $X eq 'EXTRA';
 
 	    # A blatant hack: we rewrite each _PROGRAMS primary to
@@ -6083,14 +6092,6 @@
 		&push_phony_cleaners ($X . $primary);
 	    }
 
-	    if ($X eq 'check')
-	    {
-		push (@check, '$(' . $one_name . ')');
-	    }
-	    else
-	    {
-		push (@used, '$(' . $one_name . ')');
-	    }
 	    if ($X eq 'noinst' || $X eq 'check')
 	    {
 		# Objects which don't get installed by default.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

