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