\input texinfo@c ---------------------------------------------------------------------@c Prologue@c ---------------------------------------------------------------------@setfilename porting.info@settitle Porting libstdc++-v3@setchapternewpage odd@copyingCopyright @copyright{} 2000, 2001, 2002, 2003, 2005 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.2 orany later version published by the Free Software Foundation; with theInvariant Sections being ``GNU General Public License'', the Front-Covertexts 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@ifinfoThis 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++-v3This 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 newtarget, you must edit some configuration files and provide some newheader files.  Unless this is done, libstdc++-v3 will use genericsettings which may not be correct for your target; even if they arecorrect, they will likely be inefficient.Before you get started, make sure that you have a working C library onyour target.  The C library need not precisely comply with anyparticular standard, but should generally conform to the requirementsimposed by the ANSI/ISO standard.In addition, you should try to verify that the C++ compiler generallyworks.  It is difficult to test the C++ compiler without a workinglibrary, but you should at least try some minimal test cases.(Note that what we think of as a ``target,'' the library refers to asa ``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 systemIf you are porting to a new operating system (as opposed to a new chipusing an existing operating system), you will need to create a newdirectory in the @file{config/os} hierarchy.  For example, the IRIXconfiguration files are all in @file{config/os/irix}.  There is no setway 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 configurationdirectories for these two versions of Solaris.  On the other hand, bothSolaris 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 adirectory under @file{config/os} to store the files for your operatingsystem.You might have to change the @file{configure.host} file to ensure thatyour new directory is activated.  Look for the switch statement that sets@code{os_include_dir}, and add a pattern to handle your operating systemif the default will not suffice.  The switch statement switches on onlythe 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 theOS 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 definitionsthat are required to allow the C++ library to work with your C library.Several libstdc++-v3 source files unconditionally define the macro@code{_POSIX_SOURCE}.  On many systems, defining this macro causeslarge portions of the C library header files to be eliminatedat preprocessing time.  Therefore, you may have to @code{#undef} thismacro, or define other macros (like @code{_LARGEFILE_SOURCE} or@code{__EXTENSIONS__}).  You won't know what macros to define orundefine at this point; you'll have to try compiling the library andseeing what goes wrong.  If you see errors about calling functionsthat have not been declared, look in your C library headers to see ifthe functions are declared there, and then figure out what macros youneed to define.  You will need to add them to the@code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for yourtarget.  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 bedefined:@code{_GLIBCXX_USE_C99_CHECK} may be defined to 1 to check C99function declarations (which are not covered by specialization below)found in system headers against versions found in the library headersderived from the standard.@code{_GLIBCXX_USE_C99_DYNAMIC} may be defined to an expression thatyields 0 if and only if the system headers are exposing proper supportfor C99 functions (which are not covered by specialization below).  Ifdefined, it must be 0 while bootstrapping the compiler/rebuilding thelibrary.@code{_GLIBCXX_USE_C99_LONG_LONG_CHECK} may be defined to 1 to checkthe set of C99 long long function declarations found in system headersagainst versions found in the library headers derived from thestandard.@code{_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC} may be defined to anexpression that yields 0 if and only if the system headers areexposing proper support for the set of C99 long long functions.  Ifdefined, it must be 0 while bootstrapping the compiler/rebuilding thelibrary.@code{_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC} may be defined to anexpression that yields 0 if and only if the system headersare 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 definedto 1 to check the related set of function declarations found in systemheaders against versions found in the library headers derived fromthe standard.@code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC} may be definedto an expression that yields 0 if and only if the system headersare 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, likethis:@example#ifndef _GLIBCXX_OS_DEFINES#define _GLIBCXX_OS_DEFINES...#endif@end exampleWe recommend copying an existing @file{os_defines.h} to use as astarting point.@c ---------------------------------------------------------------------@c CPU@c ---------------------------------------------------------------------@node CPU@chapter CPUIf you are porting to a new chip (as opposed to a new operating systemrunning 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 configurationdirectory, but careful naming choices will allow the configury to find yoursetup files without explicit help.We recommend that for a target triplet @code{<CPU>-<vendor>-<OS>}, youname your configuration directory @file{config/cpu/<CPU>}.  If you do this,the configury will find the directory by itself.  Otherwise you will need toedit 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, forexample, @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 notappropriate for your chip.@c ---------------------------------------------------------------------@c Character types@c ---------------------------------------------------------------------@node Character types@chapter Character typesThe library requires that you provide three header files to implementcharacter 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 almostcertainly need some modification.The first file to write is @file{ctype_base.h}.  This file providessome very basic information about character classification.  The libstdc++-v3library assumes that your C library implements @file{<ctype.h>} by usinga table (indexed by character code) containing integers, where each ofthese integers is a bit-mask indicating whether the character isupper-case, lower-case, alphabetic, etc.  The @file{ctype_base.h}file gives the type of the integer, and the values of the various bitmasks.  You will have to peer at your own @file{<ctype.h>} to figure outhow 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 typedeclarations, and one enumeration declaration, like this example, takenfrom the IRIX configuration:@examplestruct 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@noindentThe @code{mask} type is the type of the elements in the table.  If yourC 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 theelements in that table.  If you don't mind taking a minor performancepenalty, 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 aboveexample, using the values from your native @file{<ctype.h>}.  They canbe given symbolically (as above), or numerically, if you prefer.  You do