3 @c ---------------------------------------------------------------------
5 @c ---------------------------------------------------------------------
7 @setfilename porting.info
8 @settitle Porting libstdc++-v3
12 This file explains how to port libstdc++-v3 (the GNU C++ library) to
15 Copyright (c) 2000, 2001 Free Software Foundation, Inc.
18 @c ---------------------------------------------------------------------
20 @c ---------------------------------------------------------------------
23 @title Porting libstdc++-v3
26 @vskip 0pt plus 1filll
27 Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License, Version 1.1 or
31 any later version published by the Free Software Foundation; with the
32 Invariant Sections being ``GNU General Public License'', the Front-Cover
33 texts being (a) (see below), and with the Back-Cover Texts being (b)
34 (see below). A copy of the license is included in the section entitled
35 ``GNU Free Documentation License''.
37 (a) The FSF's Front-Cover Text is:
41 (b) The FSF's Back-Cover Text is:
43 You have freedom to copy and modify this GNU Manual, like GNU
44 software. Copies published by the Free Software Foundation raise
45 funds for GNU development.
48 @c ---------------------------------------------------------------------
50 @c ---------------------------------------------------------------------
53 @top Porting libstdc++-v3
55 This document explains how to port libstdc++-v3 (the GNU C++ library) to
58 In order to make the GNU C++ library (libstdc++-v3) work with a new
59 target, you must edit some configuration files and provide some new
62 Before you get started, make sure that you have a working C library on
63 your target. The C library need not precisely comply with any
64 particular standard, but should generally conform to the requirements
65 imposed by the ANSI/ISO standard.
67 In addition, you should try to verify that the C++ compiler generally
68 works. It is difficult to test the C++ compiler without a working
69 library, but you should at least try some minimal test cases.
71 Here are the primary steps required to port the library:
74 * Operating system:: Configuring for your operating system.
75 * Character types:: Implementing character classification.
76 * Thread safety:: Implementing atomic operations.
77 * Numeric limits:: Implementing numeric limits.
78 * Libtool:: Using libtool.
79 * GNU Free Documentation License:: How you can copy and share this manual.
82 @c ---------------------------------------------------------------------
84 @c ---------------------------------------------------------------------
86 @node Operating system
87 @chapter Operating system
89 If you are porting to a new operating-system (as opposed to a new chip
90 using an existing operating system), you will need to create a new
91 directory in the @file{config/os} hierarchy. For example, the IRIX
92 configuration files are all in @file{config/os/irix}. There is no set
93 way to organize the OS configuration directory. For example,
94 @file{config/os/solaris/solaris-2.6} and
95 @file{config/os/solaris/solaris-2.7} are used as configuration
96 directories for these two versions of Solaris. On the other hand, both
97 Solaris 2.7 and Solaris 2.8 use the @file{config/os/solaris/solaris-2.7}
98 directory. The important information is that there needs to be a
99 directory under @file{config/os} to store the files for your operating
102 You'll have to change the @file{configure.target} file to ensure that
103 your new directory is activated. Look for the switch statement that
104 sets @code{os_include_dir}, and add a pattern to handle your operating
105 system. The switch statement switches on only the OS portion of the
106 standard target triplet; e.g., the @code{solaris2.8} in
107 @code{sparc-sun-solaris2.8}.
109 The first file to create in this directory, should be called
110 @file{bits/os_defines.h}. This file contains basic macro definitions
111 that are required to allow the C++ library to work with your C library.
112 This file should provide macro definitions for @code{__off_t},
113 @code{__off64_t}, and @code{__ssize_t}. Typically, this just looks
117 #define __off_t off_t
118 #define __off64_t off64_t
119 #define __ssize_t ssize_t
123 You don't have to provide these definitions if your system library
124 already defines these types -- but the only library known to provide
125 these types is the GNU C Library, so you will almost certainly have to
126 provide these macros. Note that this file does not have to include a
127 header file that defines @code{off_t}, or the other types; you simply
128 have to provide the macros.
130 In addition, several libstdc++-v3 source files unconditionally define
131 the macro @code{_POSIX_SOURCE}. On many systems, defining this macro
132 causes large portions of the C library header files to be eliminated
133 at preprocessing time. Therefore, you may have to @code{#undef} this
134 macro, or define other macros (like @code{_LARGEFILE_SOURCE} or
135 @code{__EXTENSIONS__}). You won't know what macros to define or
136 undefine at this point; you'll have to try compiling the library and
137 seeing what goes wrong. If you see errors about calling functions
138 that have not been declared, look in your C library headers to see if
139 the functions are declared there, and then figure out what macros you
140 need to define. You will need to add them to the
141 @code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for your
142 target. It will not work to simply define these macros in
145 At this time, there is one libstdc++-v3-specific macro which may be
146 defined. @code{_G_USING_THUNKS} may be defined to 0 to express that the
147 port doesn't use thunks (although it is unclear that this is still
148 useful since libio support isn't currently working and the g++ v3 ABI
149 invalidates the assumption that some ports don't use thunks).
151 Finally, you should bracket the entire file in an include-guard, like
155 #ifndef _GLIBCPP_OS_DEFINES
156 #define _GLIBCPP_OS_DEFINES
161 We recommend copying an existing @file{bits/os_defines.h} to use as a
164 @c ---------------------------------------------------------------------
166 @c ---------------------------------------------------------------------
168 @node Character types
169 @chapter Character types
171 The library requires that you provide three header files to implement
172 character classification, analogous to that provided by the C libraries
173 @file{<ctype.h>} header. You can model these on the files provided in
174 @file{config/os/generic/bits}. However, these files will almost
175 certainly need some modification.
177 The first file to write is @file{bits/ctype_base.h}. This file provides
178 some very basic information about character classification. The libstdc++-v3
179 library assumes that your C library implements @file{<ctype.h>} by using
180 a table (indexed by character code) containing integers, where each of
181 these integers is a bit-mask indicating whether the character is
182 upper-case, lower-case, alphabetic, etc. The @file{bits/ctype_base.h}
183 file gives the type of the integer, and the values of the various bit
184 masks. You will have to peer at your own @file{<ctype.h>} to figure out
185 how to define the values required by this file.
187 The @file{bits/ctype_base.h} header file does not need include guards.
188 It should contain a single @code{struct} definition called
189 @code{ctype_base}. This @code{struct} should contain two type
190 declarations, and one enumeration declaration, like this example, taken
191 from the IRIX configuration:
196 typedef unsigned int mask;
197 typedef int* __to_type;
217 The @code{mask} type is the type of the elements in the table. If your
218 C library uses a table to map lower-case numbers to upper-case numbers,
219 and vice versa, you should define @code{__to_type} to be the type of the
220 elements in that table. If you don't mind taking a minor performance
221 penalty, or if your library doesn't implement @code{toupper} and
222 @code{tolower} in this way, you can pick any pointer-to-integer type,
223 but you must still define the type.
225 The enumeration should give definitions for all the values in the above
226 example, using the values from your native @file{<ctype.h>}. They can
227 be given symbolically (as above), or numerically, if you prefer. You do
228 not have to include @file{<ctype.h>} in this header; it will always be
229 included before @file{bits/ctype_base.h} is included.
231 The next file to write is @file{bits/ctype_noninline.h}, which also does
232 not require include guards. This file defines a few member functions
233 that will be included in @file{include/bits/locale_facets.h}. The first
234 function that must be written is the @code{ctype<char>::ctype}
235 constructor. Here is the IRIX example:
238 ctype<char>::ctype(const mask* __table = 0, bool __del = false,
240 : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
245 ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
251 There are two parts of this that you might choose to alter. The first,
252 and most important, is the line involving @code{__libc_attr}. That is
253 IRIX system-dependent code that gets the base of the table mapping
254 character codes to attributes. You need to substitute code that obtains
255 the address of this table on your system. If you want to use your
256 operating system's tables to map upper-case letters to lower-case, and
257 vice versa, you should initialize @code{_M_toupper} and
258 @code{_M_tolower} with those tables, in similar fashion.
260 Now, you have to write two functions to convert from upper-case to
261 lower-case, and vice versa. Here are the IRIX versions:
265 ctype<char>::do_toupper(char __c) const
266 @{ return _toupper(__c); @}
269 ctype<char>::do_tolower(char __c) const
270 @{ return _tolower(__c); @}
274 Your C library provides equivalents to IRIX's @code{_toupper} and
275 @code{_tolower}. If you initialized @code{_M_toupper} and
276 @code{_M_tolower} above, then you could use those tables instead.
278 Finally, you have to provide two utility functions that convert strings
279 of characters. The versions provided here will always work -- but you
280 could use specialized routines for greater performance if you have
281 machinery to do that on your system:
285 ctype<char>::do_toupper(char* __low, const char* __high) const
287 while (__low < __high)
289 *__low = do_toupper(*__low);
296 ctype<char>::do_tolower(char* __low, const char* __high) const
298 while (__low < __high)
300 *__low = do_tolower(*__low);
307 You must also provide the @file{bits/ctype_inline.h} file, which
308 contains a few more functions. On most systems, you can just copy
309 @file{config/os/generic/ctype_inline.h} and use it on your system.
311 In detail, the functions provided test characters for particular
312 properties; they are analogous to the functions like @code{isalpha} and
313 @code{islower} provided by the C library.
315 The first function is implemented like this on IRIX:
320 is(mask __m, char __c) const throw()
321 @{ return (_M_table)[(unsigned char)(__c)] & __m; @}
325 The @code{_M_table} is the table passed in above, in the constructor.
326 This is the table that contains the bitmasks for each character. The
327 implementation here should work on all systems.
329 The next function is:
334 is(const char* __low, const char* __high, mask* __vec) const throw()
336 while (__low < __high)
337 *__vec++ = (_M_table)[(unsigned char)(*__low++)];
343 This function is similar; it copies the masks for all the characters
344 from @code{__low} up until @code{__high} into the vector given by
347 The last two functions again are entirely generic:
352 scan_is(mask __m, const char* __low, const char* __high) const throw()
354 while (__low < __high && !this->is(__m, *__low))
361 scan_not(mask __m, const char* __low, const char* __high) const throw()
363 while (__low < __high && this->is(__m, *__low))
369 @c ---------------------------------------------------------------------
371 @c ---------------------------------------------------------------------
374 @chapter Thread safety
376 The C++ library string functionality requires a couple of atomic
377 operations to provide thread-safety. If you don't take any special
378 action, the library will use stub versions of these functions that are
379 not thread-safe. They will work fine, unless your applications are
382 If you want to provide custom, safe, versions of these functions, there
383 are two distinct approaches. One is to provide a version for your CPU,
384 using assembly language constructs. The other is to use the
385 thread-safety primitives in your operating system. In either case, you
386 make a file called @file{bits/atomicity.h}.
388 If you are using the assembly-language approach, put this code in
389 @file{config/cpu/<chip>/bits/atomicity.h}, where chip is the name of
390 your processor. In that case, edit the switch statement in
391 @file{configure.target} to set the @code{cpu_include_dir}. In either
392 case, set the switch statement that sets @code{ATOMICITYH} to be the
393 directory containing @file{bits/atomicity.h}.
395 With those bits out of the way, you have to actually write
396 @file{bits/atomicity.h} itself. This file should be wrapped in an
397 include guard named @code{_BITS_ATOMICITY_H}. It should define one
398 type, and two functions.
400 The type is @code{_Atomic_word}. Here is the version used on IRIX:
403 typedef long _Atomic_word;
407 This type must be a signed integral type supporting atomic operations.
408 If you're using the OS approach, use the same type used by your system's
409 primitives. Otherwise, use the type for which your CPU provides atomic
412 Then, you must provide two functions. The bodies of these functions
413 must be equivalent to those provided here, but using atomic operations:
416 static inline _Atomic_word
417 __attribute__ ((__unused__))
418 __exchange_and_add (_Atomic_word* __mem, int __val)
420 _Atomic_word __result = *__mem;
426 __attribute__ ((__unused__))
427 __atomic_add (_Atomic_word* __mem, int __val)
433 @c ---------------------------------------------------------------------
435 @c ---------------------------------------------------------------------
438 @chapter Numeric limits
440 The C++ library requires information about the fundamental data types,
441 such as the minimum and maximum representable values of each type.
442 You can define each of these values individually, but it is usually
443 easiest just to indicate how many bits are used in each of the data
444 types and let the library do the rest. For information about the
445 macros to define, see the top of @file{include/bits/std_limits.h}.
447 If you need to define any macros, you can do so in
448 @file{os_defines.h}. However, if all operating systems for your CPU
449 are likely to use the same values, you can provide a CPU-specific file
450 instead so that you do not have to provide the same definitions for
451 each operating system. To take that approach, create a new file
452 called @file{limits.h} in your CPU configuration directory (e.g.,
453 @file{config/cpu/i386/bits}) and then modify @file{configure.target}
454 so that @code{LIMITSH} is set to the CPU directory (e.g.,
455 @file{config/cpu/i386}). Note that @code{LIMITSH} should not include
456 the @samp{bits} part of the directory name.
458 @c ---------------------------------------------------------------------
460 @c ---------------------------------------------------------------------
465 The C++ library is compiled, archived and linked with libtool.
466 Explaining the full workings of libtool is beyond the scope of this
467 document, but there are a few, particular bits that are necessary for
470 Some parts of the libstdc++-v3 library are compiled with the libtool
471 @code{--tags CXX} option (the C++ definitions for libtool). Therefore,
472 @file{ltcf-cxx.sh} in the top-level directory needs to have the correct
473 logic to compile and archive objects equivalent to the C version of libtool,
474 @file{ltcf-c.sh}. Some libtool targets have definitions for C but not
475 for C++, or C++ definitions which have not been kept up to date.
477 The C++ run-time library contains initialization code that needs to be
478 run as the library is loaded. Often, that requires linking in special
479 object files when the C++ library is built as a shared library, or
480 taking other system-specific actions.
482 The libstdc++-v3 library is linked with the C version of libtool, even though it
483 is a C++ library. Therefore, the C version of libtool needs to ensure
484 that the run-time library initializers are run. The usual way to do
485 this is to build the library using @code{gcc -shared}.
487 If you need to change how the library is linked, look at
488 @file{ltcf-c.sh} in the top-level directory. Find the switch statement
489 that sets @code{archive_cmds}. Here, adjust the setting for your
492 @c ---------------------------------------------------------------------
494 @c ---------------------------------------------------------------------
498 @c ---------------------------------------------------------------------
500 @c ---------------------------------------------------------------------