This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

[libstdc++] new version of porting-howto




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 &lt;link&gt;-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 &lt;link&gt;-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&lt;...&gt;::basic_filebuf&lt;...&gt;
-			</function>
-		</funcdef>
-		<paramdef>__c_file_type* <parameter>file</parameter></paramdef>
+	    <function>basic_filebuf&lt;...&gt;::basic_filebuf&lt;...&gt;
+	    </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">&lt;math.h&gt;</filename>, you
 	should use <filename class =
-	"headerfile">&lt;cmath&gt;</filename>. In some cases this has
+	  "headerfile">&lt;cmath&gt;</filename>. In some cases this has
 	the advantage that the C++-header is more standardized than
 	the C-header (i.e. <filename
-	class="headerfile">&lt;ctime&gt;</filename> (almost)
+	  class="headerfile">&lt;ctime&gt;</filename> (almost)
 	corresponds to either <filename class =
-	"headerfile">&lt;time.h&gt;</filename> or <filename class =
-	"headerfile">&lt;sys/time.h&gt;</filename>).
+	  "headerfile">&lt;time.h&gt;</filename> or <filename class =
+	  "headerfile">&lt;sys/time.h&gt;</filename>).
 
 	The standard specifies that if you include the C-style header
 	(<filename class = "headerfile">&lt;math.h&gt;</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">&lt;cmath&gt;</filename>), the symbols
+	  class = "headerfile">&lt;cmath&gt;</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">&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
+	and <filename class="headerfile">&lt;istream.h&gt;</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">&lt;iostream&gt;</filename>
@@ -452,8 +481,8 @@ o make this work: <link linkend="sec-gtk
       <filename class="headerfile">&lt;ctype.h&gt;</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">&lt;ctype.h&gt;</filename> to define functions
+	class="headerfile">&lt;ctype.h&gt;</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">&lt;ctype.h&gt;</filename>. This will result in
+	= "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 <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">&lt;sstream&gt;</filename>), but for compatibility
+	class="headerfile">&lt;sstream&gt;</filename>), but for compatibility
       with older implementations you still have to use
       <command>i/ostrstream</command> (<filename
-      class="headerfile">&lt;strstream&gt;</filename>):
+	class="headerfile">&lt;strstream&gt;</filename>):
       <programlisting>
 	#ifdef HAVE_SSTREAM
 	#include &lt;sstream&gt;
@@ -689,19 +718,19 @@ o make this work: <link linkend="sec-gtk
 	void fromString(const string&amp; input, X&amp; 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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]