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