Re: libstdc++-v3/doc/xml/manual/backwards_compatibility.xml

[Jonathan Wakely <jwakely@redhat.com>]

On 13/04/21 16:37 +0100, Jonathan Wakely wrote:
>On 13/04/21 16:19 +0100, Jonathan Wakely via Libstdc++ wrote:
>>Sorry for the slow reply ...
>>
>>On Mon, 1 Feb 2021 at 22:59, Gerald Pfeifer wrote:
>>>
>>>I noticed this section on "Backwards Compatibility" in the libstdc++
>>>docs that talks about
>>>
>>> - glibc 2.0.x
>>> - GCC 3.2 (August 2002)
>>> - GCC 4.1 (February 2006)
>>>
>>>and links to "Migrating to GCC 4.1" and "Migration guide for GCC-3.2"
>>>documents.
>>>
>>>Does this still make sense (and serve real users or developers) or
>>>should this be trimmed quite a bit?
>>
>>Yeah, that (and a lot more) should be trimmed from the libstdc++
>>manual. It's just time consuming to do it.
>
>It turned out to be pretty easy in this case, as the ancient text was
>so obviously useless now that it can just be ripped out.
>
>The remaining parts of the page should probably be evaluated too, but
>at least the truly prehistoric stuff is gone with this patch.
>
>Pushed to trunk.

Oops, I meant to change gcc@ to gcc-patches@ before sending, sorry for
the noise on the main list.


