3 @c ---------------------------------------------------------------------
5 @c ---------------------------------------------------------------------
7 @setfilename porting.info
8 @settitle Porting libstdc++-v3
12 Copyright @copyright{} 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with the
17 Invariant Sections being ``GNU General Public License'', the Front-Cover
18 texts being (a) (see below), and with the Back-Cover Texts being (b)
19 (see below). A copy of the license is included in the section entitled
20 ``GNU Free Documentation License''.
22 (a) The FSF's Front-Cover Text is:
26 (b) The FSF's Back-Cover Text is:
28 You have freedom to copy and modify this GNU Manual, like GNU
29 software. Copies published by the Free Software Foundation raise
30 funds for GNU development.
34 This file explains how to port libstdc++-v3 (the GNU C++ library) to
40 @c ---------------------------------------------------------------------
42 @c ---------------------------------------------------------------------
45 @title Porting libstdc++-v3
48 @vskip 0pt plus 1filll
52 @c ---------------------------------------------------------------------
54 @c ---------------------------------------------------------------------
57 @top Porting libstdc++-v3
59 This document explains how to port libstdc++-v3 (the GNU C++ library) to
62 In order to make the GNU C++ library (libstdc++-v3) work with a new
63 target, you must edit some configuration files and provide some new
64 header files. Unless this is done, libstdc++-v3 will use generic
65 settings which may not be correct for your target; even if they are
66 correct, they will likely be inefficient.
68 Before you get started, make sure that you have a working C library on
69 your target. The C library need not precisely comply with any
70 particular standard, but should generally conform to the requirements
71 imposed by the ANSI/ISO standard.
73 In addition, you should try to verify that the C++ compiler generally
74 works. It is difficult to test the C++ compiler without a working
75 library, but you should at least try some minimal test cases.
77 (Note that what we think of as a ``target,'' the library refers to as
78 a ``host.'' The comment at the top of @file{configure.ac} explains why.)
80 Here are the primary steps required to port the library:
83 * Operating system:: Configuring for your operating system.
84 * CPU:: Configuring for your processor chip.
85 * Character types:: Implementing character classification.
86 * Thread safety:: Implementing atomic operations.
87 * Numeric limits:: Implementing numeric limits.
88 * Libtool:: Using libtool.
89 * GNU Free Documentation License:: How you can copy and share this manual.
92 @c ---------------------------------------------------------------------
94 @c ---------------------------------------------------------------------
96 @node Operating system
97 @chapter Operating system
99 If you are porting to a new operating system (as opposed to a new chip
100 using an existing operating system), you will need to create a new
101 directory in the @file{config/os} hierarchy. For example, the IRIX
102 configuration files are all in @file{config/os/irix}. There is no set
103 way to organize the OS configuration directory. For example,
104 @file{config/os/solaris/solaris-2.6} and
105 @file{config/os/solaris/solaris-2.7} are used as configuration
106 directories for these two versions of Solaris. On the other hand, both
107 Solaris 2.7 and Solaris 2.8 use the @file{config/os/solaris/solaris-2.7}
108 directory. The important information is that there needs to be a
109 directory under @file{config/os} to store the files for your operating
112 You might have to change the @file{configure.host} file to ensure that
113 your new directory is activated. Look for the switch statement that sets
114 @code{os_include_dir}, and add a pattern to handle your operating system
115 if the default will not suffice. The switch statement switches on only
116 the OS portion of the standard target triplet; e.g., the @code{solaris2.8}
117 in @code{sparc-sun-solaris2.8}. If the new directory is named after the
118 OS portion of the triplet (the default), then nothing needs to be changed.
120 The first file to create in this directory, should be called
121 @file{os_defines.h}. This file contains basic macro definitions
122 that are required to allow the C++ library to work with your C library.
123 This file should provide macro definitions for @code{__off_t},
124 @code{__off64_t}, and @code{__ssize_t}. Typically, this just looks
128 #define __off_t off_t
129 #define __off64_t off64_t
130 #define __ssize_t ssize_t
134 You don't have to provide these definitions if your system library
135 already defines these types -- but the only library known to provide
136 these types is the GNU C Library, so you will almost certainly have to
137 provide these macros. Note that this file does not have to include a
138 header file that defines @code{off_t}, or the other types; you simply
139 have to provide the macros.
141 In addition, several libstdc++-v3 source files unconditionally define
142 the macro @code{_POSIX_SOURCE}. On many systems, defining this macro
143 causes large portions of the C library header files to be eliminated
144 at preprocessing time. Therefore, you may have to @code{#undef} this
145 macro, or define other macros (like @code{_LARGEFILE_SOURCE} or
146 @code{__EXTENSIONS__}). You won't know what macros to define or
147 undefine at this point; you'll have to try compiling the library and
148 seeing what goes wrong. If you see errors about calling functions
149 that have not been declared, look in your C library headers to see if
150 the functions are declared there, and then figure out what macros you
151 need to define. You will need to add them to the
152 @code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for your
153 target. It will not work to simply define these macros in
156 At this time, there are a few libstdc++-v3-specific macros which may be
159 @code{_GLIBCXX_USE_C99_CHECK} may be defined to 1 to check C99
160 function declarations (which are not covered by specialization below)
161 found in system headers against versions found in the library headers
162 derived from the standard.
164 @code{_GLIBCXX_USE_C99_DYNAMIC} may be defined to an expression that
165 yields 0 if and only if the system headers are exposing proper support
166 for C99 functions (which are not covered by specialization below). If
167 defined, it must be 0 while bootstrapping the compiler/rebuilding the
170 @code{_GLIBCXX_USE_C99_LONG_LONG_CHECK} may be defined to 1 to check
171 the set of C99 long long function declarations found in system headers
172 against versions found in the library headers derived from the
175 @code{_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC} may be defined to an
176 expression that yields 0 if and only if the system headers are
177 exposing proper support for the set of C99 long long functions. If
178 defined, it must be 0 while bootstrapping the compiler/rebuilding the
181 @code{_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC} may be defined to an
182 expression that yields 0 if and only if the system headers
183 are exposing proper support for the related set of macros. If defined,
184 it must be 0 while bootstrapping the compiler/rebuilding the library.
186 @code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK} may be defined
187 to 1 to check the related set of function declarations found in system
188 headers against versions found in the library headers derived from
191 @code{_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC} may be defined
192 to an expression that yields 0 if and only if the system headers
193 are exposing proper support for the related set of functions. If defined,
194 it must be 0 while bootstrapping the compiler/rebuilding the library.
196 Finally, you should bracket the entire file in an include-guard, like
200 #ifndef _GLIBCXX_OS_DEFINES
201 #define _GLIBCXX_OS_DEFINES
206 We recommend copying an existing @file{os_defines.h} to use as a
209 @c ---------------------------------------------------------------------
211 @c ---------------------------------------------------------------------
216 If you are porting to a new chip (as opposed to a new operating system
217 running on an existing chip), you will need to create a new directory in the
218 @file{config/cpu} hierarchy. Much like the @ref{Operating system} setup,
219 there are no strict rules on how to organize the CPU configuration
220 directory, but careful naming choices will allow the configury to find your
221 setup files without explicit help.
223 We recommend that for a target triplet @code{<CPU>-<vendor>-<OS>}, you
224 name your configuration directory @file{config/cpu/<CPU>}. If you do this,
225 the configury will find the directory by itself. Otherwise you will need to
226 edit the @file{configure.host} file and, in the switch statement that sets
227 @code{cpu_include_dir}, add a pattern to handle your chip.
229 Note that some chip families share a single configuration directory, for
230 example, @code{alpha}, @code{alphaev5}, and @code{alphaev6} all use the
231 @file{config/cpu/alpha} directory, and there is an entry in the
232 @file{configure.host} switch statement to handle this.
234 The @code{cpu_include_dir} sets default locations for the files controlling
235 @ref{Thread safety} and @ref{Numeric limits}, if the defaults are not
236 appropriate for your chip.
239 @c ---------------------------------------------------------------------
241 @c ---------------------------------------------------------------------
243 @node Character types
244 @chapter Character types
246 The library requires that you provide three header files to implement
247 character classification, analogous to that provided by the C libraries
248 @file{<ctype.h>} header. You can model these on the files provided in
249 @file{config/os/generic}. However, these files will almost
250 certainly need some modification.
252 The first file to write is @file{ctype_base.h}. This file provides
253 some very basic information about character classification. The libstdc++-v3
254 library assumes that your C library implements @file{<ctype.h>} by using
255 a table (indexed by character code) containing integers, where each of
256 these integers is a bit-mask indicating whether the character is
257 upper-case, lower-case, alphabetic, etc. The @file{ctype_base.h}
258 file gives the type of the integer, and the values of the various bit
259 masks. You will have to peer at your own @file{<ctype.h>} to figure out
260 how to define the values required by this file.
262 The @file{ctype_base.h} header file does not need include guards.
263 It should contain a single @code{struct} definition called
264 @code{ctype_base}. This @code{struct} should contain two type
265 declarations, and one enumeration declaration, like this example, taken
266 from the IRIX configuration:
271 typedef unsigned int mask;
272 typedef int* __to_type;
292 The @code{mask} type is the type of the elements in the table. If your
293 C library uses a table to map lower-case numbers to upper-case numbers,
294 and vice versa, you should define @code{__to_type} to be the type of the
295 elements in that table. If you don't mind taking a minor performance
296 penalty, or if your library doesn't implement @code{toupper} and
297 @code{tolower} in this way, you can pick any pointer-to-integer type,
298 but you must still define the type.
300 The enumeration should give definitions for all the values in the above
301 example, using the values from your native @file{<ctype.h>}. They can
302 be given symbolically (as above), or numerically, if you prefer. You do
303 not have to include @file{<ctype.h>} in this header; it will always be
304 included before @file{ctype_base.h} is included.
306 The next file to write is @file{ctype_noninline.h}, which also does
307 not require include guards. This file defines a few member functions
308 that will be included in @file{include/bits/locale_facets.h}. The first
309 function that must be written is the @code{ctype<char>::ctype}
310 constructor. Here is the IRIX example:
313 ctype<char>::ctype(const mask* __table = 0, bool __del = false,
315 : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
320 ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
326 There are two parts of this that you might choose to alter. The first,
327 and most important, is the line involving @code{__libc_attr}. That is
328 IRIX system-dependent code that gets the base of the table mapping
329 character codes to attributes. You need to substitute code that obtains
330 the address of this table on your system. If you want to use your
331 operating system's tables to map upper-case letters to lower-case, and
332 vice versa, you should initialize @code{_M_toupper} and
333 @code{_M_tolower} with those tables, in similar fashion.
335 Now, you have to write two functions to convert from upper-case to
336 lower-case, and vice versa. Here are the IRIX versions:
340 ctype<char>::do_toupper(char __c) const
341 @{ return _toupper(__c); @}
344 ctype<char>::do_tolower(char __c) const
345 @{ return _tolower(__c); @}
349 Your C library provides equivalents to IRIX's @code{_toupper} and
350 @code{_tolower}. If you initialized @code{_M_toupper} and
351 @code{_M_tolower} above, then you could use those tables instead.
353 Finally, you have to provide two utility functions that convert strings
354 of characters. The versions provided here will always work -- but you
355 could use specialized routines for greater performance if you have
356 machinery to do that on your system:
360 ctype<char>::do_toupper(char* __low, const char* __high) const
362 while (__low < __high)
364 *__low = do_toupper(*__low);
371 ctype<char>::do_tolower(char* __low, const char* __high) const
373 while (__low < __high)
375 *__low = do_tolower(*__low);
382 You must also provide the @file{ctype_inline.h} file, which
383 contains a few more functions. On most systems, you can just copy
384 @file{config/os/generic/ctype_inline.h} and use it on your system.
386 In detail, the functions provided test characters for particular
387 properties; they are analogous to the functions like @code{isalpha} and
388 @code{islower} provided by the C library.
390 The first function is implemented like this on IRIX:
395 is(mask __m, char __c) const throw()
396 @{ return (_M_table)[(unsigned char)(__c)] & __m; @}
400 The @code{_M_table} is the table passed in above, in the constructor.
401 This is the table that contains the bitmasks for each character. The
402 implementation here should work on all systems.
404 The next function is:
409 is(const char* __low, const char* __high, mask* __vec) const throw()
411 while (__low < __high)
412 *__vec++ = (_M_table)[(unsigned char)(*__low++)];
418 This function is similar; it copies the masks for all the characters
419 from @code{__low} up until @code{__high} into the vector given by
422 The last two functions again are entirely generic:
427 scan_is(mask __m, const char* __low, const char* __high) const throw()
429 while (__low < __high && !this->is(__m, *__low))
436 scan_not(mask __m, const char* __low, const char* __high) const throw()
438 while (__low < __high && this->is(__m, *__low))
444 @c ---------------------------------------------------------------------
446 @c ---------------------------------------------------------------------
449 @chapter Thread safety
451 The C++ library string functionality requires a couple of atomic
452 operations to provide thread-safety. If you don't take any special
453 action, the library will use stub versions of these functions that are
454 not thread-safe. They will work fine, unless your applications are
457 If you want to provide custom, safe, versions of these functions, there
458 are two distinct approaches. One is to provide a version for your CPU,
459 using assembly language constructs. The other is to use the
460 thread-safety primitives in your operating system. In either case, you
461 make a file called @file{atomicity.h}, and the variable
462 @code{ATOMICITYH} must point to this file.
464 If you are using the assembly-language approach, put this code in
465 @file{config/cpu/<chip>/atomicity.h}, where chip is the name of
466 your processor (@pxref{CPU}). No additional changes are necessary to
467 locate the file in this case; @code{ATOMICITYH} will be set by default.
469 If you are using the operating system thread-safety primitives approach,
470 you can also put this code in the same CPU directory, in which case no more
471 work is needed to locate the file. For examples of this approach,
472 see the @file{atomicity.h} file for IRIX or IA64.
474 Alternatively, if the primitives are more closely related to the OS
475 than they are to the CPU, you can put the @file{atomicity.h} file in
476 the @ref{Operating system} directory instead. In this case, you must
477 edit @file{configure.host}, and in the switch statement that handles
478 operating systems, override the @code{ATOMICITYH} variable to point to
479 the appropriate @code{os_include_dir}. For examples of this approach,
480 see the @file{atomicity.h} file for AIX.
482 With those bits out of the way, you have to actually write
483 @file{atomicity.h} itself. This file should be wrapped in an
484 include guard named @code{_GLIBCXX_ATOMICITY_H}. It should define one
485 type, and two functions.
487 The type is @code{_Atomic_word}. Here is the version used on IRIX:
490 typedef long _Atomic_word;
494 This type must be a signed integral type supporting atomic operations.
495 If you're using the OS approach, use the same type used by your system's
496 primitives. Otherwise, use the type for which your CPU provides atomic
499 Then, you must provide two functions. The bodies of these functions
500 must be equivalent to those provided here, but using atomic operations:
503 static inline _Atomic_word
504 __attribute__ ((__unused__))
505 __exchange_and_add (_Atomic_word* __mem, int __val)
507 _Atomic_word __result = *__mem;
513 __attribute__ ((__unused__))
514 __atomic_add (_Atomic_word* __mem, int __val)
520 @c ---------------------------------------------------------------------
522 @c ---------------------------------------------------------------------
525 @chapter Numeric limits
527 The C++ library requires information about the fundamental data types,
528 such as the minimum and maximum representable values of each type.
529 You can define each of these values individually, but it is usually
530 easiest just to indicate how many bits are used in each of the data
531 types and let the library do the rest. For information about the
532 macros to define, see the top of @file{include/bits/std_limits.h}.
534 If you need to define any macros, you can do so in @file{os_defines.h}.
535 However, if all operating systems for your CPU are likely to use the
536 same values, you can provide a CPU-specific file instead so that you
537 do not have to provide the same definitions for each operating system.
538 To take that approach, create a new file called @file{cpu_limits.h} in
539 your CPU configuration directory (@pxref{CPU}).
541 @c ---------------------------------------------------------------------
543 @c ---------------------------------------------------------------------
548 The C++ library is compiled, archived and linked with libtool.
549 Explaining the full workings of libtool is beyond the scope of this
550 document, but there are a few, particular bits that are necessary for
553 Some parts of the libstdc++-v3 library are compiled with the libtool
554 @code{--tags CXX} option (the C++ definitions for libtool). Therefore,
555 @file{ltcf-cxx.sh} in the top-level directory needs to have the correct
556 logic to compile and archive objects equivalent to the C version of libtool,
557 @file{ltcf-c.sh}. Some libtool targets have definitions for C but not
558 for C++, or C++ definitions which have not been kept up to date.
560 The C++ run-time library contains initialization code that needs to be
561 run as the library is loaded. Often, that requires linking in special
562 object files when the C++ library is built as a shared library, or
563 taking other system-specific actions.
565 The libstdc++-v3 library is linked with the C version of libtool, even
566 though it is a C++ library. Therefore, the C version of libtool needs to
567 ensure that the run-time library initializers are run. The usual way to
568 do this is to build the library using @code{gcc -shared}.
570 If you need to change how the library is linked, look at
571 @file{ltcf-c.sh} in the top-level directory. Find the switch statement
572 that sets @code{archive_cmds}. Here, adjust the setting for your
575 @c ---------------------------------------------------------------------
577 @c ---------------------------------------------------------------------
581 @c ---------------------------------------------------------------------
583 @c ---------------------------------------------------------------------