This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[libstdc++] new version of porting-howto
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Subject: [libstdc++] new version of porting-howto
- From: Phil Edwards <pedwards at disaster dot jaj dot com>
- Date: Mon, 5 Nov 2001 16:58:06 -0500
2001-11-05 Felix Natter <fnatter@gmx.net>
* docs/html/17_intro/porting-howto.xml: check in v0.9.4
* docs/html/17_intro/porting-howto.html: regenerate
Index: docs/html/17_intro/porting-howto.xml
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/porting-howto.xml,v
retrieving revision 1.1
diff -u -3 -p -r1.1 porting-howto.xml
--- porting-howto.xml 2001/07/12 00:02:34 1.1
+++ porting-howto.xml 2001/11/05 21:53:11
@@ -22,6 +22,7 @@
<!-- TODO:
o remove //@label: use automatic numbering
o make this work: <link linkend="sec-gtkmm-hack" endterm="sec-gtkmm-hack.title"/>.
+o clean up the section-numbering
-->
<article class = "whitepaper" id = "libstdc++-porting-howto" lang = "en">
@@ -36,63 +37,72 @@ o make this work: <link linkend="sec-gtk
</address>
<revhistory>
<revision>
- <revnumber>0.5</revnumber>
- <date>Thu Jun 1 13:06:50 2000</date>
- <authorinitials>fnatter</authorinitials>
- <revremark>First docbook-version.</revremark>
+ <revnumber>0.5</revnumber>
+ <date>Thu Jun 1 13:06:50 2000</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>First docbook-version.</revremark>
</revision>
<revision>
- <revnumber>0.8</revnumber>
- <date>Sun Jul 30 20:28:40 2000</date>
- <authorinitials>fnatter</authorinitials>
- <revremark>First released version using docbook-xml
- + second upload to libstdc++-page.
- </revremark>
+ <revnumber>0.8</revnumber>
+ <date>Sun Jul 30 20:28:40 2000</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>First released version using docbook-xml
+ + second upload to libstdc++-page.
+ </revremark>
</revision>
<revision>
- <revnumber>0.9</revnumber>
- <date>Wed Sep 6 02:59:32 2000</date>
- <authorinitials>fnatter</authorinitials>
- <revremark>5 new sections.</revremark>
+ <revnumber>0.9</revnumber>
+ <date>Wed Sep 6 02:59:32 2000</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>5 new sections.</revremark>
</revision>
<revision>
- <revnumber>0.9.1</revnumber>
- <date>Sat Sep 23 14:20:15 2000</date>
- <authorinitials>fnatter</authorinitials>
- <revremark>added information about why file-descriptors are not in the
- standard</revremark>
+ <revnumber>0.9.1</revnumber>
+ <date>Sat Sep 23 14:20:15 2000</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>added information about why file-descriptors are not in the
+ standard</revremark>
</revision>
<revision>
- <revnumber>0.9.2</revnumber>
- <date>Tue Jun 5 20:07:49 2001</date>
- <authorinitials>fnatter</authorinitials>
- <revremark>
- a fix, added hint on increased portability of C-shadow-headers,
- added autoconf-test HAVE_CONTAINER_AT
- </revremark>
+ <revnumber>0.9.2</revnumber>
+ <date>Tue Jun 5 20:07:49 2001</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>
+ a fix, added hint on increased portability of C-shadow-headers,
+ added autoconf-test HAVE_CONTAINER_AT
+ </revremark>
</revision>
<revision>
- <revnumber>0.9.3</revnumber>
- <date>Fri Jun 29 16:15:56 2001</date>
- <authorinitials>fnatter</authorinitials>
- <revremark>
- changed signature of nonstandard filebuf-constructor and
- update the section on filebuf::attach to point to ../ext/howto.html,
- added link to ../21/strings/howto.html
- in sec-stringstream, changed <link>-tags to have content
- (so that these links work),
- replace "user-space" by "global namespace"
- add note about gcc 3.0 and shadow-headers
- add section about ostream::form and istream::scan
- sec-vector-at: remove hint to modify headers
- fix spelling error in sec-stringstream
- </revremark>
+ <revnumber>0.9.3</revnumber>
+ <date>Fri Jun 29 16:15:56 2001</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>
+ changed signature of nonstandard filebuf-constructor and
+ update the section on filebuf::attach to point to ../ext/howto.html,
+ added link to ../21/strings/howto.html
+ in sec-stringstream, changed <link>-tags to have content
+ (so that these links work),
+ replace "user-space" by "global namespace"
+ add note about gcc 3.0 and shadow-headers
+ add section about ostream::form and istream::scan
+ sec-vector-at: remove hint to modify headers
+ fix spelling error in sec-stringstream
+ </revremark>
</revision>
+ <revision>
+ <revnumber>0.9.4</revnumber>
+ <date>Mon Nov 5 17:01:04 2001</date>
+ <authorinitials>fnatter</authorinitials>
+ <revremark>
+ rewrite section 1.1.3 because of gnu.gcc.help-post by
+ Juergen Heinzl
+ </revremark>
+ </revision>
</revhistory>
<legalnotice><title>Legal Notice</title>
<para>
- This document can be distributed under the FDL
- (<ulink url = "http://www.gnu.org">www.gnu.org</ulink>)
+ This document can be distributed under the FDL
+ (<ulink url = "http://www.gnu.org">www.gnu.org</ulink>)
</para>
</legalnotice>
@@ -216,12 +226,31 @@ o make this work: <link linkend="sec-gtk
<para>
If some compilers complain about <command>using
std::string;</command>, and if the "hack" for gtk-- mentioned above
- does not work, then it might be a good idea to define a macro
- <symbol>NS_STD</symbol>, which is defined to either "" or "std"
- based on an autoconf-test. Then you should be able to use
- <command>NS_STD::string</command>, which will evaluate to
- <command>::string</command> ("string in the global namespace") on
- systems that do not put string in std::. (This is untested)
+ does not work, then I see two solutions:
+
+ <itemizedlist>
+ <listitem><para>
+ Define <command>std::</command> as a macro if the compiler
+ doesn't know about <command>std::</command>.
+ <programlisting>
+ #ifdef OLD_COMPILER
+ #define std
+ #endif
+ </programlisting>
+ (thanks to Juergen Heinzl who posted this solution on
+ gnu.gcc.help)
+ </para></listitem>
+
+ <listitem><para>
+ Define a macro <symbol>NS_STD</symbol>, which is defined to
+ either "" or "std"
+ based on an autoconf-test. Then you should be able to use
+ <command>NS_STD::string</command>, which will evaluate to
+ <command>::string</command> ("string in the global namespace") on
+ systems that do not put string in std::. (This is untested)
+ </para></listitem>
+ </itemizedlist>
+
</para>
</section>
@@ -288,7 +317,7 @@ o make this work: <link linkend="sec-gtk
As you can see, this currently lacks an example of a project
which uses libstdc++-symbols in headers in a back-portable way
(except for Gtk--: see the <link linkend="sec-gtkmm-hack"
- endterm="sec-gtkmm-hack.title">section on the gtkmm-hack</link>).
+ endterm="sec-gtkmm-hack.title">section on the gtkmm-hack</link>).
</para>
</section>
</section> <!-- end of namespace-section -->
@@ -330,19 +359,19 @@ o make this work: <link linkend="sec-gtk
</funcsynopsisinfo>
<funcprototype>
<funcdef>
- <function>basic_filebuf<...>::basic_filebuf<...>
- </function>
- </funcdef>
- <paramdef>__c_file_type* <parameter>file</parameter></paramdef>
+ <function>basic_filebuf<...>::basic_filebuf<...>
+ </function>
+ </funcdef>
+ <paramdef>__c_file_type* <parameter>file</parameter></paramdef>
<paramdef>ios_base::open_mode <parameter>mode</parameter></paramdef>
<paramdef>int <parameter>size</parameter></paramdef>
</funcprototype>
</funcsynopsis>
but the the signature of this constructor has changed often, and
it might change again. For the current state of this, check
- <ulink url="../ext/howto.html">the howto for extensions</ulink>.
- </para>
- <para>
+ <ulink url="../ext/howto.html">the howto for extensions</ulink>.
+ </para>
+ <para>
For a portable solution (among systems which use
filedescriptors), you need to implement a subclass of
<command>std::streambuf</command> (or
@@ -359,8 +388,8 @@ o make this work: <link linkend="sec-gtk
source-code</ulink>.
</para>
<para>
- The old C++-headers (iostream.h etc.) are available, but gcc generates
- a warning that you are using deprecated headers.
+ The old C++-headers (iostream.h etc.) are available, but gcc generates
+ a warning that you are using deprecated headers.
</para>
<section id = "sec-cheaders" label = "4.1">
@@ -372,13 +401,13 @@ o make this work: <link linkend="sec-gtk
omitting the extension (.h). For example, instead of using
<filename class="headerfile"><math.h></filename>, you
should use <filename class =
- "headerfile"><cmath></filename>. In some cases this has
+ "headerfile"><cmath></filename>. In some cases this has
the advantage that the C++-header is more standardized than
the C-header (i.e. <filename
- class="headerfile"><ctime></filename> (almost)
+ class="headerfile"><ctime></filename> (almost)
corresponds to either <filename class =
- "headerfile"><time.h></filename> or <filename class =
- "headerfile"><sys/time.h></filename>).
+ "headerfile"><time.h></filename> or <filename class =
+ "headerfile"><sys/time.h></filename>).
The standard specifies that if you include the C-style header
(<filename class = "headerfile"><math.h></filename> in
@@ -386,7 +415,7 @@ o make this work: <link linkend="sec-gtk
namespace and in namespace <command>std::</command> (but
libstdc++ does not yet have fully compliant headers) On the
other hand, if you include only the new header (i.e. <filename
- class = "headerfile"><cmath></filename>), the symbols
+ class = "headerfile"><cmath></filename>), the symbols
will only be defined in namespace <command>std::</command>
(and macros will be converted to inline-functions).
</para>
@@ -394,8 +423,8 @@ o make this work: <link linkend="sec-gtk
For more information on this, and for information on how the
GNU C++ implementation might reuse ("shadow") the C
library-functions, have a look at <ulink
- url="http://www.cantrip.org/cheaders.html">
- www.cantrip.org</ulink>.
+ url="http://www.cantrip.org/cheaders.html">
+ www.cantrip.org</ulink>.
</para>
</section>
@@ -408,8 +437,8 @@ o make this work: <link linkend="sec-gtk
In earlier versions of the standard,
<filename class="headerfile"><fstream.h></filename>,
<filename class="headerfile"><ostream.h></filename>
- and <filename class="headerfile"><istream.h></filename>
- used to define
+ and <filename class="headerfile"><istream.h></filename>
+ used to define
<command>cout</command>, <command>cin</command> and so on. Because
of the templatized iostreams in libstdc++-v3, you need to include
<filename class = "headerfile"><iostream></filename>
@@ -452,8 +481,8 @@ o make this work: <link linkend="sec-gtk
<filename class="headerfile"><ctype.h></filename>
-functionality as macros (isspace, isalpha etc.). Libstdc++-v3
"shadows" these macros as described in the <link
- linkend="sec-cheaders" endterm="sec-cheaders.title">section about
- c-headers</link>.
+ linkend="sec-cheaders" endterm="sec-cheaders.title">section about
+ c-headers</link>.
</para>
<para>
Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3
@@ -478,7 +507,7 @@ o make this work: <link linkend="sec-gtk
Another solution which would fix g++ is to tell the user to modify a
header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.x) define a
macro which tells <filename
- class="headerfile"><ctype.h></filename> to define functions
+ class="headerfile"><ctype.h></filename> to define functions
instead of macros:
<programlisting>
// This keeps isalnum, et al from being propagated as macros.
@@ -492,7 +521,7 @@ o make this work: <link linkend="sec-gtk
<para>
Another problem arises if you put a <command>using namespace
std;</command> declaration at the top, and include <filename class
- = "headerfile"><ctype.h></filename>. This will result in
+ = "headerfile"><ctype.h></filename>. This will result in
ambiguities between the definitions in the global namespace
(<filename class = "headerfile"><ctype.h></filename>) and the
definitions in namespace <command>std::</command>
@@ -506,8 +535,8 @@ o make this work: <link linkend="sec-gtk
--enable-cshadow-headers is currently broken. As a result, shadow
headers are not being searched....
</quote>
- This is now outdated, but gcc 3.0 still does not have fully
- compliant "shadow headers".
+ This is now outdated, but gcc 3.0 still does not have fully
+ compliant "shadow headers".
</para>
</section>
@@ -593,12 +622,12 @@ o make this work: <link linkend="sec-gtk
</section>
<section id="sec-scan-form" label="11">
- <title>GNU Extensions ostream::form and istream::scan</title>
- <para>
- These are not supported any more - use
- <link linkend="sec-stringstream" endterm="sec-stringstream.title">
- stringstreams</link> instead.
- </para>
+ <title>GNU Extensions ostream::form and istream::scan</title>
+ <para>
+ These are not supported any more - use
+ <link linkend="sec-stringstream" endterm="sec-stringstream.title">
+ stringstreams</link> instead.
+ </para>
</section>
<section id="sec-stringstream" label="12">
@@ -606,10 +635,10 @@ o make this work: <link linkend="sec-gtk
<para>
Libstdc++-v3 provides the new
<command>i/ostringstream</command>-classes, (<filename
- class="headerfile"><sstream></filename>), but for compatibility
+ class="headerfile"><sstream></filename>), but for compatibility
with older implementations you still have to use
<command>i/ostrstream</command> (<filename
- class="headerfile"><strstream></filename>):
+ class="headerfile"><strstream></filename>):
<programlisting>
#ifdef HAVE_SSTREAM
#include <sstream>
@@ -689,19 +718,19 @@ o make this work: <link linkend="sec-gtk
void fromString(const string& input, X& any)
{
#ifdef HAVE_SSTREAM
- std::istringstream iss(input);
+ std::istringstream iss(input);
#else
- std::istrstream iss(input.c_str());
+ std::istrstream iss(input.c_str());
#endif
- X temp;
- iss >> temp;
- if (iss.fail())
- throw runtime_error(..)
- any = temp;
+ X temp;
+ iss >> temp;
+ if (iss.fail())
+ throw runtime_error(..)
+ any = temp;
}
</programlisting>
- Another example of using stringstreams is in <ulink
- url="../21_strings/howto.html">this howto</ulink>.
+ Another example of using stringstreams is in <ulink
+ url="../21_strings/howto.html">this howto</ulink>.
</para>
<para>
I have read the Josuttis book on Standard C++, so some information