>commit 989e512f719a44fafca0030d7b8a1f5bf5f1baf7
>Author: Jonathan Wakely <jwakely@redhat.com>
>Date:   Tue Apr 13 16:30:16 2021
>
>    libstdc++: Remove outdated docs on libg++ and libstdc++-v2
>    
>    The libstdc++-v3 manual doesn't need to document how to use its
>    predecessors.
>    
>    libstdc++-v3/ChangeLog:
>    
>            * doc/xml/manual/backwards_compatibility.xml: Remove porting
>            notes for libg++ and libstdc++-v2, and bibliography.
>            * doc/html/*: Regenerated.
>
>diff --git a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
>index cce553380e1..6a4a5ccedfb 100644
>--- a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
>+++ b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
>@@ -22,7 +22,7 @@ dinosaur.
> 
> <para>Some background: libg++ was designed and created when there was no
> ISO standard to provide guidance.  Classes like linked lists are now
>-provided for by <classname>list&lt;T&gt;</classname> and do not need to be
>+provided for by <classname>std::list&lt;T&gt;</classname> and do not need to be
> created by <function>genclass</function>.  (For that matter, templates exist
> now and are well-supported, whereas genclass (mostly) predates them.)
> </para>
>@@ -34,41 +34,13 @@ Committee couldn't include everything, and so a lot of those
> <quote>obvious</quote> classes didn't get included.
> </para>
> 
>-<para>Known Issues include many of the limitations of its immediate ancestor.</para>
>-
>-<para>Portability notes and known implementation limitations are as follows.</para>
>-
>-<section xml:id="backwards.first.ios_base"><info><title>No <code>ios_base</code></title></info>
>-
>-
>-<para> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>.
>+<para>That project is no longer maintained or supported, and the sources
>+archived. For the desperate, the
>+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://ftp.gnu.org/old-gnu/libg++/">ftp.gnu.org</link>
>+server still has the libg++ source.
> </para>
> </section>
> 
>-<section xml:id="backwards.first.cout_cin"><info><title>No <code>cout</code> in <filename class="headerfile">&lt;ostream.h&gt;</filename>, no <code>cin</code> in <filename class="headerfile">&lt;istream.h&gt;</filename></title></info>
>-
>-
>-<para>
>-	In earlier versions of the standard,
>-	<filename class="headerfile">&lt;fstream.h&gt;</filename>,
>-	<filename class="headerfile">&lt;ostream.h&gt;</filename>
>-	and <filename class="headerfile">&lt;istream.h&gt;</filename>
>-	used to define
>-	<code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include
>-	<filename class="headerfile">&lt;iostream&gt;</filename>
>-	explicitly to get the required definitions.
>- </para>
>-<para> Some include adjustment may be required.</para>
>-
>-<para>This project is no longer maintained or supported, and the sources
>-archived. For the desperate,
>-the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/extensions.html">GCC extensions
>-page</link> describes where to find the last libg++ source. The code is
>-considered replaced and rewritten.
>-</para>
>-</section>
>-</section>
>-
> <section xml:id="backwards.second"><info><title>Second</title></info>
> 
> 
>@@ -80,504 +52,14 @@ considered replaced and rewritten.
> </para>
> 
> <para>
>-  The STL portions of this library are based on SGI/HP STL release 3.11.
>+  The STL portions of that library are based on SGI/HP STL release 3.11.
> </para>
> 
> <para>
>-  This project is no longer maintained or supported, and the sources
>-  archived.  The code is considered replaced and rewritten.
>+  That project is no longer maintained or supported, and the sources
>+  archived.  The code was replaced and rewritten for libstdc++-v3.
> </para>
> 
>-<para>
>-  Portability notes and known implementation limitations are as follows.
>-</para>
>-
>-<section xml:id="backwards.second.std"><info><title>Namespace <code>std::</code> not supported</title></info>
>-
>-
>-  <para>
>-    Some care is required to support C++ compiler and or library
>-    implementation that do not have the standard library in
>-    <code>namespace std</code>.
>-  </para>
>-
>-  <para>
>-    The following sections list some possible solutions to support compilers
>-    that cannot ignore <code>std::</code>-qualified names.
>-  </para>
>-
>-  <para>
>-    First, see if the compiler has a flag for this. Namespace
>-    back-portability-issues are generally not a problem for g++
>-    compilers that do not have libstdc++ in <code>std::</code>, as the
>-    compilers use <option>-fno-honor-std</option> (ignore
>-    <code>std::</code>, <code>:: = std::</code>) by default. That is,
>-    the responsibility for enabling or disabling <code>std::</code> is
>-    on the user; the maintainer does not have to care about it. This
>-    probably applies to some other compilers as well.
>-  </para>
>-
>-  <para>
>-    Second, experiment with a variety of pre-processor tricks.
>-  </para>
>-
>-  <para>
>-    By defining <code>std</code> as a macro, fully-qualified namespace
>-    calls become global. Volia.
>-  </para>
>-
>-<programlisting>
>-#ifdef WICKEDLY_OLD_COMPILER
>-# define std
>-#endif
>-</programlisting>
>-
>-  <para>
>-    Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help.
>-  </para>
>-
>-  <para>
>-    Another pre-processor based approach is to define a macro
>-    <code>NAMESPACE_STD</code>, which is defined to either
>-    <quote> </quote> or <quote>std</quote> based on a compile-type
>-    test. On GNU systems, this can be done with autotools by means of
>-    an autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>,
>-    then using that to set a value for the <code>NAMESPACE_STD</code>
>-    macro.  At that point, one is able to use
>-    <code>NAMESPACE_STD::string</code>, which will evaluate to
>-    <code>std::string</code> or <code>::string</code> (i.e., in the
>-    global namespace on systems that do not put <code>string</code> in
>-    <code>std::</code>).
>-  </para>
>-
>-<programlisting>
>-dnl @synopsis AC_CXX_NAMESPACE_STD
>-dnl
>-dnl If the compiler supports namespace std, define
>-dnl HAVE_NAMESPACE_STD.
>-dnl
>-dnl @category Cxx
>-dnl @author Todd Veldhuizen
>-dnl @author Luc Maisonobe &lt;luc@spaceroots.org&gt;
>-dnl @version 2004-02-04
>-dnl @license AllPermissive
>-AC_DEFUN([AC_CXX_NAMESPACE_STD], [
>-  AC_CACHE_CHECK(if g++ supports namespace std,
>-  ac_cv_cxx_have_std_namespace,
>-  [AC_LANG_SAVE
>-  AC_LANG_CPLUSPLUS
>-  AC_TRY_COMPILE([#include &lt;iostream&gt;
>-		  std::istream&amp; is = std::cin;],,
>-  ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
>-  AC_LANG_RESTORE
>-  ])
>-  if test "$ac_cv_cxx_have_std_namespace" = yes; then
>-    AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
>-  fi
>-])
>-</programlisting>
>-</section>
>-
>-<section xml:id="backwards.second.iterators"><info><title>Illegal iterator usage</title></info>
>-
>-<para>
>-  The following illustrate implementation-allowed illegal iterator
>-  use, and then correct use.
>-</para>
>-
>-<itemizedlist>
>-  <listitem>
>-    <para>
>-      you cannot do <code>ostream::operator&lt;&lt;(iterator)</code>
>-      to print the address of the iterator =&gt; use
>-      <code>operator&lt;&lt; &amp;*iterator</code> instead
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      you cannot clear an iterator's reference (<code>iterator =
>-      0</code>) =&gt; use <code>iterator = iterator_type();</code>
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      <code>if (iterator)</code> won't work any more =&gt; use
>-      <code>if (iterator != iterator_type())</code>
>-    </para>
>-  </listitem>
>-</itemizedlist>
>-</section>
>-
>-<section xml:id="backwards.second.isspace"><info><title><code>isspace</code> from <filename class="headerfile">&lt;cctype&gt;</filename> is a macro
>-  </title></info>
>-
>-
>-  <para>
>-    Glibc 2.0.x and 2.1.x define <filename class="headerfile">&lt;ctype.h&gt;</filename> functionality as macros
>-    (isspace, isalpha etc.).
>-  </para>
>-
>-  <para>
>-    This implementations of libstdc++, however, keep these functions
>-    as macros, and so it is not back-portable to use fully qualified
>-    names. For example:
>-  </para>
>-
>-<programlisting>
>-#include &lt;cctype&gt;
>-int main() { std::isspace('X'); }
>-</programlisting>
>-
>-<para>
>-  Results in something like this:
>-</para>
>-
>-<programlisting>
>-std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
>-</programlisting>
>-
>-<para>
>-  A solution is to modify a header-file so that the compiler tells
>-  <filename class="headerfile">&lt;ctype.h&gt;</filename> to define functions
>-  instead of macros:
>-</para>
>-
>-<programlisting>
>-// This keeps isalnum, et al from being propagated as macros.
>-#if __linux__
>-# define __NO_CTYPE 1
>-#endif
>-</programlisting>
>-
>-<para>
>-  Then, include <filename class="headerfile">&lt;ctype.h&gt;</filename>
>-</para>
>-
>-<para>
>-  Another problem arises if you put a <code>using namespace
>-  std;</code> declaration at the top, and include
>-  <filename class="headerfile">&lt;ctype.h&gt;</filename>. This will
>-  result in ambiguities between the definitions in the global namespace
>-  (<filename class="headerfile">&lt;ctype.h&gt;</filename>) and the
>-  definitions in namespace <code>std::</code>
>-  (<code>&lt;cctype&gt;</code>).
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.at"><info><title>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></title></info>
>-
>-
>-<para>
>-  One solution is to add an autoconf-test for this:
>-</para>
>-
>-<programlisting>
>-AC_MSG_CHECKING(for container::at)
>-AC_TRY_COMPILE(
>-[
>-#include &lt;vector&gt;
>-#include &lt;deque&gt;
>-#include &lt;string&gt;
>-
>-using namespace std;
>-],
>-[
>-deque&lt;int&gt; test_deque(3);
>-test_deque.at(2);
>-vector&lt;int&gt; test_vector(2);
>-test_vector.at(1);
>-string test_string(<quote>test_string</quote>);
>-test_string.at(3);
>-],
>-[AC_MSG_RESULT(yes)
>-AC_DEFINE(HAVE_CONTAINER_AT)],
>-[AC_MSG_RESULT(no)])
>-</programlisting>
>-
>-<para>
>-  If you are using other (non-GNU) compilers it might be a good idea
>-  to check for <code>string::at</code> separately.
>-</para>
>-
>-</section>
>-
>-<section xml:id="backwards.second.eof"><info><title>No <code>std::char_traits&lt;char&gt;::eof</code></title></info>
>-
>-
>-<para>
>-  Use some kind of autoconf test, plus this:
>-</para>
>-
>-<programlisting>
>-#ifdef HAVE_CHAR_TRAITS
>-#define CPP_EOF std::char_traits&lt;char&gt;::eof()
>-#else
>-#define CPP_EOF EOF
>-#endif
>-</programlisting>
>-
>-</section>
>-
>-<section xml:id="backwards.second.stringclear"><info><title>No <code>string::clear</code></title></info>
>-
>-
>-<para>
>-  There are two functions for deleting the contents of a string:
>-  <code>clear</code> and <code>erase</code> (the latter returns the
>-  string).
>-</para>
>-
>-<programlisting>
>-void
>-clear() { _M_mutate(0, this-&gt;size(), 0); }
>-</programlisting>
>-
>-<programlisting>
>-basic_string&amp;
>-erase(size_type __pos = 0, size_type __n = npos)
>-{
>-  return this-&gt;replace(_M_check(__pos), _M_fold(__pos, __n),
>-			  _M_data(), _M_data());
>-}
>-</programlisting>
>-
>-<para>
>-  Unfortunately, <code>clear</code> is not implemented in this
>-  version, so you should use <code>erase</code> (which is probably
>-  faster than <code>operator=(charT*)</code>).
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.ostreamform_istreamscan"><info><title>
>-  Removal of <code>ostream::form</code> and <code>istream::scan</code>
>-  extensions
>-</title></info>
>-
>-
>-<para>
>-  These are no longer supported. Please use stringstreams instead.
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.stringstreams"><info><title>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></title></info>
>-
>-
>-<para>
>-  Although the ISO standard <code>i/ostringstream</code>-classes are
>-  provided, (<filename class="headerfile">&lt;sstream&gt;</filename>), for
>-  compatibility with older implementations the pre-ISO
>-  <code>i/ostrstream</code> (<filename class="headerfile">&lt;strstream&gt;</filename>) interface is also provided,
>-  with these caveats:
>-</para>
>-
>-<itemizedlist>
>-  <listitem>
>-    <para>
>-      <code>strstream</code> is considered to be deprecated
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      <code>strstream</code> is limited to <code>char</code>
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      with <code>ostringstream</code> you don't have to take care of
>-      terminating the string or freeing its memory
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      <code>istringstream</code> can be re-filled (clear();
>-      str(input);)
>-    </para>
>-  </listitem>
>-</itemizedlist>
>-
>-<para>
>-  You can then use output-stringstreams like this:
>-</para>
>-
>-<programlisting>
>-#ifdef HAVE_SSTREAM
>-# include &lt;sstream&gt;
>-#else
>-# include &lt;strstream&gt;
>-#endif
>-
>-#ifdef HAVE_SSTREAM
>-  std::ostringstream oss;
>-#else
>-  std::ostrstream oss;
>-#endif
>-
>-oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
>-...
>-#ifndef HAVE_SSTREAM
>-  oss &lt;&lt; std::ends; // terminate the char*-string
>-#endif
>-
>-// str() returns char* for ostrstream and a string for ostringstream
>-// this also causes ostrstream to think that the buffer's memory
>-// is yours
>-m_label.set_text(oss.str());
>-#ifndef HAVE_SSTREAM
>-  // let the ostrstream take care of freeing the memory
>-  oss.freeze(false);
>-#endif
>-</programlisting>
>-
>-<para>
>-      Input-stringstreams can be used similarly:
>-</para>
>-
>-<programlisting>
>-std::string input;
>-...
>-#ifdef HAVE_SSTREAM
>-std::istringstream iss(input);
>-#else
>-std::istrstream iss(input.c_str());
>-#endif
>-
>-int i;
>-iss &gt;&gt; i;
>-</programlisting>
>-
>-<para> One (the only?) restriction is that an istrstream cannot be re-filled:
>-</para>
>-
>-<programlisting>
>-std::istringstream iss(numerator);
>-iss &gt;&gt; m_num;
>-// this is not possible with istrstream
>-iss.clear();
>-iss.str(denominator);
>-iss &gt;&gt; m_den;
>-</programlisting>
>-
>-<para>
>-If you don't care about speed, you can put these conversions in
>-      a template-function:
>-</para>
>-<programlisting>
>-template &lt;class X&gt;
>-void fromString(const string&amp; input, X&amp; any)
>-{
>-#ifdef HAVE_SSTREAM
>-std::istringstream iss(input);
>-#else
>-std::istrstream iss(input.c_str());
>-#endif
>-X temp;
>-iss &gt;&gt; temp;
>-if (iss.fail())
>-throw runtime_error(..)
>-any = temp;
>-}
>-</programlisting>
>-
>-<para>
>-  Another example of using stringstreams is in <link linkend="strings.string.shrink">this howto</link>.
>-</para>
>-
>-<para> There is additional information in the libstdc++-v2 info files, in
>-particular <quote>info iostream</quote>.
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.wchar"><info><title>Little or no wide character support</title></info>
>-
>-  <para>
>-    Classes <classname>wstring</classname> and
>-    <classname>char_traits&lt;wchar_t&gt;</classname> are
>-    not supported.
>-  </para>
>-</section>
>-
>-<section xml:id="backwards.second.iostream_templates"><info><title>No templatized iostreams</title></info>
>-
>-  <para>
>-    Classes <classname>wfilebuf</classname> and
>-    <classname>wstringstream</classname> are not supported.
>-  </para>
>-</section>
>-
>-<section xml:id="backwards.second.thread_safety"><info><title>Thread safety issues</title></info>
>-
>-
>-  <para>
>-    Earlier GCC releases had a somewhat different approach to
>-    threading configuration and proper compilation.  Before GCC 3.0,
>-    configuration of the threading model was dictated by compiler
>-    command-line options and macros (both of which were somewhat
>-    thread-implementation and port-specific).  There were no
>-    guarantees related to being able to link code compiled with one
>-    set of options and macro setting with another set.
>-  </para>
>-
>-  <para>
>-    For GCC 3.0, configuration of the threading model used with
>-    libraries and user-code is performed when GCC is configured and
>-    built using the --enable-threads and --disable-threads options.
>-    The ABI is stable for symbol name-mangling and limited functional
>-    compatibility exists between code compiled under different
>-    threading models.
>-  </para>
>-
>-   <para>
>-     The libstdc++ library has been designed so that it can be used in
>-     multithreaded applications (with libstdc++-v2 this was only true
>-     of the STL parts.)  The first problem is finding a
>-     <emphasis>fast</emphasis> method of implementation portable to
>-     all platforms.  Due to historical reasons, some of the library is
>-     written against per-CPU-architecture spinlocks and other parts
>-     against the gthr.h abstraction layer which is provided by gcc.  A
>-     minor problem that pops up every so often is different
>-     interpretations of what "thread-safe" means for a
>-     library (not a general program).  We currently use the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html">same
>-     definition that SGI</link> uses for their STL subset.  However,
>-     the exception for read-only containers only applies to the STL
>-     components. This definition is widely-used and something similar
>-     will be used in the next version of the C++ standard library.
>-   </para>
>-
>-   <para>
>-     Here is a small link farm to threads (no pun) in the mail
>-     archives that discuss the threading problem.  Each link is to the
>-     first relevant message in the thread; from there you can use
>-     "Thread Next" to move down the thread.  This farm is in
>-     latest-to-oldest order.
>-   </para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>
>-	    Our threading expert Loren gives a breakdown of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
>-	    six situations involving threads</link> for the 3.0
>-	    release series.
>-	  </para>
>-      </listitem>
>-	<listitem>
>-	  <para>
>-	    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
>-	This message</link> inspired a recent updating of issues with
>-	threading and the SGI STL library.  It also contains some
>-	example POSIX-multithreaded STL code.
>-	  </para>
>-	</listitem>
>-      </itemizedlist>
>-
>-   <para>
>-     (A large selection of links to older messages has been removed;
>-     many of the messages from 1999 were lost in a disk crash, and the
>-     few people with access to the backup tapes have been too swamped
>-     with work to restore them.  Many of the points have been
>-     superseded anyhow.)
>-   </para>
>-</section>
>-
> </section>
> 
> <section xml:id="backwards.third"><info><title>Third</title></info>
>@@ -588,7 +70,7 @@ libstdc++-v3.
> </para>
> 
>       <para>The subset commonly known as the Standard Template Library
>-	 (clauses 23 through 25, mostly) is adapted from the final release
>+	 (clauses 23 through 25 in C++98, mostly) is adapted from the final release
> 	 of the SGI STL (version 3.3), with extensive changes.
>       </para>
> 
>@@ -1223,40 +705,4 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
> 
> </section>
> 
>-<bibliography xml:id="backwards.biblio"><info><title>Bibliography</title></info>
>-
>-
>-  <biblioentry>
>-      <title>
>-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
>-	      xlink:href="http://www.kegel.com/gcc/gcc4.html">
>-      Migrating to GCC 4.1
>-	</link>
>-      </title>
>-
>-    <author><personname><firstname>Dan</firstname><surname>Kegel</surname></personname></author>
>-  </biblioentry>
>-
>-  <biblioentry>
>-      <title>
>-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
>-	      xlink:href="https://lists.debian.org/debian-gcc/2006/03/msg00405.html">
>-      Building the Whole Debian Archive with GCC 4.1: A Summary
>-	</link>
>-      </title>
>-    <author><personname><firstname>Martin</firstname><surname>Michlmayr</surname></personname></author>
>-  </biblioentry>
>-
>-  <biblioentry>
>-      <title>
>-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
>-	      xlink:href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">
>-      Migration guide for GCC-3.2
>-	</link>
>-      </title>
>-
>-  </biblioentry>
>-
>-</bibliography>
>-
> </section>