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 * Libtool:: Using libtool.
78 * GNU Free Documentation License:: How you can copy and share this manual.
81 @c ---------------------------------------------------------------------
83 @c ---------------------------------------------------------------------
85 @node Operating system
86 @chapter Operating system
88 If you are porting to a new operating-system (as opposed to a new chip
89 using an existing operating system), you will need to create a new
90 directory in the @file{config/os} hierarchy. For example, the IRIX
91 configuration files are all in @file{config/os/irix}. There is no set
92 way to organize the OS configuration directory. For example,
93 @file{config/os/solaris/solaris-2.6} and
94 @file{config/os/solaris/solaris-2.7} are used as configuration
95 directories for these two versions of Solaris. On the other hand, both
96 Solaris 2.7 and Solaris 2.8 use the @file{config/os/solaris/solaris-2.7}
97 directory. The important information is that there needs to be a
98 directory under @file{config/os} to store the files for your operating
101 You'll have to change the @file{configure.target} file to ensure that
102 your new directory is activated. Look for the switch statement that
103 sets @code{os_include_dir}, and add a pattern to handle your operating
104 system. The switch statement switches on only the OS portion of the
105 standard target triplet; e.g., the @code{solaris2.8} in
106 @code{sparc-sun-solaris2.8}.
108 The first file to create in this directory, should be called
109 @file{bits/os_defines.h}. This file contains basic macro definitions
110 that are required to allow the C++ library to work with your C library.
111 This file should provide macro definitions for @code{__off_t},
112 @code{__off64_t}, and @code{__ssize_t}. Typically, this just looks
116 #define __off_t off_t
117 #define __off64_t off64_t
118 #define __ssize_t ssize_t
122 You don't have to provide these definitions if your system library
123 already defines these types -- but the only library known to provide
124 these types is the GNU C Library, so you will almost certainly have to
125 provide these macros. Note that this file does not have to include a
126 header file that defines @code{off_t}, or the other types; you simply
127 have to provide the macros.
129 In addition, several libstdc++-v3 source files unconditionally define the macro
130 @code{_POSIX_SOURCE}. On many systems, defining this macro causes large
131 portions of the C library header files to be eliminated at preprocessing
132 time. Therefore, you may have to @code{#undef} this macro, or define
133 other macros (like @code{_LARGEFILE_SOURCE} or @code{__EXTENSIONS__}).
134 You won't know what macros to define or undefine at this point; you'll
135 have to try compiling the library and seeing what goes wrong. If you
136 see errors about calling functions that have not been declared, look in
137 your C library headers to see if the functions are declared there, and
138 then figure out what macros you should but in @file{bits/os_defines.h}
139 to make these declarations available.
141 Finally, you should bracket the entire file in an include-guard, like
145 #ifndef _GLIBCPP_OS_DEFINES
146 #define _GLIBCPP_OS_DEFINES
151 We recommend copying an existing @file{bits/os_defines.h} to use as a
154 @c ---------------------------------------------------------------------
156 @c ---------------------------------------------------------------------
158 @node Character types
159 @chapter Character types
161 The library requires that you provide three header files to implement
162 character classification, analagous to that provided by the C libraries
163 @file{<ctype.h>} header. You can model these on the files provided in
164 @file{config/os/generic/bits}. However, these files will almost
165 certainly need some modification.
167 The first file to write is @file{bits/ctype_base.h}. This file provides
168 some very basic information about character classification. The libstdc++-v3
169 library assumes that your C library implements @file{<ctype.h>} by using
170 a table (indexed by character code) containing integers, where each of
171 these integers is a bit-mask indicating whether the charcter is
172 upper-case, lower-case, alphabetic, etc. The @file{bits/ctype_base.h}
173 file gives the type of the integer, and the values of the various bit
174 masks. You will have to peer at your own @file{<ctype.h>} to figure out
175 how to define the values required by this file.
177 The @file{bits/ctype_base.h} header file does not need include guards.
178 It should contain a single @code{struct} definition called
179 @code{ctype_base}. This @code{struct} should contain two type
180 declarations, and one enumeration declaration, like this example, taken
181 from the IRIX configuration:
186 typedef unsigned int mask;
187 typedef int* __to_type;
207 The @code{mask} type is the type of the elements in the table. If your
208 C library uses a table to map lower-case numbers to upper-case numbers,
209 and vice versa, you should define @code{__to_type} to be the type of the
210 elements in that table. If you don't mind taking a minor performance
211 penalty, or if your library doesn't implement @code{toupper} and
212 @code{tolower} in this way, you can pick any pointer-to-integer type,
213 but you must still define the type.
215 The enumeration should give definitions for all the values in the above
216 example, using the values from your native @file{<ctype.h>}. They can
217 be given symbolically (as above), or numerically, if you prefer. You do
218 not have to include @file{<ctype.h>} in this header; it will always be
219 included before @file{bits/ctype_base.h} is included.
221 The next file to write is @file{bits/ctype_noninline.h}, which also does
222 not require include guards. This file defines a few member functions
223 that will be included in @file{include/bits/locale_facets.h}. The first
224 function that must be written is the @code{ctype<char>::ctype}
225 constructor. Here is the IRIX example:
228 ctype<char>::ctype(const mask* __table = 0, bool __del = false,
230 : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
235 ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
241 There are two parts of this that you might choose to alter. The first,
242 and most important, is the line involving @code{__libc_attr}. That is
243 IRIX system-dependent code that gets the base of the table mapping
244 character codes to attributes. You need to substitute code that obtains
245 the address of this table on your system. If you want to use your
246 operating system's tables to map upper-case letters to lower-case, and
247 vice versa, you should initialize @code{_M_toupper} and
248 @code{_M_tolower} with those tables, in similar fashion.
250 Now, you have to write two functions to convert from upper-case to
251 lower-case, and vice versa. Here are the IRIX versions:
255 ctype<char>::do_toupper(char __c) const
256 @{ return _toupper(__c); @}
259 ctype<char>::do_tolower(char __c) const
260 @{ return _tolower(__c); @}
264 Your C library provides equivalents to IRIX's @code{_toupper} and
265 @code{_tolower}. If you initialized @code{_M_toupper} and
266 @code{_M_tolower} above, then you could use those tables instead.
268 Finally, you have to provide two utility functions that convert strings
269 of characters. The versions provided here will always work -- but you
270 could use specialized routines for greater performance if you have
271 machinery to do that on your system:
275 ctype<char>::do_toupper(char* __low, const char* __high) const
277 while (__low < __high)
279 *__low = do_toupper(*__low);
286 ctype<char>::do_tolower(char* __low, const char* __high) const
288 while (__low < __high)
290 *__low = do_tolower(*__low);
297 You must also provide the @file{bits/ctype_inline.h} file, which
298 contains a few more functions. On most systems, you can just copy
299 @file{config/os/generic/ctype_inline.h} and use it on your system.
301 In detail, the functions provided test characters for particular
302 properties; they are analagous to the functions like @code{isalpha} and
303 @code{islower} provided by the C library.
305 The first function is implemented like this on IRIX:
310 is(mask __m, char __c) const throw()
311 @{ return (_M_table)[(unsigned char)(__c)] & __m; @}
315 The @code{_M_table} is the table passed in above, in the constructor.
316 This is the table that contains the bitmasks for each character. The
317 implementation here should work on all systems.
319 The next function is:
324 is(const char* __low, const char* __high, mask* __vec) const throw()
326 while (__low < __high)
327 *__vec++ = (_M_table)[(unsigned char)(*__low++)];
333 This function is similar; it copies the masks for all the characters
334 from @code{__low} up until @code{__high} into the vector given by
337 The last two functions again are entirely generic:
342 scan_is(mask __m, const char* __low, const char* __high) const throw()
344 while (__low < __high && !this->is(__m, *__low))
351 scan_not(mask __m, const char* __low, const char* __high) const throw()
353 while (__low < __high && this->is(__m, *__low))
359 @c ---------------------------------------------------------------------
361 @c ---------------------------------------------------------------------
364 @chapter Thread safety
366 The C++ library string functionality requires a couple of atomic
367 operations to provide thread-safety. If you don't take any special
368 action, the library will use stub versions of these functions that are
369 not thread-safe. They will work fine, unless your applications are
372 If you want to provide custom, safe, versions of these functions, there
373 are two distinct approaches. One is to provide a version for your CPU,
374 using assembly language constructs. The other is to use the
375 thread-safety primitives in your operating system. In either case, you
376 make a file called @file{bits/atomicity.h}.
378 If you are using the assembly-language approach, put this code in
379 @file{config/cpu/<chip>/bits/atomicity.h}, where chip is the name of
380 your processor. In that case, edit the switch statement in
381 @file{configure.target} to set the @code{cpu_include_dir}. In either
382 case, set the switch statement that sets @code{ATOMICITYH} to be the
383 directory containing @file{bits/atomicity.h}.
385 With those bits out of the way, you have to actually write
386 @file{bits/atomicity.h} itself. This file should be wrapped in an
387 include guard named @code{_BITS_ATOMICITY_H}. It should define one
388 type, and two functions.
390 The type is @code{_Atomic_word}. Here is the version used on IRIX:
393 typedef long _Atomic_word;
397 This type must be a signed integral type supporting atomic operations.
398 If you're using the OS approach, use the same type used by your system's
399 primitives. Otherwise, use the type for which your CPU provides atomic
402 Then, you must provide two functions. The bodies of these functions
403 must be equivalent to those provided here, but using atomic operations:
406 static inline _Atomic_word
407 __attribute__ ((__unused__))
408 __exchange_and_add (_Atomic_word* __mem, int __val)
410 _Atomic_word __result = *__mem;
416 __attribute__ ((__unused__))
417 __atomic_add (_Atomic_word* __mem, int __val)
423 @c ---------------------------------------------------------------------
425 @c ---------------------------------------------------------------------
430 The C++ library is compiled, archived and linked with libtool.
431 Explaining the full workings of libtool is beyond the scope of this
432 document, but there are a few, particular bits that are necessary for
435 Some parts of the libstdc++-v3 library are compiled with the libtool
436 @code{--tags CXX} option (the C++ definitions for libtool). Therefore,
437 @file{ltcf-cxx.sh} in the top-level directory needs to have the correct
438 logic to compile and archive objects equivalent to the C version of libtool,
439 @file{ltcf-c.sh}. Some libtool targets have definitions for C but not
440 for C++, or C++ definitions which have not been kept up to date.
442 The C++ run-time library contains initialization code that needs to be
443 run as the library is loaded. Often, that requires linking in special
444 object files when the C++ library is built as a shared library, or
445 taking other system-specific actions.
447 The libstdc++-v3 library is linked with the C version of libtool, even though it
448 is a C++ library. Therefore, the C version of libtool needs to ensure
449 that the run-time library initializers are run. The usual way to do
450 this is to build the library using @code{gcc -shared}.
452 If you need to change how the library is linked, look at
453 @file{ltcf-c.sh} in the top-level directory. Find the switch statement
454 that sets @code{archive_cmds}. Here, adjust the setting for your
457 @c ---------------------------------------------------------------------
459 @c ---------------------------------------------------------------------
463 @c ---------------------------------------------------------------------
465 @c ---------------------------------------------------------------------