From bfcafa4fbe7ee3063f359b2e26db81a96f4bfa9c Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Sun, 10 Dec 2000 04:04:56 +0000 Subject: Move the HTML-containing subdirs from 'docs' to 'docs/html'. 2000-12-09 Phil Edwards Move the HTML-containing subdirs from 'docs' to 'docs/html'. * README: Update the locations of instructions. * docs/doxygen/run_doxygen: New file, stub. * docs/Makefile: Moved... * docs/configopts.html: Likewise. * docs/documentation.html: Likewise. * docs/install.html: Likewise. * docs/lib3styles.css: Likewise. * docs/17_intro/BADNAMES: Likewise. * docs/17_intro/BUGS: Likewise. * docs/17_intro/C++STYLE: Likewise. * docs/17_intro/CHECKLIST: Likewise. * docs/17_intro/COPYING: Likewise. * docs/17_intro/DESIGN: Likewise. * docs/17_intro/HEADER_POLICY: Likewise. * docs/17_intro/PROBLEMS: Likewise. * docs/17_intro/RELEASE-NOTES: Likewise. * docs/17_intro/TODO: Likewise. * docs/17_intro/contribute.html: Likewise. * docs/17_intro/headers_cc.txt: Likewise. * docs/17_intro/howto.html: Likewise. * docs/17_intro/libstdc++-assign.txt: Likewise. * docs/17_intro/organization: Likewise. * docs/17_intro/porting-howto.html: Likewise. * docs/18_support/howto.html: Likewise. * docs/19_diagnostics/howto.html: Likewise. * docs/20_util/howto.html: Likewise. * docs/21_strings/gotw29a.txt: Likewise. * docs/21_strings/howto.html: Likewise. * docs/21_strings/stringtok_h.txt: Likewise. * docs/21_strings/stringtok_std_h.txt: Likewise. * docs/22_locale/codecvt.html: Likewise. * docs/22_locale/ctype.html: Likewise. * docs/22_locale/howto.html: Likewise. * docs/22_locale/locale.html: Likewise. * docs/23_containers/howto.html: Likewise. * docs/23_containers/wrappers_h.txt: Likewise. * docs/24_iterators/howto.html: Likewise. * docs/25_algorithms/howto.html: Likewise. * docs/26_numerics/howto.html: Likewise. * docs/27_io/howto.html: Likewise. * docs/27_io/iostreams_hierarchy.pdf: Likewise. * docs/ext/howto.html: Likewise. * docs/faq/index.html: Likewise. * docs/faq/index.txt: Likewise. * docs/html/Makefile: ...to here. * docs/html/configopts.html: Likewise. * docs/html/documentation.html: Likewise. * docs/html/install.html: Likewise. * docs/html/lib3styles.css: Likewise. * docs/html/17_intro/BADNAMES: Likewise. * docs/html/17_intro/BUGS: Likewise. * docs/html/17_intro/C++STYLE: Likewise. * docs/html/17_intro/CHECKLIST: Likewise. * docs/html/17_intro/COPYING: Likewise. * docs/html/17_intro/DESIGN: Likewise. * docs/html/17_intro/HEADER_POLICY: Likewise. * docs/html/17_intro/PROBLEMS: Likewise. * docs/html/17_intro/RELEASE-NOTES: Likewise. * docs/html/17_intro/TODO: Likewise. * docs/html/17_intro/contribute.html: Likewise. * docs/html/17_intro/headers_cc.txt: Likewise. * docs/html/17_intro/howto.html: Likewise. * docs/html/17_intro/libstdc++-assign.txt: Likewise. * docs/html/17_intro/organization: Likewise. * docs/html/17_intro/porting-howto.html: Likewise. * docs/html/18_support/howto.html: Likewise. * docs/html/19_diagnostics/howto.html: Likewise. * docs/html/20_util/howto.html: Likewise. * docs/html/21_strings/gotw29a.txt: Likewise. * docs/html/21_strings/howto.html: Likewise. * docs/html/21_strings/stringtok_h.txt: Likewise. * docs/html/21_strings/stringtok_std_h.txt: Likewise. * docs/html/22_locale/codecvt.html: Likewise. * docs/html/22_locale/ctype.html: Likewise. * docs/html/22_locale/howto.html: Likewise. * docs/html/22_locale/locale.html: Likewise. * docs/html/23_containers/howto.html: Likewise. * docs/html/23_containers/wrappers_h.txt: Likewise. * docs/html/24_iterators/howto.html: Likewise. * docs/html/25_algorithms/howto.html: Likewise. * docs/html/26_numerics/howto.html: Likewise. * docs/html/27_io/howto.html: Likewise. * docs/html/27_io/iostreams_hierarchy.pdf: Likewise. * docs/html/ext/howto.html: Likewise. * docs/html/faq/index.html: Likewise. * docs/html/faq/index.txt: Likewise. From-SVN: r38166 --- libstdc++-v3/docs/html/install.html | 411 ++++++++++++++++++++++++++++++++++++ 1 file changed, 411 insertions(+) create mode 100644 libstdc++-v3/docs/html/install.html (limited to 'libstdc++-v3/docs/html/install.html') diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html new file mode 100644 index 0000000..1a6b811 --- /dev/null +++ b/libstdc++-v3/docs/html/install.html @@ -0,0 +1,411 @@ + + + + + + + + libstdc++-v3 Installation Instructions + + + + + +

