\input texinfo@c ---------------------------------------------------------------------@c Prologue@c ---------------------------------------------------------------------@setfilename porting.info@settitle Porting libstdc++-v3@setchapternewpage odd@ifinfoThis file explains how to port libstdc++-v3 (the GNU C++ library) to a new target.Copyright (c) 2000, 2001, 2002 Free Software Foundation, Inc.@end ifinfo@c ---------------------------------------------------------------------@c Titlepage@c ---------------------------------------------------------------------@titlepage@title Porting libstdc++-v3@author Mark Mitchell@page@vskip 0pt plus 1filllCopyright @copyright{} 2000, 2001, 2002 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.1 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 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.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'll have to change the @file{configure.target} file to ensure thatyour new directory is activated.  Look for the switch statement thatsets @code{os_include_dir}, and add a pattern to handle your operatingsystem.  The switch statement switches on only the OS portion of thestandard 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{os_defines.h}.  This file contains basic macro definitionsthat 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 lookslike:@example#define __off_t off_t#define __off64_t off64_t#define __ssize_t ssize_t@end example@noindentYou don't have to provide these definitions if your system libraryalready defines these types -- but the only library known to providethese types is the GNU C Library, so you will almost certainly have toprovide these macros.  Note that this file does not have to include aheader file that defines @code{off_t}, or the other types; you simplyhave to provide the macros.In addition, several libstdc++-v3 source files unconditionally definethe macro @code{_POSIX_SOURCE}.  On many systems, defining this macrocauses large 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 is one libstdc++-v3-specific macro which may bedefined.  @code{_G_USING_THUNKS} may be defined to 0 to express that theport doesn't use thunks (although it is unclear that this is stilluseful since libio support isn't currently working and the g++ v3 ABIinvalidates the assumption that some ports don't use thunks).Finally, you should bracket the entire file in an include-guard, likethis:@example#ifndef _GLIBCPP_OS_DEFINES#define _GLIBCPP_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 itself.  Otherwise you will need toedit the @file{configure.target} 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.target} 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 donot have to include @file{<ctype.h>} in this header; it will always beincluded before @file{ctype_base.h} is included.The next file to write is @file{ctype_noninline.h}, which also doesnot require include guards.  This file defines a few member functionsthat will be included in @file{include/bits/locale_facets.h}.  The firstfunction that must be written is the @code{ctype<char>::ctype}constructor.  Here is the IRIX example:@examplectype<char>::ctype(const mask* __table = 0, bool __del = false,       size_t __refs = 0)  : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),