New README.html

[Nicolai Josuttis]

Hi,

as offered, here is a first try of a new file
README.html for the top directory of libstdc++.

The idea is, that it should contain all necessary informations
to be able to build and use the library (of course, this can be
made better, but it might be a good starting point).
To do this I
 - start with some general references to files of the distribution.
 - start with the general scenario of building a snapshot/version
   (this should work as long nothing substantially changes).
 - shows a way how to enable namespace handling

Note the following:
- As long as the bug tracking database doesn't work, you should
  mention another way to send bug reports.
- All necessary stuff to build the library should be available
  in the downloaded file. E.g. I see no easy way to find how to
  enable namespaces (beside my new introduction). FAQ 5.5 mentions it
  a bit but the important part is part of a link to a thread
  that is not part of the distributuion (AFAIK).
- If you use this file, clarify its role compared to README.
  E.g. write a siongle first line into README that README.html
  might be a good point to start (if it is worth it).

Sorry, but I got (and will probably get) no more time to do something else
(I am VERY busy). But I hope, this file helps a bit.
For this reason, I also did not talk with Phil about conflict that might
arise due to other changes in the documentation he makes
(forgive me!).

Best
-- 
Nicolai M. Josuttis          	http://www.josuttis.de/
Solutions in Time        	mailto:solutions@josuttis.de
Title: libstdc++: README.html

libstdc++ v3
This is a file to get a first overview of the files in the development tree 
  of the GNU Standard C++ Library v3. As this is an ongoing project, newbies might 
  have some problems to build and use the library without going into details. 
  Here is a brief summary of thing, I'd like to mention to help others to use 
  the library. 
Hope it helps, Nicolai M. 
  Josuttis , 02 Jan, 99

Most Important files

  README
    The top README for a brief overview. 


  docs/index.html
    The top file of the documentation of the web site.


  docs/17_intro/RELEASE-NOTES
    Instructions for configuring and building this shnapshot (among other things).


Build and Install (under UNIX)
This is the general way to build the library. For details and snapshot specific 
  issues read the release notes . 

   Unpack the tarball using GNU tar; it will create a directory 
    libstdc++- version . 
    For example: 
     
       tar xfz libstdc++- version .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. For example: 
     
       mkdir ../ bld-libstdc++
        cd ../ bld-libstdc++
    
  
  You must have a recent snapshot release of gcc built (tested with 
    gcc-2.95.2), and massaged your PATH variable so that it is used for the building 
    of the library.
   
    to see, whether the right gcc is used run:   which 
      gcc 
    to see the version of gcc run:    gcc 
      --version 
  
  Run configure of the top directory of the libstdc++. You can pass 
    a lot of options to configure. At least, you should use option 
    --prefix to specify where to install the library. For example: 
     
      ../libstdc++-2.90.7/configure 
        --prefix= destdir
    
    To see other options of configure run: ../libstdc++-2.90.7/configure 
      --help
    For example, you might pass --enable-namespaces 
      to turn on namespace std (see below).
  
  Create the library  
     
       make
    
  
  Install the library  
     
      make install
    
    This will create a directory destdir containing: 
     
       lib/
        include/g++-v3/
           bits/
           backward/
           ext/
    
  
  To check the status of your build, type 
   
     make check
  


  or this, to check the installed library:


   
     make check-install
  


Use the library  
To use the library you have to link against it and, in case shared libraries 
  are used, to make sure that the right shared library gets found at runtime.

  To link against the library you can say, for example, 
     
       g++ -Wall -I destdir /include/g++-v3 
        -L destdir /lib foo.cc 
        -o foo
    
     If you want the SGI STL extensions (e.g. hash tables) you can add
         -I$LIBINC/ext 
      
      and/or 
         -I$LIBINC/backward
  
  To run the programs, you have several options: 
    
      At runtime set LD_LIBRARY_PATH 
        in your environment correctly, so that the shared library for libstdc++ 
        can be found and loaded.
      Compile with -static 
        to link statically if you are debugging or would rather not deal with 
        the extra bits for shared libraries. 
      Compile the path to find the library at runtime into the program. This 
        can be done by passing the following options to g++:
    
  
  
     
      -Wl,--rpath -Wl,$LIBTOP/lib
    
  
  These are my Makefile settings: 
   
    CXXFLAGS = ... 
      -I destdir /include/g++-v3 
      -L destdir /lib \
                    
      -Wl,--rpath -Wl, destdir /lib
  


  Some fun flags to try might include combinations of:
  CXXFLAGS= -g -Wall -O3 -fstrict-aliasing 
    -ansi -fsquangle \
               -fhonor-std 
    -fnew-exceptions -fvtable-gc -ffunction-sections 


Using Namespace std, new ABI, etc.
As both gcc and libstdc++ is an ongoing project, options and ABIs might change. 
  So, try configure --help from 
  time to time (whenever you get a new version) to see whether there is something 
  new to turn on.
Note that if you compile programs -fnew-abi -fno-honor-std, uses of RTTI and 
  certain other language features will link only if you build your compiler's 
  libgcc using the same flags. 
A typical example is the handling of namespace std. You probably know that 
  according to the standard all C++ identifiers have to get declared in namespace 
  std. However, by default, gcc does ignore namespace handling for backward compatibility. 
  Here is, for example, the way I managed to process namespace std (thanks 
  to Benjamin Kosnik): 

  To build libstdc++ I used the additional option 
    --enable-namespaces
  To re-build gcc libraries to support namespaces go into the directory, where 
    gcc was build and 
    
      mv libstdc++.a libstdc++-nostd.a
      make libgcc2.a TARGET_LIBGCC2_CFLAGS="-fhonor-std"
      make libgcc.a
      mv libgcc.a libgcc-std.a
      mv gcclibdir/libgcc.a gcclibdir/libgcc-nostd.a
      cp libgcc-std.a gcclibdir/libgcc-std.a
      cd gcclibdir; ln -s libgcc-std.a 
        libgcc.a
    
    By doing this libgcc.a is a symbolic link to the std-version of libgcc. 
    
  


 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++/

And please note that the bug tracking database is not running at the moment. 
  Send bug reports to the mailing lists.

 Development tools
You will need a recent version of gcc to compile the snapshot of libstdc++. The 
recently released gcc-2.95.2 works well. In addition, you may need up-to-date 
tools for modifying Makefiles and regenerating configure scripts: automake (version 
1.4 from Cygnus, not the one on the net) and autoconf (version 2.13 and higher). 
Please see the website for more info on where to obtain these additional tools. 
For the adventurous, testing may be done with different flags than the current 
  defaults. More information and a commentary on how to to this can be found here:

   http://sourceware.cygnus.com/ml/libstdc++/1999-q3/msg00066.html

If you compile programs -fnew-abi -fno-honor-std, uses of RTTI and certain 
  other language features will link only if you build your 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.
ÂÂ