libstdc++-v3 INSTALL

+ +

The latest version of this document is always available at + + http://gcc.gnu.org/onlinedocs/libstdc++/install.html. +

+ +

To the libstdc++-v3 homepage. + + + +

+

Contents

+ + +
+ + + +

Tools you will need beforehand

+

You will need a recent version of g++ to compile the snapshot of + libstdc++: gcc-2.95.2 works well, or one of the post-2.95.2 GCC + snapshots (insert standard caveat about using snapshots rather + than formal releases). You will need the full source + distribution to whatever compiler release you are using. The + GCC snapshots can be had from one of the sites on their + mirror list. +

+ +

In addition, if you plan to modify the makefiles or regenerate + the configure scripts you'll need the nuevo automake, libtool + and autoconf to regenerate the Makefiles and configure + scripts. These tools are all required to be installed in the + same location (most linux distributions install these tools by + default, so no worries.) +

+ +

If you don't have bash, and want to run 'make check' to + test your build, you'll need to get bash 2.x. Also recommended + is GNU Make, since it is the only 'make' that will parse these + makefiles correctly. +

+ +

As of June 19, 2000, libstdc++ attempts to use tricky and + space-saving features of the GNU toolchain, enabled with + -ffunction-sections -fdata-sections -Wl,--gc-sections. + To obtain maximum benefit from this, binutils after this date + should also be used (bugs were fixed with C++ exception handling + related to this change in libstdc++-v3). The version of these + tools should be 2.10.90, and you can get snapshots (as + well as releases) of binutils + here. +

+ +

Finally, a few system-specific requirements: +

+
Cygwin +
If you are using Cygwin to compile libstdc++-v3 on Win32, you'll + have to get a version of the cygwin1.dll that is dated on or + after February 1, 2000. This is necessary to successfully run + the script "mknumeric_limits" which probes the + floating-point + environment of the host in question -- before this date, Cygwin + would freeze when running this script. In addition, you may + want to get a current version of libtool (say libtool-1.3.4 + and above) as earlier versions supposedly had problems creating + shared libraries. + +
Solaris +
We recommend installing the SUNWxcu4 package from the + Solaris CD before configuring the library. You can check for + this package as a non-privileged user with the command + "pkginfo SUNWxcu4". +
+

+ +
+ +

Setting up the source directories

+

As the libstdc++-v3 sources and the core GCC sources have + converged, more and more effort goes to building the + library as the default version to be shipped with g++. With the + 2.90.8 snapshot, and especially for CVS versions after this + release, this is treated as the usual scenario. If you want to + build the library all by itself, you will need to explicitly + disable certain features (like namespaces) since the core GCC + library, libgcc.a, will not be rebuilt with those same features. + +

+ +

