1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4 % Author: Mark Mitchell
9 % Copyright (c) 2000 by Free Software Foundation, Inc.
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 @c ---------------------------------------------------------------------
17 @c ---------------------------------------------------------------------
19 @setfilename porting.info
20 @settitle Porting libstdc++-v3
21 @setchapternewpage odd
24 This file explains how to port libstdc++-v3 (the GNU C++ library) to
27 Copyright (c) 2000 Free Software Foundation, Inc.
30 @c ---------------------------------------------------------------------
32 @c ---------------------------------------------------------------------
35 @title Porting libstdc++-v3
38 @vskip 0pt plus 1filll
39 Copyright @copyright{} 2000 Free Software Foundation, Inc.
42 @c ---------------------------------------------------------------------
44 @c ---------------------------------------------------------------------
47 @top Porting libstdc++-v3
49 This document explains how to port libstdc++-v3 (the GNU C++ library) to
52 In order to make the GNU C++ library (libstdc++-v3) work with a new
53 target, you must edit some configuration files and provide some new
56 Before you get started, make sure that you have a working C library on
57 your target. The C library need not precisely comply with any
58 particular standard, but should generally conform to the requirements
59 imposed by the ANSI/ISO standard.
61 In addition, you should try to verify that the C++ compiler generally
62 works. It is difficult to test the C++ compiler without a working
63 library, but you should at least try some minimal test cases.
65 Here are the primary steps required to port the library:
68 * Operating system:: Configuring for your operating system.
69 * Character types:: Implementing character classification.
70 * Thread safety:: Implementing atomic operations.
71 * Libtool:: Using libtool.
74 @c ---------------------------------------------------------------------
76 @c ---------------------------------------------------------------------
78 @node Operating system
79 @chapter Operating system
81 If you are porting to a new operating-system (as opposed to a new chip
82 using an existing operating system), you will need to create a new
83 directory in the @file{config/os} hierarchy. For example, the IRIX
84 configuration files are all in @file{config/os/irix}. There is no set
85 way to organize the OS configuration directory. For example,
86 @file{config/os/solaris/solaris-2.6} and
87 @file{config/os/solaris/solaris-2.7} are used as configuration
88 directories for these two versions of Solaris. On the other hand, both
89 Solaris 2.7 and Solaris 2.8 use the @file{config/os/solaris/solaris-2.7}
90 directory. The important information is that there needs to be a
91 directory under @file{config/os} to store the files for your operating
94 You'll have to change the @file{configure.target} file to ensure that
95 your new directory is activated. Look for the switch statement that
96 sets @code{os_include_dir}, and add a pattern to handle your operating
97 system. The switch statement switches on only the OS portion of the
98 standard target triplet; e.g., the @code{solaris2.8} in
99 @code{sparc-sun-solaris2.8}.
101 The first file to create in this directory, should be called
102 @file{bits/os_defines.h}. This file contains basic macro definitions
103 that are required to allow the C++ library to work with your C library.
104 This file should provide macro definitions for @code{__off_t},
105 @code{__off64_t}, and @code{__ssize_t}. Typically, this just looks
109 #define __off_t off_t
110 #define __off64_t off64_t
111 #define __ssize_t ssize_t
115 You don't have to provide these definitions if your system library
116 already defines these types -- but the only library known to provide
117 these types is the GNU C Library, so you will almost certainly have to
118 provide these macros. Note that this file does not have to include a
119 header file that defines @code{off_t}, or the other types; you simply
120 have to provide the macros.
122 In addition, several libstdc++-v3 source files unconditionally define the macro
123 @code{_POSIX_SOURCE}. On many systems, defining this macro causes large
124 portions of the C library header files to be eliminated at preprocessing
125 time. Therefore, you may have to @code{#undef} this macro, or define
126 other macros (like @code{_LARGEFILE_SOURCE} or @code{__EXTENSIONS__}).
127 You won't know what macros to define or undefine at this point; you'll
128 have to try compiling the library and seeing what goes wrong. If you
129 see errors about calling functions that have not been declared, look in
130 your C library headers to see if the functions are declared there, and
131 then figure out what macros you should but in @file{bits/os_defines.h}
132 to make these declarations available.
134 Finally, you should bracket the entire file in an include-guard, like
138 #ifndef _GLIBCPP_OS_DEFINES
139 #define _GLIBCPP_OS_DEFINES
144 We recommend copying an existing @file{bits/os_defines.h} to use as a
147 @c ---------------------------------------------------------------------
149 @c ---------------------------------------------------------------------
151 @node Character types
152 @chapter Character types
154 The library requires that you provide three header files to implement
155 character classification, analagous to that provided by the C libraries
156 @file{<ctype.h>} header. You can model these on the files provided in
157 @file{config/os/generic/bits}. However, these files will almost
158 certainly need some modification.
160 The first file to write is @file{bits/ctype_base.h}. This file provides
161 some very basic information about character classification. The libstdc++-v3
162 library assumes that your C library implements @file{<ctype.h>} by using
163 a table (indexed by character code) containing integers, where each of
164 these integers is a bit-mask indicating whether the charcter is
165 upper-case, lower-case, alphabetic, etc. The @file{bits/ctype_base.h}
166 file gives the type of the integer, and the values of the various bit
167 masks. You will have to peer at your own @file{<ctype.h>} to figure out
168 how to define the values required by this file.
170 The @file{bits/ctype_base.h} header file does not need include guards.
171 It should contain a single @code{struct} definition called
172 @code{ctype_base}. This @code{struct} should contain two type
173 declarations, and one enumeration declaration, like this example, taken
174 from the IRIX configuration:
179 typedef unsigned int mask;
180 typedef int* __to_type;
200 The @code{mask} type is the type of the elements in the table. If your
201 C library uses a table to map lower-case numbers to upper-case numbers,
202 and vice versa, you should define @code{__to_type} to be the type of the
203 elements in that table. If you don't mind taking a minor performance
204 penalty, or if your library doesn't implement @code{toupper} and
205 @code{tolower} in this way, you can pick any pointer-to-integer type,
206 but you must still define the type.
208 The enumeration should give definitions for all the values in the above
209 example, using the values from your native @file{<ctype.h>}. They can
210 be given symbolically (as above), or numerically, if you prefer. You do
211 not have to include @file{<ctype.h>} in this header; it will always be
212 included before @file{bits/ctype_base.h} is included.
214 The next file to write is @file{bits/ctype_noninline.h}, which also does
215 not require include guards. This file defines a few member functions
216 that will be included in @file{include/bits/locale_facets.h}. The first
217 function that must be written is the @code{ctype<char>::ctype}
218 constructor. Here is the IRIX example:
221 ctype<char>::ctype(const mask* __table = 0, bool __del = false,
223 : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
228 ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
234 There are two parts of this that you might choose to alter. The first,
235 and most important, is the line involving @code{__libc_attr}. That is
236 IRIX system-dependent code that gets the base of the table mapping
237 character codes to attributes. You need to substitute code that obtains
238 the address of this table on your system. If you want to use your
239 operating system's tables to map upper-case letters to lower-case, and
240 vice versa, you should initialize @code{_M_toupper} and
241 @code{_M_tolower} with those tables, in similar fashion.
243 Now, you have to write two functions to convert from upper-case to
244 lower-case, and vice versa. Here are the IRIX versions:
248 ctype<char>::do_toupper(char __c) const
249 @{ return _toupper(__c); @}
252 ctype<char>::do_tolower(char __c) const
253 @{ return _tolower(__c); @}
257 Your C library provides equivalents to IRIX's @code{_toupper} and
258 @code{_tolower}. If you initialized @code{_M_toupper} and
259 @code{_M_tolower} above, then you could use those tables instead.
261 Finally, you have to provide two utility functions that convert strings
262 of characters. The versions provided here will always work -- but you
263 could use specialized routines for greater performance if you have
264 machinery to do that on your system:
268 ctype<char>::do_toupper(char* __low, const char* __high) const
270 while (__low < __high)
272 *__low = do_toupper(*__low);
279 ctype<char>::do_tolower(char* __low, const char* __high) const
281 while (__low < __high)
283 *__low = do_tolower(*__low);
290 You must also provide the @file{bits/ctype_inline.h} file, which
291 contains a few more functions. On most systems, you can just copy
292 @file{config/os/generic/ctype_inline.h} and use it on your system.
294 In detail, the functions provided test characters for particular
295 properties; they are analagous to the functions like @code{isalpha} and
296 @code{islower} provided by the C library.
298 The first function is implemented like this on IRIX:
303 is(mask __m, char __c) const throw()
304 @{ return (_M_table)[(unsigned char)(__c)] & __m; @}
308 The @code{_M_table} is the table passed in above, in the constructor.
309 This is the table that contains the bitmasks for each character. The
310 implementation here should work on all systems.
312 The next function is:
317 is(const char* __low, const char* __high, mask* __vec) const throw()
319 while (__low < __high)
320 *__vec++ = (_M_table)[(unsigned char)(*__low++)];
326 This function is similar; it copies the masks for all the characters
327 from @code{__low} up until @code{__high} into the vector given by
330 The last two functions again are entirely generic:
335 scan_is(mask __m, const char* __low, const char* __high) const throw()
337 while (__low < __high && !this->is(__m, *__low))
344 scan_not(mask __m, const char* __low, const char* __high) const throw()
346 while (__low < __high && this->is(__m, *__low))
352 @c ---------------------------------------------------------------------
354 @c ---------------------------------------------------------------------
357 @chapter Thread safety
359 The C++ library string functionality requires a couple of atomic
360 operations to provide thread-safety. If you don't take any special
361 action, the library will use stub versions of these functions that are
362 not thread-safe. They will work fine, unless your applications are
365 If you want to provide custom, safe, versions of these functions, there
366 are two distinct approaches. One is to provide a version for your CPU,
367 using assembly language constructs. The other is to use the
368 thread-safety primitives in your operating system. In either case, you
369 make a file called @file{bits/atomicity.h}.
371 If you are using the assembly-language approach, put this code in
372 @file{config/cpu/<chip>/bits/atomicity.h}, where chip is the name of
373 your processor. In that case, edit the switch statement in
374 @file{configure.target} to set the @code{cpu_include_dir}. In either
375 case, set the switch statement that sets @code{ATOMICITYH} to be the
376 directory containing @file{bits/atomicity.h}.
378 With those bits out of the way, you have to actually write
379 @file{bits/atomicity.h} itself. This file should be wrapped in an
380 include guard named @code{_BITS_ATOMICITY_H}. It should define one
381 type, and two functions.
383 The type is @code{_Atomic_word}. Here is the version used on IRIX:
386 typedef long _Atomic_word;
390 This type must be a signed integral type supporting atomic operations.
391 If you're using the OS approach, use the same type used by your system's
392 primitives. Otherwise, use the type for which your CPU provides atomic
395 Then, you must provide two functions. The bodies of these functions
396 must be equivalent to those provided here, but using atomic operations:
399 static inline _Atomic_word
400 __attribute__ ((__unused__))
401 __exchange_and_add (_Atomic_word* __mem, int __val)
403 _Atomic_word __result = *__mem;
409 __attribute__ ((__unused__))
410 __atomic_add (_Atomic_word* __mem, int __val)
416 @c ---------------------------------------------------------------------
418 @c ---------------------------------------------------------------------
423 The C++ library is compiled, archived and linked with libtool.
424 Explaining the full workings of libtool is beyond the scope of this
425 document, but there are a few, particular bits that are necessary for
428 Some parts of the libstdc++-v3 library are compiled with the libtool
429 @code{--tags CXX} option (the C++ definitions for libtool). Therefore,
430 @file{ltcf-cxx.sh} in the top-level directory needs to have the correct
431 logic to compile and archive objects equivalent to the C version of libtool,
432 @file{ltcf-c.sh}. Some libtool targets have definitions for C but not
433 for C++, or C++ definitions which have not been kept up to date.
435 The C++ run-time library contains initialization code that needs to be
436 run as the library is loaded. Often, that requires linking in special
437 object files when the C++ library is built as a shared library, or
438 taking other system-specific actions.
440 The libstdc++-v3 library is linked with the C version of libtool, even though it
441 is a C++ library. Therefore, the C version of libtool needs to ensure
442 that the run-time library initializers are run. The usual way to do
443 this is to build the library using @code{gcc -shared}.
445 If you need to change how the library is linked, look at
446 @file{ltcf-c.sh} in the top-level directory. Find the switch statement
447 that sets @code{archive_cmds}. Here, adjust the setting for your
450 @c ---------------------------------------------------------------------
452 @c ---------------------------------------------------------------------