libstdc++-v3/docs/html/17_intro/porting.html

   1 <html lang="en">
   2 <head>
   3 <title>Porting libstdc++-v3</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name=description content="Porting libstdc++-v3">
   6 <meta name=generator content="makeinfo 4.2">
   7 <link href="http://www.gnu.org/software/texinfo/" rel=generator-home>
   8 </head>
   9 <body>
  10 <h1>Porting libstdc++-v3</h1>
  11 <p><hr>
  12 Node:<a name="Top">Top</a>,
  13 Next:<a rel=next accesskey=n href="#Operating%20system">Operating system</a>,
  14 Up:<a rel=up accesskey=u href="#dir">(dir)</a>
  15 <br>
  16
  17 <h2>Porting libstdc++-v3</h2>
  18
  19 <p>This document explains how to port libstdc++-v3 (the GNU C++ library) to
  20 a new target.
  21
  22 <p>In order to make the GNU C++ library (libstdc++-v3) work with a new
  23 target, you must edit some configuration files and provide some new
  24 header files.  Unless this is done, libstdc++-v3 will use generic
  25 settings which may not be correct for your target; even if they are
  26 correct, they will likely be inefficient.
  27
  28 <p>Before you get started, make sure that you have a working C library on
  29 your target.  The C library need not precisely comply with any
  30 particular standard, but should generally conform to the requirements
  31 imposed by the ANSI/ISO standard.
  32
  33 <p>In addition, you should try to verify that the C++ compiler generally
  34 works.  It is difficult to test the C++ compiler without a working
  35 library, but you should at least try some minimal test cases.
  36
  37 <p>Here are the primary steps required to port the library:
  38
  39 <ul>
  40 <li><a accesskey=1 href="#Operating%20system">Operating system</a>:     Configuring for your operating system.
  41 <li><a accesskey=2 href="#CPU">CPU</a>:                  Configuring for your processor chip.
  42 <li><a accesskey=3 href="#Character%20types">Character types</a>:      Implementing character classification.
  43 <li><a accesskey=4 href="#Thread%20safety">Thread safety</a>:        Implementing atomic operations.
  44 <li><a accesskey=5 href="#Numeric%20limits">Numeric limits</a>:         Implementing numeric limits.
  45 <li><a accesskey=6 href="#Libtool">Libtool</a>:              Using libtool.
  46 <li><a accesskey=7 href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>:  How you can copy and share this manual.
  47 </ul>
  48
  49 <p><hr>
  50 Node:<a name="Operating%20system">Operating system</a>,
  51 Next:<a rel=next accesskey=n href="#CPU">CPU</a>,
  52 Previous:<a rel=previous accesskey=p href="#Top">Top</a>,
  53 Up:<a rel=up accesskey=u href="#Top">Top</a>
  54 <br>
  55
  56 <h2>Operating system</h2>
  57
  58 <p>If you are porting to a new operating system (as opposed to a new chip
  59 using an existing operating system), you will need to create a new
  60 directory in the <code>config/os</code> hierarchy.  For example, the IRIX
  61 configuration files are all in <code>config/os/irix</code>.  There is no set
  62 way to organize the OS configuration directory.  For example,
  63 <code>config/os/solaris/solaris-2.6</code> and
  64 <code>config/os/solaris/solaris-2.7</code> are used as configuration
  65 directories for these two versions of Solaris.  On the other hand, both
  66 Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code>
  67 directory.  The important information is that there needs to be a
  68 directory under <code>config/os</code> to store the files for your operating
  69 system.
  70
  71 <p>You'll have to change the <code>configure.target</code> file to ensure that
  72 your new directory is activated.  Look for the switch statement that
  73 sets <code>os_include_dir</code>, and add a pattern to handle your operating
  74 system.  The switch statement switches on only the OS portion of the
  75 standard target triplet; e.g., the <code>solaris2.8</code> in
  76 <code>sparc-sun-solaris2.8</code>.
  77
  78 <p>The first file to create in this directory, should be called
  79 <code>os_defines.h</code>.  This file contains basic macro definitions
  80 that are required to allow the C++ library to work with your C library.
  81 This file should provide macro definitions for <code>__off_t</code>,
  82 <code>__off64_t</code>, and <code>__ssize_t</code>.  Typically, this just looks
  83 like:
  84
  85 <br><pre>#define __off_t off_t
  86 #define __off64_t off64_t
  87 #define __ssize_t ssize_t
  88 </pre>
  89
  90 <p>You don't have to provide these definitions if your system library
  91 already defines these types - but the only library known to provide
  92 these types is the GNU C Library, so you will almost certainly have to
  93 provide these macros.  Note that this file does not have to include a
  94 header file that defines <code>off_t</code>, or the other types; you simply
  95 have to provide the macros.
  96
  97 <p>In addition, several libstdc++-v3 source files unconditionally define
  98 the macro <code>_POSIX_SOURCE</code>.  On many systems, defining this macro
  99 causes large portions of the C library header files to be eliminated
 100 at preprocessing time.  Therefore, you may have to <code>#undef</code> this
 101 macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or
 102 <code>__EXTENSIONS__</code>).  You won't know what macros to define or
 103 undefine at this point; you'll have to try compiling the library and
 104 seeing what goes wrong.  If you see errors about calling functions
 105 that have not been declared, look in your C library headers to see if
 106 the functions are declared there, and then figure out what macros you
 107 need to define.  You will need to add them to the
 108 <code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your
 109 target.  It will not work to simply define these macros in
 110 <code>os_defines.h</code>.
 111
 112 <p>At this time, there is one libstdc++-v3-specific macro which may be
 113 defined.  <code>_G_USING_THUNKS</code> may be defined to 0 to express that the
 114 port doesn't use thunks (although it is unclear that this is still
 115 useful since libio support isn't currently working and the g++ v3 ABI
 116 invalidates the assumption that some ports don't use thunks).
 117
 118 <p>Finally, you should bracket the entire file in an include-guard, like
 119 this:
 120
 121 <br><pre>#ifndef _GLIBCPP_OS_DEFINES
 122 #define _GLIBCPP_OS_DEFINES
 123 ...
 124 #endif
 125 </pre>
 126
 127 <p>We recommend copying an existing <code>os_defines.h</code> to use as a
 128 starting point.
 129
 130 <p><hr>
 131 Node:<a name="CPU">CPU</a>,
 132 Next:<a rel=next accesskey=n href="#Character%20types">Character types</a>,
 133 Previous:<a rel=previous accesskey=p href="#Operating%20system">Operating system</a>,
 134 Up:<a rel=up accesskey=u href="#Top">Top</a>
 135 <br>
 136
 137 <h2>CPU</h2>
 138
 139 <p>If you are porting to a new chip (as opposed to a new operating system
 140 running on an existing chip), you will need to create a new directory in the
 141 <code>config/cpu</code> hierarchy.  Much like the <a href="#Operating%20system">Operating system</a> setup,
 142 there are no strict rules on how to organize the CPU configuration
 143 directory, but careful naming choices will allow the configury to find your
 144 setup files without explicit help.
 145
 146 <p>We recommend that for a target triplet <code>&lt;CPU&gt;-&lt;vendor&gt;-&lt;OS&gt;</code>, you
 147 name your configuration directory <code>config/cpu/&lt;CPU&gt;</code>.  If you do this,
 148 the configury will find the directory itself.  Otherwise you will need to
 149 edit the <code>configure.target</code> file and, in the switch statement that sets
 150 <code>cpu_include_dir</code>, add a pattern to handle your chip.
 151
 152 <p>Note that some chip families share a single configuration directory, for
 153 example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the
 154 <code>config/cpu/alpha</code> directory, and there is an entry in the
 155 <code>configure.target</code> switch statement to handle this.
 156
 157 <p>The <code>cpu_include_dir</code> sets default locations for the files controlling
 158 <a href="#Thread%20safety">Thread safety</a> and <a href="#Numeric%20limits">Numeric limits</a>, if the defaults are not
 159 appropriate for your chip.
 160
 161 <p><hr>
 162 Node:<a name="Character%20types">Character types</a>,
 163 Next:<a rel=next accesskey=n href="#Thread%20safety">Thread safety</a>,
 164 Previous:<a rel=previous accesskey=p href="#CPU">CPU</a>,
 165 Up:<a rel=up accesskey=u href="#Top">Top</a>
 166 <br>
 167
 168 <h2>Character types</h2>
 169
 170 <p>The library requires that you provide three header files to implement
 171 character classification, analogous to that provided by the C libraries
 172 <code>&lt;ctype.h&gt;</code> header.  You can model these on the files provided in
 173 <code>config/os/generic</code>.  However, these files will almost
 174 certainly need some modification.
 175
 176 <p>The first file to write is <code>ctype_base.h</code>.  This file provides
 177 some very basic information about character classification.  The libstdc++-v3
 178 library assumes that your C library implements <code>&lt;ctype.h&gt;</code> by using
 179 a table (indexed by character code) containing integers, where each of
 180 these integers is a bit-mask indicating whether the character is
 181 upper-case, lower-case, alphabetic, etc.  The <code>ctype_base.h</code>
 182 file gives the type of the integer, and the values of the various bit
 183 masks.  You will have to peer at your own <code>&lt;ctype.h&gt;</code> to figure out
 184 how to define the values required by this file.
 185
 186 <p>The <code>ctype_base.h</code> header file does not need include guards.
 187 It should contain a single <code>struct</code> definition called
 188 <code>ctype_base</code>.  This <code>struct</code> should contain two type
 189 declarations, and one enumeration declaration, like this example, taken
 190 from the IRIX configuration:
 191
 192 <br><pre>struct ctype_base
 193 {
 194   typedef unsigned int  mask;
 195   typedef int*          __to_type;
 196
 197   enum
 198   {
 199     space = _ISspace,
 200     print = _ISprint,
 201     cntrl = _IScntrl,
 202     upper = _ISupper,
 203     lower = _ISlower,
 204     alpha = _ISalpha,
 205     digit = _ISdigit,
 206     punct = _ISpunct,
 207     xdigit = _ISxdigit,
 208     alnum = _ISalnum,
 209     graph = _ISgraph
 210   };
 211 };
 212 </pre>
 213
 214 <p>The <code>mask</code> type is the type of the elements in the table.  If your
 215 C library uses a table to map lower-case numbers to upper-case numbers,
 216 and vice versa, you should define <code>__to_type</code> to be the type of the
 217 elements in that table.  If you don't mind taking a minor performance
 218 penalty, or if your library doesn't implement <code>toupper</code> and
 219 <code>tolower</code> in this way, you can pick any pointer-to-integer type,
 220 but you must still define the type.
 221
 222 <p>The enumeration should give definitions for all the values in the above
 223 example, using the values from your native <code>&lt;ctype.h&gt;</code>.  They can
 224 be given symbolically (as above), or numerically, if you prefer.  You do
 225 not have to include <code>&lt;ctype.h&gt;</code> in this header; it will always be
 226 included before <code>ctype_base.h</code> is included.
 227
 228 <p>The next file to write is <code>ctype_noninline.h</code>, which also does
 229 not require include guards.  This file defines a few member functions
 230 that will be included in <code>include/bits/locale_facets.h</code>.  The first
 231 function that must be written is the <code>ctype&lt;char&gt;::ctype</code>
 232 constructor.  Here is the IRIX example:
 233
 234 <br><pre>ctype&lt;char&gt;::ctype(const mask* __table = 0, bool __del = false,
 235       size_t __refs = 0)
 236   : _Ctype_nois&lt;char&gt;(__refs), _M_del(__table != 0 &amp;&amp; __del),
 237     _M_toupper(NULL),
 238     _M_tolower(NULL),
 239     _M_ctable(NULL),
 240     _M_table(!__table
 241              ? (const mask*) (__libc_attr._ctype_tbl-&gt;_class + 1)
 242              : __table)
 243   { }
 244 </pre>
 245
 246 <p>There are two parts of this that you might choose to alter. The first,
 247 and most important, is the line involving <code>__libc_attr</code>.  That is
 248 IRIX system-dependent code that gets the base of the table mapping
 249 character codes to attributes.  You need to substitute code that obtains
 250 the address of this table on your system.  If you want to use your
 251 operating system's tables to map upper-case letters to lower-case, and
 252 vice versa, you should initialize <code>_M_toupper</code> and
 253 <code>_M_tolower</code> with those tables, in similar fashion.
 254
 255 <p>Now, you have to write two functions to convert from upper-case to
 256 lower-case, and vice versa.  Here are the IRIX versions:
 257
 258 <br><pre>char
 259 ctype&lt;char&gt;::do_toupper(char __c) const
 260 { return _toupper(__c); }
 261
 262 char
 263 ctype&lt;char&gt;::do_tolower(char __c) const
 264 { return _tolower(__c); }
 265 </pre>
 266
 267 <p>Your C library provides equivalents to IRIX's <code>_toupper</code> and
 268 <code>_tolower</code>.  If you initialized <code>_M_toupper</code> and
 269 <code>_M_tolower</code> above, then you could use those tables instead.
 270
 271 <p>Finally, you have to provide two utility functions that convert strings
 272 of characters.  The versions provided here will always work - but you
 273 could use specialized routines for greater performance if you have
 274 machinery to do that on your system:
 275
 276 <br><pre>const char*
 277 ctype&lt;char&gt;::do_toupper(char* __low, const char* __high) const
 278 {
 279   while (__low &lt; __high)
 280     {
 281       *__low = do_toupper(*__low);
 282       ++__low;
 283     }
 284   return __high;
 285 }
 286
 287 const char*
 288 ctype&lt;char&gt;::do_tolower(char* __low, const char* __high) const
 289 {
 290   while (__low &lt; __high)
 291     {
 292       *__low = do_tolower(*__low);
 293       ++__low;
 294     }
 295   return __high;
 296 }
 297 </pre>
 298
 299 <p>You must also provide the <code>ctype_inline.h</code> file, which
 300 contains a few more functions.  On most systems, you can just copy
 301 <code>config/os/generic/ctype_inline.h</code> and use it on your system.
 302
 303 <p>In detail, the functions provided test characters for particular
 304 properties; they are analogous to the functions like <code>isalpha</code> and
 305 <code>islower</code> provided by the C library.
 306
 307 <p>The first function is implemented like this on IRIX:
 308
 309 <br><pre>bool
 310 ctype&lt;char&gt;::
 311 is(mask __m, char __c) const throw()
 312 { return (_M_table)[(unsigned char)(__c)] &amp; __m; }
 313 </pre>
 314
 315 <p>The <code>_M_table</code> is the table passed in above, in the constructor.
 316 This is the table that contains the bitmasks for each character.  The
 317 implementation here should work on all systems.
 318
 319 <p>The next function is:
 320
 321 <br><pre>const char*
 322 ctype&lt;char&gt;::
 323 is(const char* __low, const char* __high, mask* __vec) const throw()
 324 {
 325   while (__low &lt; __high)
 326     *__vec++ = (_M_table)[(unsigned char)(*__low++)];
 327   return __high;
 328 }
 329 </pre>
 330
 331 <p>This function is similar; it copies the masks for all the characters
 332 from <code>__low</code> up until <code>__high</code> into the vector given by
 333 <code>__vec</code>.
 334
 335 <p>The last two functions again are entirely generic:
 336
 337 <br><pre>const char*
 338 ctype&lt;char&gt;::
 339 scan_is(mask __m, const char* __low, const char* __high) const throw()
 340 {
 341   while (__low &lt; __high &amp;&amp; !this-&gt;is(__m, *__low))
 342     ++__low;
 343   return __low;
 344 }
 345
 346 const char*
 347 ctype&lt;char&gt;::
 348 scan_not(mask __m, const char* __low, const char* __high) const throw()
 349 {
 350   while (__low &lt; __high &amp;&amp; this-&gt;is(__m, *__low))
 351     ++__low;
 352   return __low;
 353 }
 354 </pre>
 355
 356 <p><hr>
 357 Node:<a name="Thread%20safety">Thread safety</a>,
 358 Next:<a rel=next accesskey=n href="#Numeric%20limits">Numeric limits</a>,
 359 Previous:<a rel=previous accesskey=p href="#Character%20types">Character types</a>,
 360 Up:<a rel=up accesskey=u href="#Top">Top</a>
 361 <br>
 362
 363 <h2>Thread safety</h2>
 364
 365 <p>The C++ library string functionality requires a couple of atomic
 366 operations to provide thread-safety.  If you don't take any special
 367 action, the library will use stub versions of these functions that are
 368 not thread-safe.  They will work fine, unless your applications are
 369 multi-threaded.
 370
 371 <p>If you want to provide custom, safe, versions of these functions, there
 372 are two distinct approaches.  One is to provide a version for your CPU,
 373 using assembly language constructs.  The other is to use the
 374 thread-safety primitives in your operating system.  In either case, you
 375 make a file called <code>atomicity.h</code>, and the variable
 376 <code>ATOMICITYH</code> must point to this file.
 377
 378 <p>If you are using the assembly-language approach, put this code in
 379 <code>config/cpu/&lt;chip&gt;/atomicity.h</code>, where chip is the name of
 380 your processor (see <a href="#CPU">CPU</a>).  No additional changes are necessary to
 381 locate the file in this case; <code>ATOMICITYH</code> will be set by default.
 382
 383 <p>If you are using the operating system thread-safety primitives approach,
 384 you can also put this code in the same CPU directory, in which case no more
 385 work is needed to locate the file.  For examples of this approach,
 386 see the <code>atomicity.h</code> file for IRIX or IA64.
 387
 388 <p>Alternatively, if the primitives are more closely related to the OS
 389 than they are to the CPU, you can put the <code>atomicity.h</code> file in
 390 the <a href="#Operating%20system">Operating system</a> directory instead.  In this case, you must
 391 edit <code>configure.target</code>, and in the switch statement that handles
 392 operating systems, override the <code>ATOMICITYH</code> variable to point to
 393 the appropriate <code>os_include_dir</code>.  For examples of this approach,
 394 see the <code>atomicity.h</code> file for AIX.
 395
 396 <p>With those bits out of the way, you have to actually write
 397 <code>atomicity.h</code> itself.  This file should be wrapped in an
 398 include guard named <code>_BITS_ATOMICITY_H</code>.  It should define one
 399 type, and two functions.
 400
 401 <p>The type is <code>_Atomic_word</code>.  Here is the version used on IRIX:
 402
 403 <br><pre>typedef long _Atomic_word;
 404 </pre>
 405
 406 <p>This type must be a signed integral type supporting atomic operations.
 407 If you're using the OS approach, use the same type used by your system's
 408 primitives.  Otherwise, use the type for which your CPU provides atomic
 409 primitives.
 410
 411 <p>Then, you must provide two functions.  The bodies of these functions
 412 must be equivalent to those provided here, but using atomic operations:
 413
 414 <br><pre>static inline _Atomic_word
 415 __attribute__ ((__unused__))
 416 __exchange_and_add (_Atomic_word* __mem, int __val)
 417 {
 418   _Atomic_word __result = *__mem;
 419   *__mem += __val;
 420   return __result;
 421 }
 422
 423 static inline void
 424 __attribute__ ((__unused__))
 425 __atomic_add (_Atomic_word* __mem, int __val)
 426 {
 427   *__mem += __val;
 428 }
 429 </pre>
 430
 431 <p><hr>
 432 Node:<a name="Numeric%20limits">Numeric limits</a>,
 433 Next:<a rel=next accesskey=n href="#Libtool">Libtool</a>,
 434 Previous:<a rel=previous accesskey=p href="#Thread%20safety">Thread safety</a>,
 435 Up:<a rel=up accesskey=u href="#Top">Top</a>
 436 <br>
 437
 438 <h2>Numeric limits</h2>
 439
 440 <p>The C++ library requires information about the fundamental data types,
 441 such as the minimum and maximum representable values of each type.
 442 You can define each of these values individually, but it is usually
 443 easiest just to indicate how many bits are used in each of the data
 444 types and let the library do the rest.  For information about the
 445 macros to define, see the top of <code>include/bits/std_limits.h</code>.
 446
 447 <p>If you need to define any macros, you can do so in <code>os_defines.h</code>.
 448 However, if all operating systems for your CPU are likely to use the
 449 same values, you can provide a CPU-specific file instead so that you
 450 do not have to provide the same definitions for each operating system.
 451 To take that approach, create a new file called <code>cpu_limits.h</code> in
 452 your CPU configuration directory (see <a href="#CPU">CPU</a>).
 453
 454 <p><hr>
 455 Node:<a name="Libtool">Libtool</a>,
 456 Next:<a rel=next accesskey=n href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>,
 457 Previous:<a rel=previous accesskey=p href="#Numeric%20limits">Numeric limits</a>,
 458 Up:<a rel=up accesskey=u href="#Top">Top</a>
 459 <br>
 460
 461 <h2>Libtool</h2>
 462
 463 <p>The C++ library is compiled, archived and linked with libtool.
 464 Explaining the full workings of libtool is beyond the scope of this
 465 document, but there are a few, particular bits that are necessary for
 466 porting.
 467
 468 <p>Some parts of the libstdc++-v3 library are compiled with the libtool
 469 <code>--tags CXX</code> option (the C++ definitions for libtool).  Therefore,
 470 <code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct
 471 logic to compile and archive objects equivalent to the C version of libtool,
 472 <code>ltcf-c.sh</code>.  Some libtool targets have definitions for C but not
 473 for C++, or C++ definitions which have not been kept up to date.
 474
 475 <p>The C++ run-time library contains initialization code that needs to be
 476 run as the library is loaded.  Often, that requires linking in special
 477 object files when the C++ library is built as a shared library, or
 478 taking other system-specific actions.
 479
 480 <p>The libstdc++-v3 library is linked with the C version of libtool, even
 481 though it is a C++ library.  Therefore, the C version of libtool needs to
 482 ensure that the run-time library initializers are run.  The usual way to
 483 do this is to build the library using <code>gcc -shared</code>.
 484
 485 <p>If you need to change how the library is linked, look at
 486 <code>ltcf-c.sh</code> in the top-level directory.  Find the switch statement
 487 that sets <code>archive_cmds</code>.  Here, adjust the setting for your
 488 operating system.
 489
 490 <p><hr>
 491 Node:<a name="GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>,
 492 Previous:<a rel=previous accesskey=p href="#Libtool">Libtool</a>,
 493 Up:<a rel=up accesskey=u href="#Top">Top</a>
 494 <br>
 495
 496 <h2>GNU Free Documentation License</h2>
 497
 498 <div align="center">Version 1.1, March 2000</div>
 499 <br><pre>Copyright &copy; 2000 Free Software Foundation, Inc.
 500 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
 501
 502 Everyone is permitted to copy and distribute verbatim copies
 503 of this license document, but changing it is not allowed.
 504 </pre>
 505
 506 <ol type=1 start=0>
 507 </p><li>PREAMBLE
 508
 509 <p>The purpose of this License is to make a manual, textbook, or other
 510 written document <dfn>free</dfn> in the sense of freedom: to assure everyone
 511 the effective freedom to copy and redistribute it, with or without
 512 modifying it, either commercially or noncommercially.  Secondarily,
 513 this License preserves for the author and publisher a way to get
 514 credit for their work, while not being considered responsible for
 515 modifications made by others.
 516
 517 <p>This License is a kind of "copyleft", which means that derivative
 518 works of the document must themselves be free in the same sense.  It
 519 complements the GNU General Public License, which is a copyleft
 520 license designed for free software.
 521
 522 <p>We have designed this License in order to use it for manuals for free
 523 software, because free software needs free documentation: a free
 524 program should come with manuals providing the same freedoms that the
 525 software does.  But this License is not limited to software manuals;
 526 it can be used for any textual work, regardless of subject matter or
 527 whether it is published as a printed book.  We recommend this License
 528 principally for works whose purpose is instruction or reference.
 529
 530 </p><li>APPLICABILITY AND DEFINITIONS
 531
 532 <p>This License applies to any manual or other work that contains a
 533 notice placed by the copyright holder saying it can be distributed
 534 under the terms of this License.  The "Document", below, refers to any
 535 such manual or work.  Any member of the public is a licensee, and is
 536 addressed as "you".
 537
 538 <p>A "Modified Version" of the Document means any work containing the
 539 Document or a portion of it, either copied verbatim, or with
 540 modifications and/or translated into another language.
 541
 542 <p>A "Secondary Section" is a named appendix or a front-matter section of
 543 the Document that deals exclusively with the relationship of the
 544 publishers or authors of the Document to the Document's overall subject
 545 (or to related matters) and contains nothing that could fall directly
 546 within that overall subject.  (For example, if the Document is in part a
 547 textbook of mathematics, a Secondary Section may not explain any
 548 mathematics.)  The relationship could be a matter of historical
 549 connection with the subject or with related matters, or of legal,
 550 commercial, philosophical, ethical or political position regarding
 551 them.
 552
 553 <p>The "Invariant Sections" are certain Secondary Sections whose titles
 554 are designated, as being those of Invariant Sections, in the notice
 555 that says that the Document is released under this License.
 556
 557 <p>The "Cover Texts" are certain short passages of text that are listed,
 558 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
 559 the Document is released under this License.
 560
 561 <p>A "Transparent" copy of the Document means a machine-readable copy,
 562 represented in a format whose specification is available to the
 563 general public, whose contents can be viewed and edited directly and
 564 straightforwardly with generic text editors or (for images composed of
 565 pixels) generic paint programs or (for drawings) some widely available
 566 drawing editor, and that is suitable for input to text formatters or
 567 for automatic translation to a variety of formats suitable for input
 568 to text formatters.  A copy made in an otherwise Transparent file
 569 format whose markup has been designed to thwart or discourage
 570 subsequent modification by readers is not Transparent.  A copy that is
 571 not "Transparent" is called "Opaque".
 572
 573 <p>Examples of suitable formats for Transparent copies include plain
 574 <small>ASCII</small> without markup, Texinfo input format, LaTeX input format,
 575 <small>SGML</small> or <small>XML</small> using a publicly available
 576 <small>DTD</small>, and standard-conforming simple <small>HTML</small> designed
 577 for human modification.  Opaque formats include PostScript,
 578 <small>PDF</small>, proprietary formats that can be read and edited only by
 579 proprietary word processors, <small>SGML</small> or <small>XML</small> for which
 580 the <small>DTD</small> and/or processing tools are not generally available,
 581 and the machine-generated <small>HTML</small> produced by some word
 582 processors for output purposes only.
 583
 584 <p>The "Title Page" means, for a printed book, the title page itself,
 585 plus such following pages as are needed to hold, legibly, the material
 586 this License requires to appear in the title page.  For works in
 587 formats which do not have any title page as such, "Title Page" means
 588 the text near the most prominent appearance of the work's title,
 589 preceding the beginning of the body of the text.
 590
 591 </p><li>VERBATIM COPYING
 592
 593 <p>You may copy and distribute the Document in any medium, either
 594 commercially or noncommercially, provided that this License, the
 595 copyright notices, and the license notice saying this License applies
 596 to the Document are reproduced in all copies, and that you add no other
 597 conditions whatsoever to those of this License.  You may not use
 598 technical measures to obstruct or control the reading or further
 599 copying of the copies you make or distribute.  However, you may accept
 600 compensation in exchange for copies.  If you distribute a large enough
 601 number of copies you must also follow the conditions in section 3.
 602
 603 <p>You may also lend copies, under the same conditions stated above, and
 604 you may publicly display copies.
 605
 606 </p><li>COPYING IN QUANTITY
 607
 608 <p>If you publish printed copies of the Document numbering more than 100,
 609 and the Document's license notice requires Cover Texts, you must enclose
 610 the copies in covers that carry, clearly and legibly, all these Cover
 611 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
 612 the back cover.  Both covers must also clearly and legibly identify
 613 you as the publisher of these copies.  The front cover must present
 614 the full title with all words of the title equally prominent and
 615 visible.  You may add other material on the covers in addition.
 616 Copying with changes limited to the covers, as long as they preserve
 617 the title of the Document and satisfy these conditions, can be treated
 618 as verbatim copying in other respects.
 619
 620 <p>If the required texts for either cover are too voluminous to fit
 621 legibly, you should put the first ones listed (as many as fit
 622 reasonably) on the actual cover, and continue the rest onto adjacent
 623 pages.
 624
 625 <p>If you publish or distribute Opaque copies of the Document numbering
 626 more than 100, you must either include a machine-readable Transparent
 627 copy along with each Opaque copy, or state in or with each Opaque copy
 628 a publicly-accessible computer-network location containing a complete
 629 Transparent copy of the Document, free of added material, which the
 630 general network-using public has access to download anonymously at no
 631 charge using public-standard network protocols.  If you use the latter
 632 option, you must take reasonably prudent steps, when you begin
 633 distribution of Opaque copies in quantity, to ensure that this
 634 Transparent copy will remain thus accessible at the stated location
 635 until at least one year after the last time you distribute an Opaque
 636 copy (directly or through your agents or retailers) of that edition to
 637 the public.
 638
 639 <p>It is requested, but not required, that you contact the authors of the
 640 Document well before redistributing any large number of copies, to give
 641 them a chance to provide you with an updated version of the Document.
 642
 643 </p><li>MODIFICATIONS
 644
 645 <p>You may copy and distribute a Modified Version of the Document under
 646 the conditions of sections 2 and 3 above, provided that you release
 647 the Modified Version under precisely this License, with the Modified
 648 Version filling the role of the Document, thus licensing distribution
 649 and modification of the Modified Version to whoever possesses a copy
 650 of it.  In addition, you must do these things in the Modified Version:
 651
 652 <ol type=A start=1>
 653 </p><li>Use in the Title Page (and on the covers, if any) a title distinct
 654 from that of the Document, and from those of previous versions
 655 (which should, if there were any, be listed in the History section
 656 of the Document).  You may use the same title as a previous version
 657 if the original publisher of that version gives permission.
 658
 659 <li>List on the Title Page, as authors, one or more persons or entities
 660 responsible for authorship of the modifications in the Modified
 661 Version, together with at least five of the principal authors of the
 662 Document (all of its principal authors, if it has less than five).
 663
 664 <li>State on the Title page the name of the publisher of the
 665 Modified Version, as the publisher.
 666
 667 <li>Preserve all the copyright notices of the Document.
 668
 669 <li>Add an appropriate copyright notice for your modifications
 670 adjacent to the other copyright notices.
 671
 672 <li>Include, immediately after the copyright notices, a license notice
 673 giving the public permission to use the Modified Version under the
 674 terms of this License, in the form shown in the Addendum below.
 675
 676 <li>Preserve in that license notice the full lists of Invariant Sections
 677 and required Cover Texts given in the Document's license notice.
 678
 679 <li>Include an unaltered copy of this License.
 680
 681 <li>Preserve the section entitled "History", and its title, and add to
 682 it an item stating at least the title, year, new authors, and
 683 publisher of the Modified Version as given on the Title Page.  If
 684 there is no section entitled "History" in the Document, create one
 685 stating the title, year, authors, and publisher of the Document as
 686 given on its Title Page, then add an item describing the Modified
 687 Version as stated in the previous sentence.
 688
 689 <li>Preserve the network location, if any, given in the Document for
 690 public access to a Transparent copy of the Document, and likewise
 691 the network locations given in the Document for previous versions
 692 it was based on.  These may be placed in the "History" section.
 693 You may omit a network location for a work that was published at
 694 least four years before the Document itself, or if the original
 695 publisher of the version it refers to gives permission.
 696
 697 <li>In any section entitled "Acknowledgments" or "Dedications",
 698 preserve the section's title, and preserve in the section all the
 699 substance and tone of each of the contributor acknowledgments
 700 and/or dedications given therein.
 701
 702 <li>Preserve all the Invariant Sections of the Document,
 703 unaltered in their text and in their titles.  Section numbers
 704 or the equivalent are not considered part of the section titles.
 705
 706 <li>Delete any section entitled "Endorsements".  Such a section
 707 may not be included in the Modified Version.
 708
 709 <li>Do not retitle any existing section as "Endorsements"
 710 or to conflict in title with any Invariant Section.
 711 </ol>
 712
 713 <p>If the Modified Version includes new front-matter sections or
 714 appendices that qualify as Secondary Sections and contain no material
 715 copied from the Document, you may at your option designate some or all
 716 of these sections as invariant.  To do this, add their titles to the
 717 list of Invariant Sections in the Modified Version's license notice.
 718 These titles must be distinct from any other section titles.
 719
 720 <p>You may add a section entitled "Endorsements", provided it contains
 721 nothing but endorsements of your Modified Version by various
 722 parties--for example, statements of peer review or that the text has
 723 been approved by an organization as the authoritative definition of a
 724 standard.
 725
 726 <p>You may add a passage of up to five words as a Front-Cover Text, and a
 727 passage of up to 25 words as a Back-Cover Text, to the end of the list
 728 of Cover Texts in the Modified Version.  Only one passage of
 729 Front-Cover Text and one of Back-Cover Text may be added by (or
 730 through arrangements made by) any one entity.  If the Document already
 731 includes a cover text for the same cover, previously added by you or
 732 by arrangement made by the same entity you are acting on behalf of,
 733 you may not add another; but you may replace the old one, on explicit
 734 permission from the previous publisher that added the old one.
 735
 736 <p>The author(s) and publisher(s) of the Document do not by this License
 737 give permission to use their names for publicity for or to assert or
 738 imply endorsement of any Modified Version.
 739
 740 </p><li>COMBINING DOCUMENTS
 741
 742 <p>You may combine the Document with other documents released under this
 743 License, under the terms defined in section 4 above for modified
 744 versions, provided that you include in the combination all of the
 745 Invariant Sections of all of the original documents, unmodified, and
 746 list them all as Invariant Sections of your combined work in its
 747 license notice.
 748
 749 <p>The combined work need only contain one copy of this License, and
 750 multiple identical Invariant Sections may be replaced with a single
 751 copy.  If there are multiple Invariant Sections with the same name but
 752 different contents, make the title of each such section unique by
 753 adding at the end of it, in parentheses, the name of the original
 754 author or publisher of that section if known, or else a unique number.
 755 Make the same adjustment to the section titles in the list of
 756 Invariant Sections in the license notice of the combined work.
 757
 758 <p>In the combination, you must combine any sections entitled "History"
 759 in the various original documents, forming one section entitled
 760 "History"; likewise combine any sections entitled "Acknowledgments",
 761 and any sections entitled "Dedications".  You must delete all sections
 762 entitled "Endorsements."
 763
 764 </p><li>COLLECTIONS OF DOCUMENTS
 765
 766 <p>You may make a collection consisting of the Document and other documents
 767 released under this License, and replace the individual copies of this
 768 License in the various documents with a single copy that is included in
 769 the collection, provided that you follow the rules of this License for
 770 verbatim copying of each of the documents in all other respects.
 771
 772 <p>You may extract a single document from such a collection, and distribute
 773 it individually under this License, provided you insert a copy of this
 774 License into the extracted document, and follow this License in all
 775 other respects regarding verbatim copying of that document.
 776
 777 </p><li>AGGREGATION WITH INDEPENDENT WORKS
 778
 779 <p>A compilation of the Document or its derivatives with other separate
 780 and independent documents or works, in or on a volume of a storage or
 781 distribution medium, does not as a whole count as a Modified Version
 782 of the Document, provided no compilation copyright is claimed for the
 783 compilation.  Such a compilation is called an "aggregate", and this
 784 License does not apply to the other self-contained works thus compiled
 785 with the Document, on account of their being thus compiled, if they
 786 are not themselves derivative works of the Document.
 787
 788 <p>If the Cover Text requirement of section 3 is applicable to these
 789 copies of the Document, then if the Document is less than one quarter
 790 of the entire aggregate, the Document's Cover Texts may be placed on
 791 covers that surround only the Document within the aggregate.
 792 Otherwise they must appear on covers around the whole aggregate.
 793
 794 </p><li>TRANSLATION
 795
 796 <p>Translation is considered a kind of modification, so you may
 797 distribute translations of the Document under the terms of section 4.
 798 Replacing Invariant Sections with translations requires special
 799 permission from their copyright holders, but you may include
 800 translations of some or all Invariant Sections in addition to the
 801 original versions of these Invariant Sections.  You may include a
 802 translation of this License provided that you also include the
 803 original English version of this License.  In case of a disagreement
 804 between the translation and the original English version of this
 805 License, the original English version will prevail.
 806
 807 </p><li>TERMINATION
 808
 809 <p>You may not copy, modify, sublicense, or distribute the Document except
 810 as expressly provided for under this License.  Any other attempt to
 811 copy, modify, sublicense or distribute the Document is void, and will
 812 automatically terminate your rights under this License.  However,
 813 parties who have received copies, or rights, from you under this
 814 License will not have their licenses terminated so long as such
 815 parties remain in full compliance.
 816
 817 </p><li>FUTURE REVISIONS OF THIS LICENSE
 818
 819 <p>The Free Software Foundation may publish new, revised versions
 820 of the GNU Free Documentation License from time to time.  Such new
 821 versions will be similar in spirit to the present version, but may
 822 differ in detail to address new problems or concerns.  See
 823 <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
 824
 825 <p>Each version of the License is given a distinguishing version number.
 826 If the Document specifies that a particular numbered version of this
 827 License "or any later version" applies to it, you have the option of
 828 following the terms and conditions either of that specified version or
 829 of any later version that has been published (not as a draft) by the
 830 Free Software Foundation.  If the Document does not specify a version
 831 number of this License, you may choose any version ever published (not
 832 as a draft) by the Free Software Foundation.
 833 </ol>
 834
 835 <h3>ADDENDUM: How to use this License for your documents</h3>
 836
 837 <p>To use this License in a document you have written, include a copy of
 838 the License in the document and put the following copyright and
 839 license notices just after the title page:
 840
 841 <br><pre>  Copyright (C)  <var>year</var>  <var>your name</var>.
 842   Permission is granted to copy, distribute and/or modify this document
 843   under the terms of the GNU Free Documentation License, Version 1.1
 844   or any later version published by the Free Software Foundation;
 845   with the Invariant Sections being <var>list their titles</var>, with the
 846   Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts being <var>list</var>.
 847   A copy of the license is included in the section entitled ``GNU
 848   Free Documentation License''.
 849 </pre>
 850
 851 <p>If you have no Invariant Sections, write "with no Invariant Sections"
 852 instead of saying which ones are invariant.  If you have no
 853 Front-Cover Texts, write "no Front-Cover Texts" instead of
 854 "Front-Cover Texts being <var>list</var>"; likewise for Back-Cover Texts.
 855
 856 <p>If your document contains nontrivial examples of program code, we
 857 recommend releasing these examples in parallel under your choice of
 858 free software license, such as the GNU General Public License,
 859 to permit their use in free software.
 860
 861
 862 <h2>Table of Contents</h2>
 863 <ul>
 864 <li><a name="toc_Top"></a>
 865     <a href="#Top">Porting libstdc++-v3</a>
 866 <li><a name="toc_Operating%20system"></a>
 867     <a href="#Operating%20system">Operating system</a>
 868 <li><a name="toc_CPU"></a>
 869     <a href="#CPU">CPU</a>
 870 <li><a name="toc_Character%20types"></a>
 871     <a href="#Character%20types">Character types</a>
 872 <li><a name="toc_Thread%20safety"></a>
 873     <a href="#Thread%20safety">Thread safety</a>
 874 <li><a name="toc_Numeric%20limits"></a>
 875     <a href="#Numeric%20limits">Numeric limits</a>
 876 <li><a name="toc_Libtool"></a>
 877     <a href="#Libtool">Libtool</a>
 878 <li><a name="toc_GNU%20Free%20Documentation%20License"></a>
 879     <a href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>
 880 <ul>
 881 <li><a href="#GNU%20Free%20Documentation%20License">ADDENDUM: How to use this License for your documents</a>
 882 </ul>
 883 </ul>
 884
 885 </body></html>
 886