By default, all configurations of libstdc++-v3 now have namespaces + enabled. Being able to select/de-select this option was a complex task + that had hopelessly confused many otherwise intelligent people, and + provided an endless stream of silent cursing and cries for help. + Because of this, gcc sources are required, and are no longer optional. +

+ +

The following definitions will be used throughout the rest of this + document: +

+ Note: +
    +
  1. The .8 snapshot and following are intended to replace the + library that comes with the compiler, so libsrcdir + and libbuilddir must be contained under + gccsrcdir and gccbuilddir, respectively. +
  2. The source, build, and installation directories should + not be parents of one another; i.e., these should all be + separate directories. Please don't build out of the + source directory. +
+

+ +

Since the release of libstdc++-2.90.8, configuration patches have gone + into CVS gcc that make the management of the various libstdc++ source + trees a bit easier. Because of this, both libstdc++-v2 and + libstdc++-v3 and live together more or less in peace, without the need + for soft linking. If a CVS gcc source directory after April 5, 2000 is + being used, then the directions are slightly different: please pick + which of the following two scenarios best represents your particular + situation. +

+ +

...with gcc-2.95.2 +

Unpack the gccsrcdir and go into that directory. For + instance, gcc-2.95.2 is a valid gccsrcdir. + Once in gccsrcdir, you'll need to rename the directories + called libstdc++ and libio like so: + 

+   mv libstdc++ libstdc++-v2
+   mv libio libio-v2
+

+

Next, unpack the libstdc++-v3 library tarball into the + gccsrcdir directory; it will create a + libsrcdir called libstdc++-version: + 

+   gzip -dc libstdc++-version.tar.gz | tar xf -
+

+

Finally, make a soft link between libsrcdir and + libstdc++ so that libstdc++-v3 will be the default C++ + library used. + 

+   ln -s libsrcdir libstdc++
+ This complexity of having two completely separate libstdc++ + libraries is necessary so that you can unlink libsrcdir + and update the compiler sources. If you're not this adventurous, or + would not like to switch between different C++ standard libraries, + this extra effort is probably wasted; just remove the v2 sources. +

+

+ +

...with CVS gcc +

Check out or download the gcc sources: the resulting source + directory is gccsrcdir. +

+

Next, unpack the libstdc++-v3 library tarball into this + gccsrcdir directory; it will create a + libsrcdir called libstdc++-version: + 

+   gzip -dc libstdc++-version.tar.gz | tar xf -
+

+ +

If CVS libstdc++-v3 is being used instead of a snapshot's tarball, + then move the source directory from the CVS checkout into the + gccsrcdir directory. + +

Finally, rename libsrcdir to libstdc++-v3 so that + gcc's configure flags will be able to deal with the new library. + 

+   mv libsrcdir libstdc++-v3
+

+

+ + +
+

Configuring

+

Due to namespaces, when building libstdc++-v3 you'll have to configure + the entire gccsrcdir directory. The full list of libstdc++-v3 + specific configuration options, not dependent on the specific compiler + release being used, can be found here. +

+

Consider possibly using --enable-languages=c++ to save time by only + building the C++ language parts. +

+ +

...with gcc-2.95.2 + 

+   gccsrcdir/configure --prefix=destdir
+

+ +

...with CVS gcc + 

+   gccsrcdir/configure --prefix=destdir --enable-libstdcxx-v3
+

+ +

Adding --enable-libstdcxx-v3 automatically selects libstdc++-v3 + as the C++ library to be used alongside the C++ compiler being built, + and also enables -fhonor-std by default. This option is not available + with gcc-2.95.2. +

+ + +
+

Building and installing the library

+

Now you have a few options:

+

[re]building everything

+

If you're building GCC from scratch, you can do the usual + 'make bootstrap' here, and libstdc++-v3 will be built + as its default C++ library. The generated g++ will magically + use the correct headers, link against the correct library + binary, and in general using libstdc++-v3 will be a piece of + cake. You're done; run 'make install' (the GCC + Installation instructions) to put the new compiler and libraries + into place. +

+ +

[re]building only libstdc++

+

Due to differences in the configure process, the resulting Makefiles + in thegccbuilddir will have different rules depending on + the source base being used. +

+ +

