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