1999-03-16

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 fifth 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.12
 - STL auto_ptr fixes
 - A string and vector iterator class 
 - Minor valarray tweaks. 
 - New buffering classes and abstractions for the underlying byte sequences, 
   with filebufs approaching (unoptimized) usability. 
 - Facets have been cached, stashed, and used throughout the iostream 
   hierarchy. Note the caching strategy is still developing, and the actual 
   locations they are saved may be changed.
 - Initialization of standard streams is done in a coherent and 
   standards-conformant manner.  
 - Preliminary wchar_t support has been added, although this isn't yet usable. 
 - Libio has been imported directly into the distribution, resulting in it's 
   larger size, but allowing input/output to work on other platforms--Solaris 
   in particular.


What works: (noted with the chapter # of the ISO-14882 standard)
-----------
 - exceptions, op new etc. (18, 19)
 - SGI-STL release 3.12 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<>.  (However, 
   note that numeric_limits<> is not tailored for your target.  You 
   must do that by hand.) (26)
 - 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) 
 - Most 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. 

 
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.4.

  tar xfz libstdc++-2.90.4.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.4/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, 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 -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 released version of Egcs.  We have used the
egcs-1.1.1 release successfully. 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.