...with gcc-2.95.2 +

+ libstdc++-rule is libstdc++ +
+

+ +

...with CVS gcc +

+ libstdc++-rule is libstdc++-v3 +
+

+ +

To rebuild just libstdc++, use: + 

+   make all-target-libstdc++-rule
+ This will configure and build the C++ library in the + gccbuilddir/cpu-vendor-OS/libstdc++ directory. + As en example, for CVS gcc this would be + make all-target-libstdc++-v3, and for gcc-2.95.2 it would be + make all-target-libstdc++ +

+

If the build fails with a "warning: can't inline call" + message when compiling stringMAIN.cc, see the + resolution at the end of this document. +

+

If you are rebuilding from a previous build [attempt], some + information is kept in a cache file. This is stored in + gccbuilddir/cpu-vendor-OS/ if you are building with + multilibs (the default), or in + gccbuilddir/cpu-vendor-OS/libstdc++-v3 if you have + multilibs disabled. The filename is config.cache; if previous + information is causing problems, you can delete it entirely, or + simply edit it and remove lines. +

+

You're done. Now install the rebuilt pieces with + 

+   make install
+ or + 
+   make install-gcc
+   make install-target-libstdc++-rule
+

+ + +
+

Post-installation

+

Installation will create the destdir directory and + populate it with subdirectories: + 

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

+

You can check the status of the build without installing it using + 

+   make check
+ or you can check the status of the installed library using + 
+   make check-target-libstdc++-rule
+ These commands will create a 'testsuite' directory underneath + libbuilddir containing the results of the tests. We are + interested in any strange failures of the testsuite; please see + FAQ 2.4 for which files to examine. +

+ + +
+

Using the library

+
  • Find the new library at runtime (shared linking only) +

    If you only built a static library (libstdc++.a), or if you + specified static linking, you don't have to worry about this. + But if you built a shared library (libstdc++.so) and linked + against it, then you will need to find that library when you + run the executable. +

    +

    Methods vary for different platforms and different styles, but + the usual ones are printed to the screen during installation. + They include: +

      +
    • At runtime set LD_LIBRARY_PATH in your environment correctly, + so that the shared library for libstdc++ can be found and + loaded. Be certain that you understand all of the other + implications and behavior of LD_LIBRARY_PATH first (few + people do, and they get into trouble). +
    • Compile the path to find the library at runtime into the + program. This can be done by passing certain options to g++, + which will in turn pass them on to the linker. The exact + format of the options is dependent on which linker you use: +
        +
      • GNU ld (default on Linux): -Wl,--rpath -Wl,destdir/lib +
      • IRIX ld: -Wl,-rpath -Wl,destdir/lib +
      • Solaris ld: -Wl,-Rdestdir/lib +
      • More...? +
      +
    +

    +

    Use the ldd(1) utility to show which library the system + thinks it will get at runtime. +

    + +

    + + +
    +

    warning: can't inline call to...

    +

    When building the .8 snapshot with g++ 2.95.2, compilation may halt + with this warning message. The "problem" is the -Werror + flag being passed to the compiler, which says to treat warnings as + errors. (This plus a high warning level makes us track down bugs + quickly.) The compiler can't inline a certain call, prints + a warning, and dies. +

    +

    The workaround is to edit either libsrcdir/src/Makefile.in + (before configuring) or bld-libstdc++/src/Makefile + (after configuring). There's one line that reads + 

    +   WERROR = -Werror
    + Delete the flag itself, so that the line reads + 
    +   WERROR =
    + Then the compiler will still print a warning, but it won't die. +

    +

    For the curious, this "problem" is actually a symptom + of something else. The compiler in CVS could inline more than what + 2.95.2 does, and the libstdc++ changes were made with that + compiler. One of the libstdc++ maintainers explains this +here. +

    +

    This has been patched in current CVS sources. +

    + + + + + + +
    +

    +Comments and suggestions are welcome, and may be sent to +Phil Edwards or +Gabriel Dos Reis. +
    $Id: install.html,v 1.12 2000/12/03 23:47:47 jsm28 Exp $ +

    + + + + + -- cgit v1.1