porting.texi

测试手写程序

\input texinfo

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

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

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

Copyright (c) 2000, 2001 Free Software Foundation, Inc.
@end ifinfo

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

@titlepage
@title Porting libstdc++-v3
@author Mark Mitchell
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000, 2001 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.1 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 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.  

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.

Here are the primary steps required to port the library:

@menu
* Operating system::    Configuring for your operating system.
* 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'll have to change the @file{configure.target} 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.  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}.

The first file to create in this directory, should be called
@file{bits/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 two libstdc++-v3-specific macros which may be
defined.  @code{_G_USING_THUNKS} 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).
@code{_GLIBCPP_AVOID_FSEEK} may be defined if seeking on an interactive
stream (or one hooked to a pipe) is not allowed by the OS.  In this
case, getc()/ungetc() will be used at some key locations in the library
implementation instead of fseek().  Currently, the code path to avoid
fseek() is only enabled when the seek size is 1 character away from the
current stream position.  This is known to improve *-unknown-freebsd*,
sparc-sun-solaris2.* and *-*-mingw32*.

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

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

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

@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/bits}.  However, these files will almost
certainly need some modification.

The first file to write is @file{bits/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{bits/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{bits/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
elements in that table.  If you don't mind taking a minor performance
penalty, or if your library doesn't implement @code{toupper} and
@code{tolower} in this way, you can pick any pointer-to-integer type,
but you must still define the type.

The enumeration should give definitions for all the values in the above
example, using the values from your native @file{<ctype.h>}.  They can
be given symbolically (as above), or numerically, if you prefer.  You do
not have to include @file{<ctype.h>} in this header; it will always be
included before @file{bits/ctype_base.h} is included.

The next file to write is @file{bits/ctype_noninline.h}, which also does
not require include guards.  This file defines a few member functions
that will be included in @file{include/bits/locale_facets.h}.  The first
function that must be written is the @code{ctype<char>::ctype}
constructor.  Here is the IRIX example:

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