porting.texi

Mac OS X 10.4.9 for x86 Source Code gcc 实现源代码

\input texinfo

@c ---------------------------------------------------------------------
@c Prologue
@c ---------------------------------------------------------------------

@setfilename porting.info
@settitle Porting libstdc++-v3
@setchapternewpage odd

@copying
Copyright @copyright{} 2000, 2001, 2002, 2003 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end copying

@ifinfo
This file explains how to port libstdc++-v3 (the GNU C++ library) to 
a new target.

@insertcopying
@end ifinfo

@c ---------------------------------------------------------------------
@c Titlepage
@c ---------------------------------------------------------------------

@titlepage
@title Porting libstdc++-v3
@author Mark Mitchell
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c ---------------------------------------------------------------------
@c Top
@c ---------------------------------------------------------------------

@node Top
@top Porting libstdc++-v3

This document explains how to port libstdc++-v3 (the GNU C++ library) to 
a new target.

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.

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.

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.

(Note that what we think of as a ``target,'' the library refers to as
a ``host.''  The comment at the top of @file{configure.ac} explains why.)

Here are the primary steps required to port the library:

@menu
* Operating system::    Configuring for your operating system.
* CPU::                 Configuring for your processor chip.
* Character types::     Implementing character classification.
* Thread safety::       Implementing atomic operations.
* Numeric limits::	Implementing numeric limits.
* Libtool::             Using libtool.
* GNU Free Documentation License:: How you can copy and share this manual.
@end menu

@c ---------------------------------------------------------------------
@c Operating system
@c ---------------------------------------------------------------------

@node Operating system
@chapter Operating system

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 @file{config/os} hierarchy.  For example, the IRIX
configuration files are all in @file{config/os/irix}.  There is no set
way to organize the OS configuration directory.  For example,
@file{config/os/solaris/solaris-2.6} and
@file{config/os/solaris/solaris-2.7} 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 @file{config/os/solaris/solaris-2.7}
directory.  The important information is that there needs to be a
directory under @file{config/os} to store the files for your operating
system.

You might have to change the @file{configure.host} file to ensure that
your new directory is activated.  Look for the switch statement that sets
@code{os_include_dir}, 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}
in @code{sparc-sun-solaris2.8}.  If the new directory is named after the
OS portion of the triplet (the default), then nothing needs to be changed.

The first file to create in this directory, should be called
@file{os_defines.h}.  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{__off64_t}, and @code{__ssize_t}.  Typically, this just looks
like:

@example
#define __off_t off_t
#define __off64_t off64_t
#define __ssize_t ssize_t
@end example

@noindent
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}, or the other types; you simply
have to provide the macros.

In addition, several libstdc++-v3 source files unconditionally define
the macro @code{_POSIX_SOURCE}.  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} this
macro, or define other macros (like @code{_LARGEFILE_SOURCE} or
@code{__EXTENSIONS__}).  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} macro in the GCC configuration file for your
target.  It will not work to simply define these macros in
@file{os_defines.h}.

At this time, there are a few libstdc++-v3-specific macros which may be
defined:

@code{_GLIBCXX_USE_C99_CHECK} may be defined to 1 to check C99
function declarations (which are not covered by specialization below)
found in system headers against versions found in the library headers
derived from the standard.

@code{_GLIBCXX_USE_C99_DYNAMIC} may be defined to an expression that
yields 0 if and only if the system headers are exposing proper support
for C99 functions (which are not covered by specialization below).  If
defined, it must be 0 while bootstrapping the compiler/rebuilding the
library.

@code{_GLIBCXX_USE_C99_LONG_LONG_CHECK} may be defined to 1 to check
the set of C99 long long function declarations found in system headers
against versions found in the library headers derived from the
standard.

@code{_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC} may be defined to an
expression that yields 0 if and only if the system headers are
exposing proper support for the set of C99 long long functions.  If
defined, it must be 0 while bootstrapping the compiler/rebuilding the
library.

@code{_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC} may be defined to an
expression that yields 0 if and only if the system headers
are exposing proper support for the related set of macros.  If defined,
it must be 0 while bootstrapping the compiler/rebuilding the library.

@code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK} may be defined
to 1 to check the related set of function declarations found in system
headers against versions found in the library headers derived from
the standard.

@code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC} may be defined
to an expression that yields 0 if and only if the system headers
are exposing proper support for the related set of functions.  If defined,
it must be 0 while bootstrapping the compiler/rebuilding the library.

Finally, you should bracket the entire file in an include-guard, like
this:

@example
#ifndef _GLIBCXX_OS_DEFINES
#define _GLIBCXX_OS_DEFINES
...
#endif
@end example

We recommend copying an existing @file{os_defines.h} to use as a
starting point.

@c ---------------------------------------------------------------------
@c CPU
@c ---------------------------------------------------------------------

@node CPU
@chapter CPU

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
@file{config/cpu} hierarchy.  Much like the @ref{Operating system} 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.

We recommend that for a target triplet @code{<CPU>-<vendor>-<OS>}, you
name your configuration directory @file{config/cpu/<CPU>}.  If you do this,
the configury will find the directory by itself.  Otherwise you will need to
edit the @file{configure.host} file and, in the switch statement that sets
@code{cpu_include_dir}, add a pattern to handle your chip.

Note that some chip families share a single configuration directory, for
example, @code{alpha}, @code{alphaev5}, and @code{alphaev6} all use the
@file{config/cpu/alpha} directory, and there is an entry in the
@file{configure.host} switch statement to handle this.

The @code{cpu_include_dir} sets default locations for the files controlling
@ref{Thread safety} and @ref{Numeric limits}, if the defaults are not
appropriate for your chip.


@c ---------------------------------------------------------------------
@c Character types
@c ---------------------------------------------------------------------

@node Character types
@chapter Character types

The library requires that you provide three header files to implement
character classification, analogous to that provided by the C libraries
@file{<ctype.h>} header.  You can model these on the files provided in
@file{config/os/generic}.  However, these files will almost
certainly need some modification.

The first file to write is @file{ctype_base.h}.  This file provides
some very basic information about character classification.  The libstdc++-v3
library assumes that your C library implements @file{<ctype.h>} 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 @file{ctype_base.h}
file gives the type of the integer, and the values of the various bit
masks.  You will have to peer at your own @file{<ctype.h>} to figure out
how to define the values required by this file.

The @file{ctype_base.h} header file does not need include guards.
It should contain a single @code{struct} definition called
@code{ctype_base}.  This @code{struct} should contain two type
declarations, and one enumeration declaration, like this example, taken
from the IRIX configuration:

@example
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
  @};
@};
@end example

@noindent
The @code{mask} 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} to be the type of the