64e8f36132
2002-10-10 Phil Edwards <pme@gcc.gnu.org> * docs/html/21_strings/howto.html: Write #5, char_traits. * docs/html/17_intro/porting.texi: Expand on os_include_dir. * docs/html/17_intro/porting.html: Regenerate. From-SVN: r58031
887 lines
39 KiB
HTML
887 lines
39 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Porting libstdc++-v3</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name=description content="Porting libstdc++-v3">
|
|
<meta name=generator content="makeinfo 4.2">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel=generator-home>
|
|
</head>
|
|
<body>
|
|
<h1>Porting libstdc++-v3</h1>
|
|
<p><hr>
|
|
Node:<a name="Top">Top</a>,
|
|
Next:<a rel=next accesskey=n href="#Operating%20system">Operating system</a>,
|
|
Up:<a rel=up accesskey=u href="#dir">(dir)</a>
|
|
<br>
|
|
|
|
<h2>Porting libstdc++-v3</h2>
|
|
|
|
<p>This document explains how to port libstdc++-v3 (the GNU C++ library) to
|
|
a new target.
|
|
|
|
<p>In order to make the GNU C++ library (libstdc++-v3) work with a new
|
|
target, you must edit some configuration files and provide some new
|
|
header files. Unless this is done, libstdc++-v3 will use generic
|
|
settings which may not be correct for your target; even if they are
|
|
correct, they will likely be inefficient.
|
|
|
|
<p>Before you get started, make sure that you have a working C library on
|
|
your target. The C library need not precisely comply with any
|
|
particular standard, but should generally conform to the requirements
|
|
imposed by the ANSI/ISO standard.
|
|
|
|
<p>In addition, you should try to verify that the C++ compiler generally
|
|
works. It is difficult to test the C++ compiler without a working
|
|
library, but you should at least try some minimal test cases.
|
|
|
|
<p>Here are the primary steps required to port the library:
|
|
|
|
<ul>
|
|
<li><a accesskey=1 href="#Operating%20system">Operating system</a>: Configuring for your operating system.
|
|
<li><a accesskey=2 href="#CPU">CPU</a>: Configuring for your processor chip.
|
|
<li><a accesskey=3 href="#Character%20types">Character types</a>: Implementing character classification.
|
|
<li><a accesskey=4 href="#Thread%20safety">Thread safety</a>: Implementing atomic operations.
|
|
<li><a accesskey=5 href="#Numeric%20limits">Numeric limits</a>: Implementing numeric limits.
|
|
<li><a accesskey=6 href="#Libtool">Libtool</a>: Using libtool.
|
|
<li><a accesskey=7 href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>: How you can copy and share this manual.
|
|
</ul>
|
|
|
|
<p><hr>
|
|
Node:<a name="Operating%20system">Operating system</a>,
|
|
Next:<a rel=next accesskey=n href="#CPU">CPU</a>,
|
|
Previous:<a rel=previous accesskey=p href="#Top">Top</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>Operating system</h2>
|
|
|
|
<p>If you are porting to a new operating system (as opposed to a new chip
|
|
using an existing operating system), you will need to create a new
|
|
directory in the <code>config/os</code> hierarchy. For example, the IRIX
|
|
configuration files are all in <code>config/os/irix</code>. There is no set
|
|
way to organize the OS configuration directory. For example,
|
|
<code>config/os/solaris/solaris-2.6</code> and
|
|
<code>config/os/solaris/solaris-2.7</code> are used as configuration
|
|
directories for these two versions of Solaris. On the other hand, both
|
|
Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code>
|
|
directory. The important information is that there needs to be a
|
|
directory under <code>config/os</code> to store the files for your operating
|
|
system.
|
|
|
|
<p>You might have to change the <code>configure.target</code> file to ensure that
|
|
your new directory is activated. Look for the switch statement that sets
|
|
<code>os_include_dir</code>, and add a pattern to handle your operating system
|
|
if the default will not suffice. The switch statement switches on only
|
|
the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code>
|
|
in <code>sparc-sun-solaris2.8</code>. If the new directory is named after the
|
|
OS portion of the triplet (the default), then nothing needs to be changed.
|
|
|
|
<p>The first file to create in this directory, should be called
|
|
<code>os_defines.h</code>. This file contains basic macro definitions
|
|
that are required to allow the C++ library to work with your C library.
|
|
This file should provide macro definitions for <code>__off_t</code>,
|
|
<code>__off64_t</code>, and <code>__ssize_t</code>. Typically, this just looks
|
|
like:
|
|
|
|
<br><pre>#define __off_t off_t
|
|
#define __off64_t off64_t
|
|
#define __ssize_t ssize_t
|
|
</pre>
|
|
|
|
<p>You don't have to provide these definitions if your system library
|
|
already defines these types - but the only library known to provide
|
|
these types is the GNU C Library, so you will almost certainly have to
|
|
provide these macros. Note that this file does not have to include a
|
|
header file that defines <code>off_t</code>, or the other types; you simply
|
|
have to provide the macros.
|
|
|
|
<p>In addition, several libstdc++-v3 source files unconditionally define
|
|
the macro <code>_POSIX_SOURCE</code>. On many systems, defining this macro
|
|
causes large portions of the C library header files to be eliminated
|
|
at preprocessing time. Therefore, you may have to <code>#undef</code> this
|
|
macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or
|
|
<code>__EXTENSIONS__</code>). You won't know what macros to define or
|
|
undefine at this point; you'll have to try compiling the library and
|
|
seeing what goes wrong. If you see errors about calling functions
|
|
that have not been declared, look in your C library headers to see if
|
|
the functions are declared there, and then figure out what macros you
|
|
need to define. You will need to add them to the
|
|
<code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your
|
|
target. It will not work to simply define these macros in
|
|
<code>os_defines.h</code>.
|
|
|
|
<p>At this time, there is one libstdc++-v3-specific macro which may be
|
|
defined. <code>_G_USING_THUNKS</code> may be defined to 0 to express that the
|
|
port doesn't use thunks (although it is unclear that this is still
|
|
useful since libio support isn't currently working and the g++ v3 ABI
|
|
invalidates the assumption that some ports don't use thunks).
|
|
|
|
<p>Finally, you should bracket the entire file in an include-guard, like
|
|
this:
|
|
|
|
<br><pre>#ifndef _GLIBCPP_OS_DEFINES
|
|
#define _GLIBCPP_OS_DEFINES
|
|
...
|
|
#endif
|
|
</pre>
|
|
|
|
<p>We recommend copying an existing <code>os_defines.h</code> to use as a
|
|
starting point.
|
|
|
|
<p><hr>
|
|
Node:<a name="CPU">CPU</a>,
|
|
Next:<a rel=next accesskey=n href="#Character%20types">Character types</a>,
|
|
Previous:<a rel=previous accesskey=p href="#Operating%20system">Operating system</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>CPU</h2>
|
|
|
|
<p>If you are porting to a new chip (as opposed to a new operating system
|
|
running on an existing chip), you will need to create a new directory in the
|
|
<code>config/cpu</code> hierarchy. Much like the <a href="#Operating%20system">Operating system</a> setup,
|
|
there are no strict rules on how to organize the CPU configuration
|
|
directory, but careful naming choices will allow the configury to find your
|
|
setup files without explicit help.
|
|
|
|
<p>We recommend that for a target triplet <code><CPU>-<vendor>-<OS></code>, you
|
|
name your configuration directory <code>config/cpu/<CPU></code>. If you do this,
|
|
the configury will find the directory itself. Otherwise you will need to
|
|
edit the <code>configure.target</code> file and, in the switch statement that sets
|
|
<code>cpu_include_dir</code>, add a pattern to handle your chip.
|
|
|
|
<p>Note that some chip families share a single configuration directory, for
|
|
example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the
|
|
<code>config/cpu/alpha</code> directory, and there is an entry in the
|
|
<code>configure.target</code> switch statement to handle this.
|
|
|
|
<p>The <code>cpu_include_dir</code> sets default locations for the files controlling
|
|
<a href="#Thread%20safety">Thread safety</a> and <a href="#Numeric%20limits">Numeric limits</a>, if the defaults are not
|
|
appropriate for your chip.
|
|
|
|
<p><hr>
|
|
Node:<a name="Character%20types">Character types</a>,
|
|
Next:<a rel=next accesskey=n href="#Thread%20safety">Thread safety</a>,
|
|
Previous:<a rel=previous accesskey=p href="#CPU">CPU</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>Character types</h2>
|
|
|
|
<p>The library requires that you provide three header files to implement
|
|
character classification, analogous to that provided by the C libraries
|
|
<code><ctype.h></code> header. You can model these on the files provided in
|
|
<code>config/os/generic</code>. However, these files will almost
|
|
certainly need some modification.
|
|
|
|
<p>The first file to write is <code>ctype_base.h</code>. This file provides
|
|
some very basic information about character classification. The libstdc++-v3
|
|
library assumes that your C library implements <code><ctype.h></code> by using
|
|
a table (indexed by character code) containing integers, where each of
|
|
these integers is a bit-mask indicating whether the character is
|
|
upper-case, lower-case, alphabetic, etc. The <code>ctype_base.h</code>
|
|
file gives the type of the integer, and the values of the various bit
|
|
masks. You will have to peer at your own <code><ctype.h></code> to figure out
|
|
how to define the values required by this file.
|
|
|
|
<p>The <code>ctype_base.h</code> header file does not need include guards.
|
|
It should contain a single <code>struct</code> definition called
|
|
<code>ctype_base</code>. This <code>struct</code> should contain two type
|
|
declarations, and one enumeration declaration, like this example, taken
|
|
from the IRIX configuration:
|
|
|
|
<br><pre>struct ctype_base
|
|
{
|
|
typedef unsigned int mask;
|
|
typedef int* __to_type;
|
|
|
|
enum
|
|
{
|
|
space = _ISspace,
|
|
print = _ISprint,
|
|
cntrl = _IScntrl,
|
|
upper = _ISupper,
|
|
lower = _ISlower,
|
|
alpha = _ISalpha,
|
|
digit = _ISdigit,
|
|
punct = _ISpunct,
|
|
xdigit = _ISxdigit,
|
|
alnum = _ISalnum,
|
|
graph = _ISgraph
|
|
};
|
|
};
|
|
</pre>
|
|
|
|
<p>The <code>mask</code> type is the type of the elements in the table. If your
|
|
C library uses a table to map lower-case numbers to upper-case numbers,
|
|
and vice versa, you should define <code>__to_type</code> to be the type of the
|
|
elements in that table. If you don't mind taking a minor performance
|
|
penalty, or if your library doesn't implement <code>toupper</code> and
|
|
<code>tolower</code> in this way, you can pick any pointer-to-integer type,
|
|
but you must still define the type.
|
|
|
|
<p>The enumeration should give definitions for all the values in the above
|
|
example, using the values from your native <code><ctype.h></code>. They can
|
|
be given symbolically (as above), or numerically, if you prefer. You do
|
|
not have to include <code><ctype.h></code> in this header; it will always be
|
|
included before <code>ctype_base.h</code> is included.
|
|
|
|
<p>The next file to write is <code>ctype_noninline.h</code>, which also does
|
|
not require include guards. This file defines a few member functions
|
|
that will be included in <code>include/bits/locale_facets.h</code>. The first
|
|
function that must be written is the <code>ctype<char>::ctype</code>
|
|
constructor. Here is the IRIX example:
|
|
|
|
<br><pre>ctype<char>::ctype(const mask* __table = 0, bool __del = false,
|
|
size_t __refs = 0)
|
|
: _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
|
|
_M_toupper(NULL),
|
|
_M_tolower(NULL),
|
|
_M_ctable(NULL),
|
|
_M_table(!__table
|
|
? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
|
|
: __table)
|
|
{ }
|
|
</pre>
|
|
|
|
<p>There are two parts of this that you might choose to alter. The first,
|
|
and most important, is the line involving <code>__libc_attr</code>. That is
|
|
IRIX system-dependent code that gets the base of the table mapping
|
|
character codes to attributes. You need to substitute code that obtains
|
|
the address of this table on your system. If you want to use your
|
|
operating system's tables to map upper-case letters to lower-case, and
|
|
vice versa, you should initialize <code>_M_toupper</code> and
|
|
<code>_M_tolower</code> with those tables, in similar fashion.
|
|
|
|
<p>Now, you have to write two functions to convert from upper-case to
|
|
lower-case, and vice versa. Here are the IRIX versions:
|
|
|
|
<br><pre>char
|
|
ctype<char>::do_toupper(char __c) const
|
|
{ return _toupper(__c); }
|
|
|
|
char
|
|
ctype<char>::do_tolower(char __c) const
|
|
{ return _tolower(__c); }
|
|
</pre>
|
|
|
|
<p>Your C library provides equivalents to IRIX's <code>_toupper</code> and
|
|
<code>_tolower</code>. If you initialized <code>_M_toupper</code> and
|
|
<code>_M_tolower</code> above, then you could use those tables instead.
|
|
|
|
<p>Finally, you have to provide two utility functions that convert strings
|
|
of characters. The versions provided here will always work - but you
|
|
could use specialized routines for greater performance if you have
|
|
machinery to do that on your system:
|
|
|
|
<br><pre>const char*
|
|
ctype<char>::do_toupper(char* __low, const char* __high) const
|
|
{
|
|
while (__low < __high)
|
|
{
|
|
*__low = do_toupper(*__low);
|
|
++__low;
|
|
}
|
|
return __high;
|
|
}
|
|
|
|
const char*
|
|
ctype<char>::do_tolower(char* __low, const char* __high) const
|
|
{
|
|
while (__low < __high)
|
|
{
|
|
*__low = do_tolower(*__low);
|
|
++__low;
|
|
}
|
|
return __high;
|
|
}
|
|
</pre>
|
|
|
|
<p>You must also provide the <code>ctype_inline.h</code> file, which
|
|
contains a few more functions. On most systems, you can just copy
|
|
<code>config/os/generic/ctype_inline.h</code> and use it on your system.
|
|
|
|
<p>In detail, the functions provided test characters for particular
|
|
properties; they are analogous to the functions like <code>isalpha</code> and
|
|
<code>islower</code> provided by the C library.
|
|
|
|
<p>The first function is implemented like this on IRIX:
|
|
|
|
<br><pre>bool
|
|
ctype<char>::
|
|
is(mask __m, char __c) const throw()
|
|
{ return (_M_table)[(unsigned char)(__c)] & __m; }
|
|
</pre>
|
|
|
|
<p>The <code>_M_table</code> is the table passed in above, in the constructor.
|
|
This is the table that contains the bitmasks for each character. The
|
|
implementation here should work on all systems.
|
|
|
|
<p>The next function is:
|
|
|
|
<br><pre>const char*
|
|
ctype<char>::
|
|
is(const char* __low, const char* __high, mask* __vec) const throw()
|
|
{
|
|
while (__low < __high)
|
|
*__vec++ = (_M_table)[(unsigned char)(*__low++)];
|
|
return __high;
|
|
}
|
|
</pre>
|
|
|
|
<p>This function is similar; it copies the masks for all the characters
|
|
from <code>__low</code> up until <code>__high</code> into the vector given by
|
|
<code>__vec</code>.
|
|
|
|
<p>The last two functions again are entirely generic:
|
|
|
|
<br><pre>const char*
|
|
ctype<char>::
|
|
scan_is(mask __m, const char* __low, const char* __high) const throw()
|
|
{
|
|
while (__low < __high && !this->is(__m, *__low))
|
|
++__low;
|
|
return __low;
|
|
}
|
|
|
|
const char*
|
|
ctype<char>::
|
|
scan_not(mask __m, const char* __low, const char* __high) const throw()
|
|
{
|
|
while (__low < __high && this->is(__m, *__low))
|
|
++__low;
|
|
return __low;
|
|
}
|
|
</pre>
|
|
|
|
<p><hr>
|
|
Node:<a name="Thread%20safety">Thread safety</a>,
|
|
Next:<a rel=next accesskey=n href="#Numeric%20limits">Numeric limits</a>,
|
|
Previous:<a rel=previous accesskey=p href="#Character%20types">Character types</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>Thread safety</h2>
|
|
|
|
<p>The C++ library string functionality requires a couple of atomic
|
|
operations to provide thread-safety. If you don't take any special
|
|
action, the library will use stub versions of these functions that are
|
|
not thread-safe. They will work fine, unless your applications are
|
|
multi-threaded.
|
|
|
|
<p>If you want to provide custom, safe, versions of these functions, there
|
|
are two distinct approaches. One is to provide a version for your CPU,
|
|
using assembly language constructs. The other is to use the
|
|
thread-safety primitives in your operating system. In either case, you
|
|
make a file called <code>atomicity.h</code>, and the variable
|
|
<code>ATOMICITYH</code> must point to this file.
|
|
|
|
<p>If you are using the assembly-language approach, put this code in
|
|
<code>config/cpu/<chip>/atomicity.h</code>, where chip is the name of
|
|
your processor (see <a href="#CPU">CPU</a>). No additional changes are necessary to
|
|
locate the file in this case; <code>ATOMICITYH</code> will be set by default.
|
|
|
|
<p>If you are using the operating system thread-safety primitives approach,
|
|
you can also put this code in the same CPU directory, in which case no more
|
|
work is needed to locate the file. For examples of this approach,
|
|
see the <code>atomicity.h</code> file for IRIX or IA64.
|
|
|
|
<p>Alternatively, if the primitives are more closely related to the OS
|
|
than they are to the CPU, you can put the <code>atomicity.h</code> file in
|
|
the <a href="#Operating%20system">Operating system</a> directory instead. In this case, you must
|
|
edit <code>configure.target</code>, and in the switch statement that handles
|
|
operating systems, override the <code>ATOMICITYH</code> variable to point to
|
|
the appropriate <code>os_include_dir</code>. For examples of this approach,
|
|
see the <code>atomicity.h</code> file for AIX.
|
|
|
|
<p>With those bits out of the way, you have to actually write
|
|
<code>atomicity.h</code> itself. This file should be wrapped in an
|
|
include guard named <code>_BITS_ATOMICITY_H</code>. It should define one
|
|
type, and two functions.
|
|
|
|
<p>The type is <code>_Atomic_word</code>. Here is the version used on IRIX:
|
|
|
|
<br><pre>typedef long _Atomic_word;
|
|
</pre>
|
|
|
|
<p>This type must be a signed integral type supporting atomic operations.
|
|
If you're using the OS approach, use the same type used by your system's
|
|
primitives. Otherwise, use the type for which your CPU provides atomic
|
|
primitives.
|
|
|
|
<p>Then, you must provide two functions. The bodies of these functions
|
|
must be equivalent to those provided here, but using atomic operations:
|
|
|
|
<br><pre>static inline _Atomic_word
|
|
__attribute__ ((__unused__))
|
|
__exchange_and_add (_Atomic_word* __mem, int __val)
|
|
{
|
|
_Atomic_word __result = *__mem;
|
|
*__mem += __val;
|
|
return __result;
|
|
}
|
|
|
|
static inline void
|
|
__attribute__ ((__unused__))
|
|
__atomic_add (_Atomic_word* __mem, int __val)
|
|
{
|
|
*__mem += __val;
|
|
}
|
|
</pre>
|
|
|
|
<p><hr>
|
|
Node:<a name="Numeric%20limits">Numeric limits</a>,
|
|
Next:<a rel=next accesskey=n href="#Libtool">Libtool</a>,
|
|
Previous:<a rel=previous accesskey=p href="#Thread%20safety">Thread safety</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>Numeric limits</h2>
|
|
|
|
<p>The C++ library requires information about the fundamental data types,
|
|
such as the minimum and maximum representable values of each type.
|
|
You can define each of these values individually, but it is usually
|
|
easiest just to indicate how many bits are used in each of the data
|
|
types and let the library do the rest. For information about the
|
|
macros to define, see the top of <code>include/bits/std_limits.h</code>.
|
|
|
|
<p>If you need to define any macros, you can do so in <code>os_defines.h</code>.
|
|
However, if all operating systems for your CPU are likely to use the
|
|
same values, you can provide a CPU-specific file instead so that you
|
|
do not have to provide the same definitions for each operating system.
|
|
To take that approach, create a new file called <code>cpu_limits.h</code> in
|
|
your CPU configuration directory (see <a href="#CPU">CPU</a>).
|
|
|
|
<p><hr>
|
|
Node:<a name="Libtool">Libtool</a>,
|
|
Next:<a rel=next accesskey=n href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>,
|
|
Previous:<a rel=previous accesskey=p href="#Numeric%20limits">Numeric limits</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>Libtool</h2>
|
|
|
|
<p>The C++ library is compiled, archived and linked with libtool.
|
|
Explaining the full workings of libtool is beyond the scope of this
|
|
document, but there are a few, particular bits that are necessary for
|
|
porting.
|
|
|
|
<p>Some parts of the libstdc++-v3 library are compiled with the libtool
|
|
<code>--tags CXX</code> option (the C++ definitions for libtool). Therefore,
|
|
<code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct
|
|
logic to compile and archive objects equivalent to the C version of libtool,
|
|
<code>ltcf-c.sh</code>. Some libtool targets have definitions for C but not
|
|
for C++, or C++ definitions which have not been kept up to date.
|
|
|
|
<p>The C++ run-time library contains initialization code that needs to be
|
|
run as the library is loaded. Often, that requires linking in special
|
|
object files when the C++ library is built as a shared library, or
|
|
taking other system-specific actions.
|
|
|
|
<p>The libstdc++-v3 library is linked with the C version of libtool, even
|
|
though it is a C++ library. Therefore, the C version of libtool needs to
|
|
ensure that the run-time library initializers are run. The usual way to
|
|
do this is to build the library using <code>gcc -shared</code>.
|
|
|
|
<p>If you need to change how the library is linked, look at
|
|
<code>ltcf-c.sh</code> in the top-level directory. Find the switch statement
|
|
that sets <code>archive_cmds</code>. Here, adjust the setting for your
|
|
operating system.
|
|
|
|
<p><hr>
|
|
Node:<a name="GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>,
|
|
Previous:<a rel=previous accesskey=p href="#Libtool">Libtool</a>,
|
|
Up:<a rel=up accesskey=u href="#Top">Top</a>
|
|
<br>
|
|
|
|
<h2>GNU Free Documentation License</h2>
|
|
|
|
<div align="center">Version 1.1, March 2000</div>
|
|
<br><pre>Copyright © 2000 Free Software Foundation, Inc.
|
|
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
</pre>
|
|
|
|
<ol type=1 start=0>
|
|
</p><li>PREAMBLE
|
|
|
|
<p>The purpose of this License is to make a manual, textbook, or other
|
|
written document <dfn>free</dfn> in the sense of freedom: to assure everyone
|
|
the effective freedom to copy and redistribute it, with or without
|
|
modifying it, either commercially or noncommercially. Secondarily,
|
|
this License preserves for the author and publisher a way to get
|
|
credit for their work, while not being considered responsible for
|
|
modifications made by others.
|
|
|
|
<p>This License is a kind of "copyleft", which means that derivative
|
|
works of the document must themselves be free in the same sense. It
|
|
complements the GNU General Public License, which is a copyleft
|
|
license designed for free software.
|
|
|
|
<p>We have designed this License in order to use it for manuals for free
|
|
software, because free software needs free documentation: a free
|
|
program should come with manuals providing the same freedoms that the
|
|
software does. But this License is not limited to software manuals;
|
|
it can be used for any textual work, regardless of subject matter or
|
|
whether it is published as a printed book. We recommend this License
|
|
principally for works whose purpose is instruction or reference.
|
|
|
|
</p><li>APPLICABILITY AND DEFINITIONS
|
|
|
|
<p>This License applies to any manual or other work that contains a
|
|
notice placed by the copyright holder saying it can be distributed
|
|
under the terms of this License. The "Document", below, refers to any
|
|
such manual or work. Any member of the public is a licensee, and is
|
|
addressed as "you".
|
|
|
|
<p>A "Modified Version" of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
|
|
<p>A "Secondary Section" is a named appendix or a front-matter section of
|
|
the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document's overall subject
|
|
(or to related matters) and contains nothing that could fall directly
|
|
within that overall subject. (For example, if the Document is in part a
|
|
textbook of mathematics, a Secondary Section may not explain any
|
|
mathematics.) The relationship could be a matter of historical
|
|
connection with the subject or with related matters, or of legal,
|
|
commercial, philosophical, ethical or political position regarding
|
|
them.
|
|
|
|
<p>The "Invariant Sections" are certain Secondary Sections whose titles
|
|
are designated, as being those of Invariant Sections, in the notice
|
|
that says that the Document is released under this License.
|
|
|
|
<p>The "Cover Texts" are certain short passages of text that are listed,
|
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
the Document is released under this License.
|
|
|
|
<p>A "Transparent" copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the
|
|
general public, whose contents can be viewed and edited directly and
|
|
straightforwardly with generic text editors or (for images composed of
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
drawing editor, and that is suitable for input to text formatters or
|
|
for automatic translation to a variety of formats suitable for input
|
|
to text formatters. A copy made in an otherwise Transparent file
|
|
format whose markup has been designed to thwart or discourage
|
|
subsequent modification by readers is not Transparent. A copy that is
|
|
not "Transparent" is called "Opaque".
|
|
|
|
<p>Examples of suitable formats for Transparent copies include plain
|
|
<small>ASCII</small> without markup, Texinfo input format, LaTeX input format,
|
|
<small>SGML</small> or <small>XML</small> using a publicly available
|
|
<small>DTD</small>, and standard-conforming simple <small>HTML</small> designed
|
|
for human modification. Opaque formats include PostScript,
|
|
<small>PDF</small>, proprietary formats that can be read and edited only by
|
|
proprietary word processors, <small>SGML</small> or <small>XML</small> for which
|
|
the <small>DTD</small> and/or processing tools are not generally available,
|
|
and the machine-generated <small>HTML</small> produced by some word
|
|
processors for output purposes only.
|
|
|
|
<p>The "Title Page" means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
this License requires to appear in the title page. For works in
|
|
formats which do not have any title page as such, "Title Page" means
|
|
the text near the most prominent appearance of the work's title,
|
|
preceding the beginning of the body of the text.
|
|
|
|
</p><li>VERBATIM COPYING
|
|
|
|
<p>You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License applies
|
|
to the Document are reproduced in all copies, and that you add no other
|
|
conditions whatsoever to those of this License. You may not use
|
|
technical measures to obstruct or control the reading or further
|
|
copying of the copies you make or distribute. However, you may accept
|
|
compensation in exchange for copies. If you distribute a large enough
|
|
number of copies you must also follow the conditions in section 3.
|
|
|
|
<p>You may also lend copies, under the same conditions stated above, and
|
|
you may publicly display copies.
|
|
|
|
</p><li>COPYING IN QUANTITY
|
|
|
|
<p>If you publish printed copies of the Document numbering more than 100,
|
|
and the Document's license notice requires Cover Texts, you must enclose
|
|
the copies in covers that carry, clearly and legibly, all these Cover
|
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
the back cover. Both covers must also clearly and legibly identify
|
|
you as the publisher of these copies. The front cover must present
|
|
the full title with all words of the title equally prominent and
|
|
visible. You may add other material on the covers in addition.
|
|
Copying with changes limited to the covers, as long as they preserve
|
|
the title of the Document and satisfy these conditions, can be treated
|
|
as verbatim copying in other respects.
|
|
|
|
<p>If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
|
pages.
|
|
|
|
<p>If you publish or distribute Opaque copies of the Document numbering
|
|
more than 100, you must either include a machine-readable Transparent
|
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
|
a publicly-accessible computer-network location containing a complete
|
|
Transparent copy of the Document, free of added material, which the
|
|
general network-using public has access to download anonymously at no
|
|
charge using public-standard network protocols. If you use the latter
|
|
option, you must take reasonably prudent steps, when you begin
|
|
distribution of Opaque copies in quantity, to ensure that this
|
|
Transparent copy will remain thus accessible at the stated location
|
|
until at least one year after the last time you distribute an Opaque
|
|
copy (directly or through your agents or retailers) of that edition to
|
|
the public.
|
|
|
|
<p>It is requested, but not required, that you contact the authors of the
|
|
Document well before redistributing any large number of copies, to give
|
|
them a chance to provide you with an updated version of the Document.
|
|
|
|
</p><li>MODIFICATIONS
|
|
|
|
<p>You may copy and distribute a Modified Version of the Document under
|
|
the conditions of sections 2 and 3 above, provided that you release
|
|
the Modified Version under precisely this License, with the Modified
|
|
Version filling the role of the Document, thus licensing distribution
|
|
and modification of the Modified Version to whoever possesses a copy
|
|
of it. In addition, you must do these things in the Modified Version:
|
|
|
|
<ol type=A start=1>
|
|
</p><li>Use in the Title Page (and on the covers, if any) a title distinct
|
|
from that of the Document, and from those of previous versions
|
|
(which should, if there were any, be listed in the History section
|
|
of the Document). You may use the same title as a previous version
|
|
if the original publisher of that version gives permission.
|
|
|
|
<li>List on the Title Page, as authors, one or more persons or entities
|
|
responsible for authorship of the modifications in the Modified
|
|
Version, together with at least five of the principal authors of the
|
|
Document (all of its principal authors, if it has less than five).
|
|
|
|
<li>State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.
|
|
|
|
<li>Preserve all the copyright notices of the Document.
|
|
|
|
<li>Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
|
|
<li>Include, immediately after the copyright notices, a license notice
|
|
giving the public permission to use the Modified Version under the
|
|
terms of this License, in the form shown in the Addendum below.
|
|
|
|
<li>Preserve in that license notice the full lists of Invariant Sections
|
|
and required Cover Texts given in the Document's license notice.
|
|
|
|
<li>Include an unaltered copy of this License.
|
|
|
|
<li>Preserve the section entitled "History", and its title, and add to
|
|
it an item stating at least the title, year, new authors, and
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
there is no section entitled "History" in the Document, create one
|
|
stating the title, year, authors, and publisher of the Document as
|
|
given on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.
|
|
|
|
<li>Preserve the network location, if any, given in the Document for
|
|
public access to a Transparent copy of the Document, and likewise
|
|
the network locations given in the Document for previous versions
|
|
it was based on. These may be placed in the "History" section.
|
|
You may omit a network location for a work that was published at
|
|
least four years before the Document itself, or if the original
|
|
publisher of the version it refers to gives permission.
|
|
|
|
<li>In any section entitled "Acknowledgments" or "Dedications",
|
|
preserve the section's title, and preserve in the section all the
|
|
substance and tone of each of the contributor acknowledgments
|
|
and/or dedications given therein.
|
|
|
|
<li>Preserve all the Invariant Sections of the Document,
|
|
unaltered in their text and in their titles. Section numbers
|
|
or the equivalent are not considered part of the section titles.
|
|
|
|
<li>Delete any section entitled "Endorsements". Such a section
|
|
may not be included in the Modified Version.
|
|
|
|
<li>Do not retitle any existing section as "Endorsements"
|
|
or to conflict in title with any Invariant Section.
|
|
</ol>
|
|
|
|
<p>If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
copied from the Document, you may at your option designate some or all
|
|
of these sections as invariant. To do this, add their titles to the
|
|
list of Invariant Sections in the Modified Version's license notice.
|
|
These titles must be distinct from any other section titles.
|
|
|
|
<p>You may add a section entitled "Endorsements", provided it contains
|
|
nothing but endorsements of your Modified Version by various
|
|
parties--for example, statements of peer review or that the text has
|
|
been approved by an organization as the authoritative definition of a
|
|
standard.
|
|
|
|
<p>You may add a passage of up to five words as a Front-Cover Text, and a
|
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
of Cover Texts in the Modified Version. Only one passage of
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
through arrangements made by) any one entity. If the Document already
|
|
includes a cover text for the same cover, previously added by you or
|
|
by arrangement made by the same entity you are acting on behalf of,
|
|
you may not add another; but you may replace the old one, on explicit
|
|
permission from the previous publisher that added the old one.
|
|
|
|
<p>The author(s) and publisher(s) of the Document do not by this License
|
|
give permission to use their names for publicity for or to assert or
|
|
imply endorsement of any Modified Version.
|
|
|
|
</p><li>COMBINING DOCUMENTS
|
|
|
|
<p>You may combine the Document with other documents released under this
|
|
License, under the terms defined in section 4 above for modified
|
|
versions, provided that you include in the combination all of the
|
|
Invariant Sections of all of the original documents, unmodified, and
|
|
list them all as Invariant Sections of your combined work in its
|
|
license notice.
|
|
|
|
<p>The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
copy. If there are multiple Invariant Sections with the same name but
|
|
different contents, make the title of each such section unique by
|
|
adding at the end of it, in parentheses, the name of the original
|
|
author or publisher of that section if known, or else a unique number.
|
|
Make the same adjustment to the section titles in the list of
|
|
Invariant Sections in the license notice of the combined work.
|
|
|
|
<p>In the combination, you must combine any sections entitled "History"
|
|
in the various original documents, forming one section entitled
|
|
"History"; likewise combine any sections entitled "Acknowledgments",
|
|
and any sections entitled "Dedications". You must delete all sections
|
|
entitled "Endorsements."
|
|
|
|
</p><li>COLLECTIONS OF DOCUMENTS
|
|
|
|
<p>You may make a collection consisting of the Document and other documents
|
|
released under this License, and replace the individual copies of this
|
|
License in the various documents with a single copy that is included in
|
|
the collection, provided that you follow the rules of this License for
|
|
verbatim copying of each of the documents in all other respects.
|
|
|
|
<p>You may extract a single document from such a collection, and distribute
|
|
it individually under this License, provided you insert a copy of this
|
|
License into the extracted document, and follow this License in all
|
|
other respects regarding verbatim copying of that document.
|
|
|
|
</p><li>AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
<p>A compilation of the Document or its derivatives with other separate
|
|
and independent documents or works, in or on a volume of a storage or
|
|
distribution medium, does not as a whole count as a Modified Version
|
|
of the Document, provided no compilation copyright is claimed for the
|
|
compilation. Such a compilation is called an "aggregate", and this
|
|
License does not apply to the other self-contained works thus compiled
|
|
with the Document, on account of their being thus compiled, if they
|
|
are not themselves derivative works of the Document.
|
|
|
|
<p>If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one quarter
|
|
of the entire aggregate, the Document's Cover Texts may be placed on
|
|
covers that surround only the Document within the aggregate.
|
|
Otherwise they must appear on covers around the whole aggregate.
|
|
|
|
</p><li>TRANSLATION
|
|
|
|
<p>Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section 4.
|
|
Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include
|
|
translations of some or all Invariant Sections in addition to the
|
|
original versions of these Invariant Sections. You may include a
|
|
translation of this License provided that you also include the
|
|
original English version of this License. In case of a disagreement
|
|
between the translation and the original English version of this
|
|
License, the original English version will prevail.
|
|
|
|
</p><li>TERMINATION
|
|
|
|
<p>You may not copy, modify, sublicense, or distribute the Document except
|
|
as expressly provided for under this License. Any other attempt to
|
|
copy, modify, sublicense or distribute the Document is void, and will
|
|
automatically terminate your rights under this License. However,
|
|
parties who have received copies, or rights, from you under this
|
|
License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
|
|
</p><li>FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
<p>The Free Software Foundation may publish new, revised versions
|
|
of the GNU Free Documentation License from time to time. Such new
|
|
versions will be similar in spirit to the present version, but may
|
|
differ in detail to address new problems or concerns. See
|
|
<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
|
|
|
|
<p>Each version of the License is given a distinguishing version number.
|
|
If the Document specifies that a particular numbered version of this
|
|
License "or any later version" applies to it, you have the option of
|
|
following the terms and conditions either of that specified version or
|
|
of any later version that has been published (not as a draft) by the
|
|
Free Software Foundation. If the Document does not specify a version
|
|
number of this License, you may choose any version ever published (not
|
|
as a draft) by the Free Software Foundation.
|
|
</ol>
|
|
|
|
<h3>ADDENDUM: How to use this License for your documents</h3>
|
|
|
|
<p>To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
|
|
<br><pre> Copyright (C) <var>year</var> <var>your name</var>.
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.1
|
|
or any later version published by the Free Software Foundation;
|
|
with the Invariant Sections being <var>list their titles</var>, with the
|
|
Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts being <var>list</var>.
|
|
A copy of the license is included in the section entitled ``GNU
|
|
Free Documentation License''.
|
|
</pre>
|
|
|
|
<p>If you have no Invariant Sections, write "with no Invariant Sections"
|
|
instead of saying which ones are invariant. If you have no
|
|
Front-Cover Texts, write "no Front-Cover Texts" instead of
|
|
"Front-Cover Texts being <var>list</var>"; likewise for Back-Cover Texts.
|
|
|
|
<p>If your document contains nontrivial examples of program code, we
|
|
recommend releasing these examples in parallel under your choice of
|
|
free software license, such as the GNU General Public License,
|
|
to permit their use in free software.
|
|
|
|
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a name="toc_Top"></a>
|
|
<a href="#Top">Porting libstdc++-v3</a>
|
|
<li><a name="toc_Operating%20system"></a>
|
|
<a href="#Operating%20system">Operating system</a>
|
|
<li><a name="toc_CPU"></a>
|
|
<a href="#CPU">CPU</a>
|
|
<li><a name="toc_Character%20types"></a>
|
|
<a href="#Character%20types">Character types</a>
|
|
<li><a name="toc_Thread%20safety"></a>
|
|
<a href="#Thread%20safety">Thread safety</a>
|
|
<li><a name="toc_Numeric%20limits"></a>
|
|
<a href="#Numeric%20limits">Numeric limits</a>
|
|
<li><a name="toc_Libtool"></a>
|
|
<a href="#Libtool">Libtool</a>
|
|
<li><a name="toc_GNU%20Free%20Documentation%20License"></a>
|
|
<a href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>
|
|
<ul>
|
|
<li><a href="#GNU%20Free%20Documentation%20License">ADDENDUM: How to use this License for your documents</a>
|
|
</ul>
|
|
</ul>
|
|
|
|
</body></html>
|
|
|