[V3 PATCH] additional documentation
Phil Edwards
pedwards@disaster.jaj.com
Tue Feb 6 16:03:00 GMT 2001
This is a fairly boring patch, fixing some HTML markup issues, adding some
more how-to notes, and describing the conventions that the library must
adhere to for any global variables (the wacky array-of-chars thing we all
loved so well :-) Applied.
2001-02-06 Phil Edwards <pme@sources.redhat.com>
* docs/html/configopts.html: Fix HTML markup.
* docs/html/install.html: Bring up to date.
* docs/html/17_intro/C++STYLE: Add global variable conventions.
* docs/html/21_strings/howto.html: More notes.
* docs/html/22_locale/howto.html: Fix HTML markup.
* docs/html/27_io/howto.html: More notes.
* docs/html/27_io/binary_iostreams_kanze.txt: New file.
* docs/html/27_io/binary_iostreams_kuehl.txt: New file.
Index: docs/html/configopts.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/configopts.html,v
retrieving revision 1.5
diff -u -3 -p -r1.5 configopts.html
--- configopts.html 2001/01/30 09:18:50 1.5
+++ configopts.html 2001/02/06 23:57:29
@@ -80,8 +80,8 @@ options</A></H1>
model based on langinfo/iconv (from <A
HREF=" http://sources.redhat.com/glibc/ ">glibc</A>, the GNU C
library), or 'generic' to use a generic "C"
- abstraction which consists of "C" locale info. The default is
- 'generic'.
+ abstraction which consists of "C" locale info.
+ The default is 'generic'.
</P>
<DT><TT>--enable-long-long </TT>
@@ -136,7 +136,6 @@ options</A></H1>
unless you also specify
<TT>--with-gxx-include-dir=_dirname_</TT> during configuration.
</P>
-
<DT><TT>--with-gxx-include-dir=<include-files dir></TT>
<DD><P>Adds support for named libstdc++ include directory. For instance,
Index: docs/html/install.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/install.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 install.html
--- install.html 2001/01/23 17:02:26 1.3
+++ install.html 2001/02/06 23:57:29
@@ -58,7 +58,8 @@
<P>If you don't have bash, and want to run <TT>'make check'</TT> 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.
+ makefiles correctly. We are moving to DejaGNU, so you'll
+ probably want to get that.
</P>
<P>As of June 19, 2000, libstdc++ attempts to use tricky and
@@ -151,10 +152,11 @@
<P><B>...with a gcc-2.9[67] snapshot</B>
<P>Unpack the <EM>gccsrcdir</EM> and go into that directory. For
instance, <TT>gcc-2.95.2</TT> is a valid <EM>gccsrcdir</EM>.
- Once in <EM>gccsrcdir</EM>, you'll need to rename the libstdc++-v3
- directory which comes with that snapshot:
+ Once in <EM>gccsrcdir</EM>, you'll need to rename or delete
+ the libstdc++-v3 directory which comes with that snapshot:
<PRE>
- mv libstdc++-v3 libstdc++-v3-previous</PRE>
+ mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
+ rm -r libstdc++-v3</PRE>
</P>
<P>Next, unpack the libstdc++-v3 library tarball into the
<EM>gccsrcdir</EM> directory; it will create a
@@ -173,9 +175,11 @@
<P><B>...with CVS gcc</B>
<P>Check out or download the gcc sources: the resulting source
directory is <EM>gccsrcdir</EM>. Once in <EM>gccsrcdir</EM>,
- you'll need to rename the libstdc++-v3 directory which comes
- with that snapshot:
- mv libstdc++-v3 libstdc++-v3-previous</PRE>
+ you'll need to rename or delete the libstdc++-v3 directory
+ which comes with that snapshot:
+ <PRE>
+ mv libstdc++-v3 libstdc++-v3-previous <STRONG>[OR]</STRONG>
+ rm -r libstdc++-v3</PRE>
</P>
<P>Next, unpack the libstdc++-v3 library tarball into this
<EM>gccsrcdir</EM> directory; it will create a
@@ -208,13 +212,7 @@
<P><PRE>
cd <EM>gccbuilddir</EM>
- <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --enable-libstdcxx-v3</PRE>
- </P>
-
- <P>Adding <TT>--enable-libstdcxx-v3</TT> 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.
+ <EM>gccsrcdir</EM>/configure --prefix=<EM>destdir</EM> --other-opts...</PRE>
</P>
@@ -239,10 +237,6 @@
This will configure and build the C++ library in the
<EM>gccbuilddir/cpu-vendor-OS/</EM>libstdc++ directory.
</P>
- <P>If the build fails with a "warning: can't inline call"
- message when compiling stringMAIN.cc, see <A HREF="#Werror">the
- resolution at the end of this document</A>.
- </P>
<P>If you are rebuilding from a previous build [attempt], some
information is kept in a cache file. This is stored in
<EM>gccbuilddir/cpu-vendor-OS/</EM> if you are building with
@@ -258,7 +252,7 @@
or
<PRE>
make install-gcc
- make install-target-<EM>libstdc++-rule</EM></PRE>
+ make install-target-libstdc++-v3</PRE>
</P>
@@ -271,7 +265,7 @@
include/g++-v3/
bits/
ext/
- cpu-vendor-OS/include/g++-v3/
+ CPU-vendor-OS/include/g++-v3/
bits/
ext/</PRE>
</P>
@@ -323,35 +317,6 @@
thinks it will get at runtime.
</P>
</OL>
- </P>
-
-
-<HR>
-<H3><A NAME="Werror"><TT>warning: can't inline call to</TT>...</A></H3>
- <P>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
- <EM>quickly</EM>.) The compiler can't inline a certain call, prints
- a warning, and dies.
- </P>
- <P>The workaround is to edit either <EM>libsrcdir</EM>/src/Makefile.in
- (before configuring) or <EM>bld-libstdc++</EM>/src/Makefile
- (after configuring). There's one line that reads
- <PRE>
- WERROR = -Werror</PRE>
- Delete the flag itself, so that the line reads
- <PRE>
- WERROR =</PRE>
- Then the compiler will still print a warning, but it won't die.
- </P>
- <P>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
-<A HREF=" http://gcc.gnu.org/ml/libstdc++/2000-q1/msg00420.html ">here</A>.
- </P>
- <P>This has been patched in current CVS sources.
</P>
Index: docs/html/17_intro/C++STYLE
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/C++STYLE,v
retrieving revision 1.4
diff -u -3 -p -r1.4 C++STYLE
--- C++STYLE 2001/01/17 07:44:56 1.4
+++ C++STYLE 2001/02/06 23:57:29
@@ -6,7 +6,7 @@ This library is written to appropriate C
it is intended to precede the recommendations of the GNU Coding
Standard, which can be referenced here:
- http://www.gnu.ai.mit.edu/prep/standards_toc.html
+ http://www.gnu.org/prep/standards_toc.html
ChangeLog entries for member functions should use the
classname::member function name syntax as follows:
@@ -27,7 +27,7 @@ Notable areas of divergence from what ma
char &c = *p; // wrong
Reason: In C++, definitions are mixed with executable code. Here,
- p is being initialized, not *p. This is near-universal
+ p is being initialized, not *p. This is near-universal
practice among C++ programmers; it is normal for C hackers
to switch spontaneously as they gain experience.
@@ -183,6 +183,16 @@ Notable areas of divergence from what ma
}
return __ret;
+
+14. Location of global variables.
+ All global variables of class type, whether in the "user visable"
+ space (e.g., cin) or the implementation namespace, must be defined
+ as a character array with the appropriate alignment and then later
+ re-initialized to the correct value.
+
+ This is due to startup issues on certain platforms, such as AIX.
+ For more explanation and examples, see src/globals.cc. All such
+ variables should be contained in that file, for simplicity.
Index: docs/html/21_strings/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/21_strings/howto.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 howto.html
--- howto.html 2000/12/10 04:04:55 1.1
+++ howto.html 2001/02/06 23:57:29
@@ -236,6 +236,13 @@
with reading the new function names, this version is recommended
as an example.
</P>
+ <P><B>Added February 2001:</B> Mark Wilden pointed out that the
+ standard <TT>std::getline()</TT> function can be used with standard
+ <A HREF="../27_io/howto.html">istringstreams</A> to perform
+ tokenizing as well. Build an istringstream from the input text,
+ and then use std::getline with varying delimiters (the three-argument
+ signature) to extract tokens into a string.
+ </P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
</P>
Index: docs/html/22_locale/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/22_locale/howto.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 howto.html
--- howto.html 2000/12/10 04:04:55 1.1
+++ howto.html 2001/02/06 23:57:29
@@ -56,9 +56,9 @@
<HR>
<H2><A NAME="2">Nathan Myers on Locales</A></H2>
- <P> An article entitled "The Standard C++ Locale" was published in
- Dr. Dobb's Journal and can be found
- <A HREF=" http://www.cantrip.org/locale.html ">here</A>
+ <P> An article entitled "The Standard C++ Locale" was
+ published in Dr. Dobb's Journal and can be found
+ <A HREF=" http://www.cantrip.org/locale.html ">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
@@ -67,7 +67,7 @@
<HR>
<H2><A NAME="5">class locale</A></H2>
<P> Notes made during the implementation of locales can be found
- <A HREF="locale.html">here</A>.
+ <A HREF="locale.html">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
@@ -76,7 +76,7 @@
<HR>
<H2><A NAME="4">class codecvt</A></H2>
<P> Notes made during the implementation of codecvt can be found
- <A HREF="codecvt.html">here</A>.
+ <A HREF="codecvt.html">here</A>.
</P>
<P> The following is the abstract from the implementation notes:
@@ -104,7 +104,7 @@ functionality are given.
<HR>
<H2><A NAME="5">class ctype</A></H2>
<P> Notes made during the implementation of ctype can be found
- <A HREF="ctype.html">here</A>.
+ <A HREF="ctype.html">here</A>.
</P>
<P>Return <A HREF="#top">to top of page</A> or
<A HREF="../faq/index.html">to the FAQ</A>.
@@ -114,7 +114,7 @@ functionality are given.
<H2><A NAME="6">Correct Transformations</A></H2>
<!-- Jumping directly here from chapter 21. -->
<P>A very common question on newsgroups and mailing lists is, "How
- do I do <foo> to a character string?" where <foo> is
+ do I do <foo> to a character string?" where <foo> is
a task such as changing all the letters to uppercase, to lowercase,
testing for digits, etc. A skilled and conscientious programmer
will follow the question with another, "And how do I make the
cvs server: docs/html/27_io/binary_iostreams_kanze.txt is a new entry, no comparison available
cvs server: docs/html/27_io/binary_iostreams_kuehl.txt is a new entry, no comparison available
Index: docs/html/27_io/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/27_io/howto.html,v
retrieving revision 1.2
diff -u -3 -p -r1.2 howto.html
--- howto.html 2001/01/23 17:02:27 1.2
+++ howto.html 2001/02/06 23:57:29
@@ -29,6 +29,7 @@
<LI><A HREF="#4">Iostreams class hierarchy diagram</A>
<LI><A HREF="#5">What is this <sstream>/stringstreams thing?</A>
<LI><A HREF="#6">Deriving a stream buffer</A>
+ <LI><A HREF="#7">More on binary I/O</A>
</UL>
<HR>
@@ -196,9 +197,9 @@
<P>Sorry. Them's the breaks.
</P>
<P>This isn't going to try and be a complete tutorial on reading and
- writing binary files (because "binary" covers a lot of
- ground), but we will try and clear up a couple of misconceptions
- and common errors.
+ writing binary files (because "binary"
+ <A HREF="#7">covers a lot of ground)</A>, but we will try and clear
+ up a couple of misconceptions and common errors.
</P>
<P>First, <TT>ios::binary</TT> has exactly one defined effect, no more
and no less. Normal text mode has to be concerned with the newline
@@ -224,7 +225,7 @@
<P>Third, using the <TT>get()</TT> and <TT>put()/write()</TT> member
functions still aren't guaranteed to help you. These are
"unformatted" I/O functions, but still character-based.
- (This may or may not be what you want.)
+ (This may or may not be what you want, see below.)
</P>
<P>Notice how all the problems here are due to the inappropriate use
of <EM>formatting</EM> functions and classes to perform something
@@ -381,6 +382,31 @@
}
</PRE>
Try it yourself!
+ </P>
+
+<HR>
+<H2><A NAME="7">More on binary I/O</A></H2>
+ <P>Towards the beginning of February 2001, the subject of
+ "binary" I/O was brought up in a couple of places at the
+ same time. One notable place was Usenet, where James Kanze and
+ Dietmar Kühl separately posted articles on why attempting
+ generic binary I/O was not a good idea. (Here are copies of
+ <A HREF="binary_iostreams_kanze.txt">Kanze's article</A> and
+ <A HREF="binary_iostreams_kuehl.txt">Kühl's article</A>.)
+ </P>
+ <P>Briefly, the problems of byte ordering and type sizes mean that
+ the unformatted functions like <TT>ostream::put()</TT> and
+ <TT>istream::get()</TT> cannot safely be used to communicate
+ between arbitrary programs, or across a network, or from one
+ invocation of a program to another invocation of the same program
+ on a different platform, etc.
+ </P>
+ <P>The entire Usenet thread is instructive, and took place under the
+ subject heading "binary iostreams" on both comp.std.c++
+ and comp.lang.c++.moderated in parallel. Also in that thread,
+ Dietmar Kühl mentioned that he had written a pair of stream
+ classes that would read and write XDR, which is a good step towards
+ a portable binary format.
</P>
More information about the Libstdc++
mailing list