1999-05-18

Release Notes   
-------------
The Egcs Standard C++ Library v3, or libstc++-2.90.x, is an ongoing
project to implement the ISO 14882 Standard C++ library as described
in chapters 17 through 27 and annex D, as a drop-in replacement
for the current (ARM-conformant) library.

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

The Egcs Standard C++ Library v3, or libstc++-2.90.x, follows an open
development model, attempting to be fully buzzword, bazaar, and GNU
compliant. Full details on participating, including contributor
guidelines, mailing list subscription, mailing list archives,
up-to-date documentation, and various and sundry other details can be
found at the following URL:

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


New: 
--- 
 - Update to SGI STL 3.2
 - Automatically-generated <limits> header for each architecture. 
 - Partially re-written valarray.
 - Extensible documentation-synched-to-webpage architecture. 
 - Check script to check installation and builds, with facilities for
   tracking size and compile speed.
 - Stringbufs and stringstreams for basic types work.
 - Various bugfixes.
 - Re-written num_get::do_get.

What works: (noted with the chapter # of the ISO-14882 standard)
-----------
 - exceptions, op new etc. (18, 19)
 - SGI-STL release 3.2 utilities, containers, algorithms, and iterators.
   (20,23,24,25), and ostreambuf_iterator<>. Plus fixes for auto_ptr,
   and an interator class for vector and string.
 - basic_string<> (21)
 - locale, some facets (ctype, num_put, collate), stubs for the rest. (22)
 - Gabriel Dos Reis's valarray<>, and Drepper's complex<>.
 - ios_base, basic_ios<>, basic_streambuf<>, basic_stringbuf<>, 
   basic_filebuf<>, ostream<>, operator<< for integers, strings. (27)


What doesn't:
-------------
 - Too many parts of istream, op>>, op<<(double&) etc. (27) 
 - Many facet implementations are stubs. (22) 
 - Almost no optimizations for small-footprint/low-overhead. (22,27) 
 - It has not been fully audited for standard conformance in the areas 
   that do work--check out the testsuite directory for an idea of the 
   limitations of the current implementation. 
 - It has not been made thread-safe. 
 - There has been some work to wrap the C headers in namespace std::, but 
   it may not be complete yet, and C macros are not shadowed. Please consult 
   the mailing list archives for more information. 
 - Some parts of numeric_limits specialization for floating point types
   are stubs. 

 
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 for all non-STL parts of the library is a
slightly-modified version of the GPL that allows for template
instantiations: in particular, you may "use this file as part of a free
software library without restrictions." See the file COPYING for more
info, and any of the source files for the exception clause.

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 Benjamin Kosnik <benjamin@cygnus.com> for further details.


Build and Install
-----------------
Unpack the tarball using GNU tar; it will create a directory libstdc++-2.90.5.

  tar xfz libstdc++-2.90.5.tar.gz

It's recommended that you create a separate build directory apart from
the source directory for the building of the library: this is optimal,
and will be assumed for the rest of the instructions. (It is possible
to configure/build in the same directory.) Call this build directory
(say) bld-libstdc++, and cd into it:

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

You must have a recent snapshot release of Egcs built, and massaged
your PATH variable so that it is used for the building of the
library. Run configure; for example, using bash:

  ../libstdc++-2.90.5/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$LIBINC -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, you will need to set LD_LIBRARY_PATH in your environment
correctly, so that the shared library for libstdc++ can be found and
loaded. (Or, you can compile with -static to link statically if you
are debugging or would rather not deal with the extra bits for shared
libraries.)

To set LD_LIBRARY_PATH try this (again, assuming bash):

  LD_LIBRARY_PATH=$prefix/lib foo


Contact:
--------
Places have changed from previous snapshots.  The web page, which has
information about joining the mailing list and searching its archives,
CVS access, and contribution information is now at:

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

Please note that the mailing list has recently moved, and is now
hosted on sourceware.cygnus.com. (The web site above has the most
up-to-date info.)
   
Obtain the library snapshot via ftp (including these release notes) from

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

The library is maintained by Benjamin Kosnik, Nathan Myers, Gabriel
Dos Reis, and Ulrich Drepper.  


Development tools:
------------------
Testing was done with 

CXXFLAGS=  -g -Wall -O3 -fstrict-aliasing -ansi -fnew-abi -fhonor-std
CXXDEFINES= 
CXXINCLUDE= -I$LIBINC/std -I$LIBDIR -I$LIBINC/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 version of Egcs. (Egcs 1.1.2 does not work: see
the newsgroup archive for more info.)  In addition, you may need
up-to-date tools for modifying Makefiles and regenerating configure
scripts: automake (version 1.4 and above works nicely) and autoconf
(version 2.13 and higher). Please see the website for more info on
where to obtain these additional tools.


