From: Phil Edwards Date: Tue, 6 Nov 2001 00:18:37 +0000 (+0000) Subject: porting.texi: Move... X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=eb6e2e5bef83996cf65d1e6285665b9598847880;p=gcc.git porting.texi: Move... 2001-11-05 Phil Edwards * porting.texi: Move... * docs/html/17_intro/porting.texi: ...to here. * docs/html/Makefile: Add rule to rebuild... * docs/html/17_intro/porting.html: ...this. New file. From-SVN: r46797 --- diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 0b420002bb6..293b1315ec1 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,10 @@ +2001-11-05 Phil Edwards + + * porting.texi: Move... + * docs/html/17_intro/porting.texi: ...to here. + * docs/html/Makefile: Add rule to rebuild... + * docs/html/17_intro/porting.html: ...this. New file. + 2001-11-05 Felix Natter * docs/html/17_intro/porting-howto.xml: check in v0.9.4 diff --git a/libstdc++-v3/docs/html/17_intro/porting.html b/libstdc++-v3/docs/html/17_intro/porting.html new file mode 100644 index 00000000000..b51fa9cdcb5 --- /dev/null +++ b/libstdc++-v3/docs/html/17_intro/porting.html @@ -0,0 +1,841 @@ + + +Porting libstdc++-v3 + + + + + + + +

+Node:Top, +Next: +
+ +

Porting libstdc++-v3

+ +

This 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 new +target, you must edit some configuration files and provide some new +header files. + +

Before you get started, make sure that you have a working C library on +your target. The C library need not precisely comply with any +particular standard, but should generally conform to the requirements +imposed by the ANSI/ISO standard. + +

In addition, you should try to verify that the C++ compiler generally +works. It is difficult to test the C++ compiler without a working +library, but you should at least try some minimal test cases. + +

Here are the primary steps required to port the library: + +

+ +

+Node:Operating system, +Next:, +Previous:Top, +Up:Top +
+ +

Operating system

+ +

If you are porting to a new operating-system (as opposed to a new chip +using an existing operating system), you will need to create a new +directory in the config/os hierarchy. For example, the IRIX +configuration files are all in config/os/irix. There is no set +way to organize the OS configuration directory. For example, +config/os/solaris/solaris-2.6 and +config/os/solaris/solaris-2.7 are used as configuration +directories for these two versions of Solaris. On the other hand, both +Solaris 2.7 and Solaris 2.8 use the config/os/solaris/solaris-2.7 +directory. The important information is that there needs to be a +directory under config/os to store the files for your operating +system. + +

You'll have to change the configure.target file to ensure that +your new directory is activated. Look for the switch statement that +sets os_include_dir, and add a pattern to handle your operating +system. The switch statement switches on only the OS portion of the +standard target triplet; e.g., the solaris2.8 in +sparc-sun-solaris2.8. + +

The first file to create in this directory, should be called +bits/os_defines.h. This file contains basic macro definitions +that are required to allow the C++ library to work with your C library. +This file should provide macro definitions for __off_t, +__off64_t, and __ssize_t. Typically, this just looks +like: + +

#define __off_t off_t
+#define __off64_t off64_t
+#define __ssize_t ssize_t
+
+ +

You don't have to provide these definitions if your system library +already defines these types - but the only library known to provide +these types is the GNU C Library, so you will almost certainly have to +provide these macros. Note that this file does not have to include a +header file that defines off_t, or the other types; you simply +have to provide the macros. + +

In addition, several libstdc++-v3 source files unconditionally define +the macro _POSIX_SOURCE. On many systems, defining this macro +causes large portions of the C library header files to be eliminated +at preprocessing time. Therefore, you may have to #undef this +macro, or define other macros (like _LARGEFILE_SOURCE or +__EXTENSIONS__). You won't know what macros to define or +undefine at this point; you'll have to try compiling the library and +seeing what goes wrong. If you see errors about calling functions +that have not been declared, look in your C library headers to see if +the functions are declared there, and then figure out what macros you +need to define. You will need to add them to the +CPLUSPLUS_CPP_SPEC macro in the GCC configuration file for your +target. It will not work to simply define these macros in +os_defines.h. + +

At this time, there are two libstdc++-v3-specific macros which may be +defined. _G_USING_THUNKS may be defined to 0 to express that the +port doesn't use thunks (although it is unclear that this is still +useful since libio support isn't currently working and the g++ v3 ABI +invalidates the assumption that some ports don't use thunks). +_GLIBCPP_AVOID_FSEEK may be defined if seeking on an interactive +stream (or one hooked to a pipe) is not allowed by the OS. In this +case, getc()/ungetc() will be used at some key locations in the library +implementation instead of fseek(). Currently, the code path to avoid +fseek() is only enabled when the seek size is 1 character away from the +current stream position. This is known to improve *-unknown-freebsd* +and sparc-sun-solaris2.*. + +

Finally, you should bracket the entire file in an include-guard, like +this: + +

#ifndef _GLIBCPP_OS_DEFINES
+#define _GLIBCPP_OS_DEFINES
+...
+#endif
+
+ +

We recommend copying an existing bits/os_defines.h to use as a +starting point. + +

+Node:Character types, +Next:, +Previous:Operating system, +Up:Top +
+ +

Character types

+ +

The library requires that you provide three header files to implement +character classification, analagous to that provided by the C libraries +<ctype.h> header. You can model these on the files provided in +config/os/generic/bits. However, these files will almost +certainly need some modification. + +

The first file to write is bits/ctype_base.h. This file provides +some very basic information about character classification. The libstdc++-v3 +library assumes that your C library implements <ctype.h> by using +a table (indexed by character code) containing integers, where each of +these integers is a bit-mask indicating whether the charcter is +upper-case, lower-case, alphabetic, etc. The bits/ctype_base.h +file gives the type of the integer, and the values of the various bit +masks. You will have to peer at your own <ctype.h> to figure out +how to define the values required by this file. + +

The bits/ctype_base.h header file does not need include guards. +It should contain a single struct definition called +ctype_base. This struct should contain two type +declarations, and one enumeration declaration, like this example, taken +from the IRIX configuration: + +

struct 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
+  };
+};
+
+ +

The mask type is the type of the elements in the table. If your +C library uses a table to map lower-case numbers to upper-case numbers, +and vice versa, you should define __to_type to be the type of the +elements in that table. If you don't mind taking a minor performance +penalty, or if your library doesn't implement toupper and +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 above +example, using the values from your native <ctype.h>. They can +be given symbolically (as above), or numerically, if you prefer. You do +not have to include <ctype.h> in this header; it will always be +included before bits/ctype_base.h is included. + +

The next file to write is bits/ctype_noninline.h, which also does +not require include guards. This file defines a few member functions +that will be included in include/bits/locale_facets.h. The first +function that must be written is the ctype<char>::ctype +constructor. Here is the IRIX example: + +

ctype<char>::ctype(const mask* __table = 0, bool __del = false,
+      size_t __refs = 0)
+  : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
+    _M_toupper(NULL),
+    _M_tolower(NULL),
+    _M_ctable(NULL),
+    _M_table(!__table
+             ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
+             : __table)
+  { }
+
+ +

There are two parts of this that you might choose to alter. The first, +and most important, is the line involving __libc_attr. That is +IRIX system-dependent code that gets the base of the table mapping +character codes to attributes. You need to substitute code that obtains +the address of this table on your system. If you want to use your +operating system's tables to map upper-case letters to lower-case, and +vice versa, you should initialize _M_toupper and +_M_tolower with those tables, in similar fashion. + +

Now, you have to write two functions to convert from upper-case to +lower-case, and vice versa. Here are the IRIX versions: + +

char
+ctype<char>::do_toupper(char __c) const
+{ return _toupper(__c); }
+
+char
+ctype<char>::do_tolower(char __c) const
+{ return _tolower(__c); }
+
+ +

Your C library provides equivalents to IRIX's _toupper and +_tolower. If you initialized _M_toupper and +_M_tolower above, then you could use those tables instead. + +

Finally, you have to provide two utility functions that convert strings +of characters. The versions provided here will always work - but you +could use specialized routines for greater performance if you have +machinery to do that on your system: + +

const char*
+ctype<char>::do_toupper(char* __low, const char* __high) const
+{
+  while (__low < __high)
+    {
+      *__low = do_toupper(*__low);
+      ++__low;
+    }
+  return __high;
+}
+
+const char*
+ctype<char>::do_tolower(char* __low, const char* __high) const
+{
+  while (__low < __high)
+    {
+      *__low = do_tolower(*__low);
+      ++__low;
+    }
+  return __high;
+}
+
+ +

You must also provide the bits/ctype_inline.h file, which +contains a few more functions. On most systems, you can just copy +config/os/generic/ctype_inline.h and use it on your system. + +

In detail, the functions provided test characters for particular +properties; they are analagous to the functions like isalpha and +islower provided by the C library. + +

The first function is implemented like this on IRIX: + +

bool
+ctype<char>::
+is(mask __m, char __c) const throw()
+{ return (_M_table)[(unsigned char)(__c)] & __m; }
+
+ +

The _M_table is the table passed in above, in the constructor. +This is the table that contains the bitmasks for each character. The +implementation here should work on all systems. + +

The next function is: + +

const char*
+ctype<char>::
+is(const char* __low, const char* __high, mask* __vec) const throw()
+{
+  while (__low < __high)
+    *__vec++ = (_M_table)[(unsigned char)(*__low++)];
+  return __high;
+}
+
+ +

This function is similar; it copies the masks for all the characters +from __low up until __high into the vector given by +__vec. + +

The last two functions again are entirely generic: + +

const char*
+ctype<char>::
+scan_is(mask __m, const char* __low, const char* __high) const throw()
+{
+  while (__low < __high && !this->is(__m, *__low))
+    ++__low;
+  return __low;
+}
+
+const char*
+ctype<char>::
+scan_not(mask __m, const char* __low, const char* __high) const throw()
+{
+  while (__low < __high && this->is(__m, *__low))
+    ++__low;
+  return __low;
+}
+
+ +

+Node:Thread safety, +Next:, +Previous:Character types, +Up:Top +
+ +

Thread safety

+ +

The C++ library string functionality requires a couple of atomic +operations to provide thread-safety. If you don't take any special +action, the library will use stub versions of these functions that are +not thread-safe. They will work fine, unless your applications are +multi-threaded. + +

If you want to provide custom, safe, versions of these functions, there +are two distinct approaches. One is to provide a version for your CPU, +using assembly language constructs. The other is to use the +thread-safety primitives in your operating system. In either case, you +make a file called bits/atomicity.h. + +

If you are using the assembly-language approach, put this code in +config/cpu/<chip>/bits/atomicity.h, where chip is the name of +your processor. In that case, edit the switch statement in +configure.target to set the cpu_include_dir. In either +case, set the switch statement that sets ATOMICITYH to be the +directory containing bits/atomicity.h. + +

With those bits out of the way, you have to actually write +bits/atomicity.h itself. This file should be wrapped in an +include guard named _BITS_ATOMICITY_H. It should define one +type, and two functions. + +

The type is _Atomic_word. Here is the version used on IRIX: + +

typedef long _Atomic_word;
+
+ +

This type must be a signed integral type supporting atomic operations. +If you're using the OS approach, use the same type used by your system's +primitives. Otherwise, use the type for which your CPU provides atomic +primitives. + +

Then, you must provide two functions. The bodies of these functions +must be equivalent to those provided here, but using atomic operations: + +

static inline _Atomic_word
+__attribute__ ((__unused__))
+__exchange_and_add (_Atomic_word* __mem, int __val)
+{
+  _Atomic_word __result = *__mem;
+  *__mem += __val;
+  return __result;
+}
+
+static inline void
+__attribute__ ((__unused__))
+__atomic_add (_Atomic_word* __mem, int __val)
+{
+  *__mem += __val;
+}
+
+ +

+Node:Numeric limits, +Next:, +Previous:Thread safety, +Up:Top +
+ +

Numeric limits

+ +

The C++ library requires information about the fundamental data types, +such as the minimum and maximum representable values of each type. +You can define each of these values individually, but it is usually +easiest just to indicate how many bits are used in each of the data +types and let the library do the rest. For information about the +macros to define, see the top of include/bits/std_limits.h. + +

If you need to define any macros, you can do so in +os_defines.h. However, if all operating systems for your CPU +are likely to use the same values, you can provide a CPU-specific file +instead so that you do not have to provide the same definitions for +each operating system. To take that approach, create a new file +called limits.h in your CPU configuration directory (e.g., +config/cpu/i386/bits) and then modify configure.target +so that LIMITSH is set to the CPU directory (e.g., +config/cpu/i386). Note that LIMITSH should not include +the bits part of the directory name. + +

+Node:Libtool, +Next:, +Previous:Numeric limits, +Up:Top +
+ +

Libtool

+ +

The C++ library is compiled, archived and linked with libtool. +Explaining the full workings of libtool is beyond the scope of this +document, but there are a few, particular bits that are necessary for +porting. + +

Some parts of the libstdc++-v3 library are compiled with the libtool +--tags CXX option (the C++ definitions for libtool). Therefore, +ltcf-cxx.sh in the top-level directory needs to have the correct +logic to compile and archive objects equivalent to the C version of libtool, +ltcf-c.sh. Some libtool targets have definitions for C but not +for C++, or C++ definitions which have not been kept up to date. + +

The C++ run-time library contains initialization code that needs to be +run as the library is loaded. Often, that requires linking in special +object files when the C++ library is built as a shared library, or +taking other system-specific actions. + +

The libstdc++-v3 library is linked with the C version of libtool, even though it +is a C++ library. Therefore, the C version of libtool needs to ensure +that the run-time library initializers are run. The usual way to do +this is to build the library using gcc -shared. + +

If you need to change how the library is linked, look at +ltcf-c.sh in the top-level directory. Find the switch statement +that sets archive_cmds. Here, adjust the setting for your +operating system. + +

+Node:GNU Free Documentation License, +Previous:Libtool, +Up:Top +
+ +

GNU Free Documentation License

+ +
Version 1.1, March 2000
+
Copyright © 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+ +
    +

  1. PREAMBLE + +

    The purpose of this License is to make a manual, textbook, or other +written document free in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +

    This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +

    We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +

  2. APPLICABILITY AND DEFINITIONS + +

    This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +

    A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +

    A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +

    The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +

    The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +

    A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +

    Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, +SGML or XML using a publicly available +DTD, and standard-conforming simple HTML designed +for human modification. Opaque formats include PostScript, +PDF, proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which +the DTD and/or processing tools are not generally available, +and the machine-generated HTML produced by some word +processors for output purposes only. + +

    The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +

  3. VERBATIM COPYING + +

    You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +

    You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +

  4. COPYING IN QUANTITY + +

    If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +

    If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +

    If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +

    It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +

  5. MODIFICATIONS + +

    You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +

      +

    1. Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +
    2. List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has less than five). + +
    3. State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +
    4. Preserve all the copyright notices of the Document. + +
    5. Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +
    6. Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +
    7. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +
    8. Include an unaltered copy of this License. + +
    9. Preserve the section entitled "History", and its title, and add to +it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section entitled "History" in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +
    10. Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the "History" section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +
    11. In any section entitled "Acknowledgments" or "Dedications", +preserve the section's title, and preserve in the section all the +substance and tone of each of the contributor acknowledgments +and/or dedications given therein. + +
    12. Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +
    13. Delete any section entitled "Endorsements". Such a section +may not be included in the Modified Version. + +
    14. Do not retitle any existing section as "Endorsements" +or to conflict in title with any Invariant Section. +
    + +

    If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +

    You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +

    You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +

    The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +

  6. COMBINING DOCUMENTS + +

    You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +

    The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +

    In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgments", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + +

  7. COLLECTIONS OF DOCUMENTS + +

    You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +

    You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +

  8. AGGREGATION WITH INDEPENDENT WORKS + +

    A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +

    If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + +

  9. TRANSLATION + +

    Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + +

  10. TERMINATION + +

    You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +

  11. FUTURE REVISIONS OF THIS LICENSE + +

    The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +

    Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +

+ +

ADDENDUM: How to use this License for your documents

+ +

To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +

  Copyright (C)  year  your name.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.1
+  or any later version published by the Free Software Foundation;
+  with the Invariant Sections being list their titles, with the
+  Front-Cover Texts being list, and with the Back-Cover Texts being list.
+  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+
+ +

If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being list"; likewise for Back-Cover Texts. + +

If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + + +

Table of Contents

+ + + + diff --git a/libstdc++-v3/docs/html/17_intro/porting.texi b/libstdc++-v3/docs/html/17_intro/porting.texi new file mode 100644 index 00000000000..9114806b63f --- /dev/null +++ b/libstdc++-v3/docs/html/17_intro/porting.texi @@ -0,0 +1,510 @@ +\input texinfo + +@c --------------------------------------------------------------------- +@c Prologue +@c --------------------------------------------------------------------- + +@setfilename porting.info +@settitle Porting libstdc++-v3 +@setchapternewpage odd + +@ifinfo +This file explains how to port libstdc++-v3 (the GNU C++ library) to +a new target. + +Copyright (c) 2000, 2001 Free Software Foundation, Inc. +@end ifinfo + +@c --------------------------------------------------------------------- +@c Titlepage +@c --------------------------------------------------------------------- + +@titlepage +@title Porting libstdc++-v3 +@author Mark Mitchell +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'', the Front-Cover +texts 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++-v3 + +This 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 new +target, you must edit some configuration files and provide some new +header files. + +Before you get started, make sure that you have a working C library on +your target. The C library need not precisely comply with any +particular standard, but should generally conform to the requirements +imposed by the ANSI/ISO standard. + +In addition, you should try to verify that the C++ compiler generally +works. It is difficult to test the C++ compiler without a working +library, 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. +* 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 system + +If you are porting to a new operating-system (as opposed to a new chip +using an existing operating system), you will need to create a new +directory in the @file{config/os} hierarchy. For example, the IRIX +configuration files are all in @file{config/os/irix}. There is no set +way 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 configuration +directories for these two versions of Solaris. On the other hand, both +Solaris 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 a +directory under @file{config/os} to store the files for your operating +system. + +You'll have to change the @file{configure.target} file to ensure that +your new directory is activated. Look for the switch statement that +sets @code{os_include_dir}, and add a pattern to handle your operating +system. The switch statement switches on only the OS portion of the +standard 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{bits/os_defines.h}. This file contains basic macro definitions +that 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 looks +like: + +@example +#define __off_t off_t +#define __off64_t off64_t +#define __ssize_t ssize_t +@end example + +@noindent +You don't have to provide these definitions if your system library +already defines these types -- but the only library known to provide +these types is the GNU C Library, so you will almost certainly have to +provide these macros. Note that this file does not have to include a +header file that defines @code{off_t}, or the other types; you simply +have to provide the macros. + +In addition, several libstdc++-v3 source files unconditionally define +the macro @code{_POSIX_SOURCE}. On many systems, defining this macro +causes large portions of the C library header files to be eliminated +at preprocessing time. Therefore, you may have to @code{#undef} this +macro, or define other macros (like @code{_LARGEFILE_SOURCE} or +@code{__EXTENSIONS__}). You won't know what macros to define or +undefine at this point; you'll have to try compiling the library and +seeing what goes wrong. If you see errors about calling functions +that have not been declared, look in your C library headers to see if +the functions are declared there, and then figure out what macros you +need to define. You will need to add them to the +@code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for your +target. It will not work to simply define these macros in +@file{os_defines.h}. + +At this time, there are two libstdc++-v3-specific macros which may be +defined. @code{_G_USING_THUNKS} may be defined to 0 to express that the +port doesn't use thunks (although it is unclear that this is still +useful since libio support isn't currently working and the g++ v3 ABI +invalidates the assumption that some ports don't use thunks). +@code{_GLIBCPP_AVOID_FSEEK} may be defined if seeking on an interactive +stream (or one hooked to a pipe) is not allowed by the OS. In this +case, getc()/ungetc() will be used at some key locations in the library +implementation instead of fseek(). Currently, the code path to avoid +fseek() is only enabled when the seek size is 1 character away from the +current stream position. This is known to improve *-unknown-freebsd* +and sparc-sun-solaris2.*. + +Finally, you should bracket the entire file in an include-guard, like +this: + +@example +#ifndef _GLIBCPP_OS_DEFINES +#define _GLIBCPP_OS_DEFINES +... +#endif +@end example + +We recommend copying an existing @file{bits/os_defines.h} to use as a +starting point. + +@c --------------------------------------------------------------------- +@c Character types +@c --------------------------------------------------------------------- + +@node Character types +@chapter Character types + +The library requires that you provide three header files to implement +character classification, analagous to that provided by the C libraries +@file{} header. You can model these on the files provided in +@file{config/os/generic/bits}. However, these files will almost +certainly need some modification. + +The first file to write is @file{bits/ctype_base.h}. This file provides +some very basic information about character classification. The libstdc++-v3 +library assumes that your C library implements @file{} by using +a table (indexed by character code) containing integers, where each of +these integers is a bit-mask indicating whether the charcter is +upper-case, lower-case, alphabetic, etc. The @file{bits/ctype_base.h} +file gives the type of the integer, and the values of the various bit +masks. You will have to peer at your own @file{} to figure out +how to define the values required by this file. + +The @file{bits/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 type +declarations, and one enumeration declaration, like this example, taken +from the IRIX configuration: + +@example +struct 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 + +@noindent +The @code{mask} type is the type of the elements in the table. If your +C 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 the +elements in that table. If you don't mind taking a minor performance +penalty, 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 above +example, using the values from your native @file{}. They can +be given symbolically (as above), or numerically, if you prefer. You do +not have to include @file{} in this header; it will always be +included before @file{bits/ctype_base.h} is included. + +The next file to write is @file{bits/ctype_noninline.h}, which also does +not require include guards. This file defines a few member functions +that will be included in @file{include/bits/locale_facets.h}. The first +function that must be written is the @code{ctype::ctype} +constructor. Here is the IRIX example: + +@example +ctype::ctype(const mask* __table = 0, bool __del = false, + size_t __refs = 0) + : _Ctype_nois(__refs), _M_del(__table != 0 && __del), + _M_toupper(NULL), + _M_tolower(NULL), + _M_ctable(NULL), + _M_table(!__table + ? (const mask*) (__libc_attr._ctype_tbl->_class + 1) + : __table) + @{ @} +@end example + +@noindent +There are two parts of this that you might choose to alter. The first, +and most important, is the line involving @code{__libc_attr}. That is +IRIX system-dependent code that gets the base of the table mapping +character codes to attributes. You need to substitute code that obtains +the address of this table on your system. If you want to use your +operating system's tables to map upper-case letters to lower-case, and +vice versa, you should initialize @code{_M_toupper} and +@code{_M_tolower} with those tables, in similar fashion. + +Now, you have to write two functions to convert from upper-case to +lower-case, and vice versa. Here are the IRIX versions: + +@example +char +ctype::do_toupper(char __c) const +@{ return _toupper(__c); @} + +char +ctype::do_tolower(char __c) const +@{ return _tolower(__c); @} +@end example + +@noindent +Your C library provides equivalents to IRIX's @code{_toupper} and +@code{_tolower}. If you initialized @code{_M_toupper} and +@code{_M_tolower} above, then you could use those tables instead. + +Finally, you have to provide two utility functions that convert strings +of characters. The versions provided here will always work -- but you +could use specialized routines for greater performance if you have +machinery to do that on your system: + +@example +const char* +ctype::do_toupper(char* __low, const char* __high) const +@{ + while (__low < __high) + @{ + *__low = do_toupper(*__low); + ++__low; + @} + return __high; +@} + +const char* +ctype::do_tolower(char* __low, const char* __high) const +@{ + while (__low < __high) + @{ + *__low = do_tolower(*__low); + ++__low; + @} + return __high; +@} +@end example + +You must also provide the @file{bits/ctype_inline.h} file, which +contains a few more functions. On most systems, you can just copy +@file{config/os/generic/ctype_inline.h} and use it on your system. + +In detail, the functions provided test characters for particular +properties; they are analagous to the functions like @code{isalpha} and +@code{islower} provided by the C library. + +The first function is implemented like this on IRIX: + +@example +bool +ctype:: +is(mask __m, char __c) const throw() +@{ return (_M_table)[(unsigned char)(__c)] & __m; @} +@end example + +@noindent +The @code{_M_table} is the table passed in above, in the constructor. +This is the table that contains the bitmasks for each character. The +implementation here should work on all systems. + +The next function is: + +@example +const char* +ctype:: +is(const char* __low, const char* __high, mask* __vec) const throw() +@{ + while (__low < __high) + *__vec++ = (_M_table)[(unsigned char)(*__low++)]; + return __high; +@} +@end example + +@noindent +This function is similar; it copies the masks for all the characters +from @code{__low} up until @code{__high} into the vector given by +@code{__vec}. + +The last two functions again are entirely generic: + +@example +const char* +ctype:: +scan_is(mask __m, const char* __low, const char* __high) const throw() +@{ + while (__low < __high && !this->is(__m, *__low)) + ++__low; + return __low; +@} + +const char* +ctype:: +scan_not(mask __m, const char* __low, const char* __high) const throw() +@{ + while (__low < __high && this->is(__m, *__low)) + ++__low; + return __low; +@} +@end example + +@c --------------------------------------------------------------------- +@c Thread safety +@c --------------------------------------------------------------------- + +@node Thread safety +@chapter Thread safety + +The C++ library string functionality requires a couple of atomic +operations to provide thread-safety. If you don't take any special +action, the library will use stub versions of these functions that are +not thread-safe. They will work fine, unless your applications are +multi-threaded. + +If you want to provide custom, safe, versions of these functions, there +are two distinct approaches. One is to provide a version for your CPU, +using assembly language constructs. The other is to use the +thread-safety primitives in your operating system. In either case, you +make a file called @file{bits/atomicity.h}. + +If you are using the assembly-language approach, put this code in +@file{config/cpu//bits/atomicity.h}, where chip is the name of +your processor. In that case, edit the switch statement in +@file{configure.target} to set the @code{cpu_include_dir}. In either +case, set the switch statement that sets @code{ATOMICITYH} to be the +directory containing @file{bits/atomicity.h}. + +With those bits out of the way, you have to actually write +@file{bits/atomicity.h} itself. This file should be wrapped in an +include guard named @code{_BITS_ATOMICITY_H}. It should define one +type, and two functions. + +The type is @code{_Atomic_word}. Here is the version used on IRIX: + +@example +typedef long _Atomic_word; +@end example + +@noindent +This type must be a signed integral type supporting atomic operations. +If you're using the OS approach, use the same type used by your system's +primitives. Otherwise, use the type for which your CPU provides atomic +primitives. + +Then, you must provide two functions. The bodies of these functions +must be equivalent to those provided here, but using atomic operations: + +@example +static inline _Atomic_word +__attribute__ ((__unused__)) +__exchange_and_add (_Atomic_word* __mem, int __val) +@{ + _Atomic_word __result = *__mem; + *__mem += __val; + return __result; +@} + +static inline void +__attribute__ ((__unused__)) +__atomic_add (_Atomic_word* __mem, int __val) +@{ + *__mem += __val; +@} +@end example + +@c --------------------------------------------------------------------- +@c Numeric limits +@c --------------------------------------------------------------------- + +@node Numeric limits +@chapter Numeric limits + +The C++ library requires information about the fundamental data types, +such as the minimum and maximum representable values of each type. +You can define each of these values individually, but it is usually +easiest just to indicate how many bits are used in each of the data +types and let the library do the rest. For information about the +macros to define, see the top of @file{include/bits/std_limits.h}. + +If you need to define any macros, you can do so in +@file{os_defines.h}. However, if all operating systems for your CPU +are likely to use the same values, you can provide a CPU-specific file +instead so that you do not have to provide the same definitions for +each operating system. To take that approach, create a new file +called @file{limits.h} in your CPU configuration directory (e.g., +@file{config/cpu/i386/bits}) and then modify @file{configure.target} +so that @code{LIMITSH} is set to the CPU directory (e.g., +@file{config/cpu/i386}). Note that @code{LIMITSH} should not include +the @samp{bits} part of the directory name. + +@c --------------------------------------------------------------------- +@c Libtool +@c --------------------------------------------------------------------- + +@node Libtool +@chapter Libtool + +The C++ library is compiled, archived and linked with libtool. +Explaining the full workings of libtool is beyond the scope of this +document, but there are a few, particular bits that are necessary for +porting. + +Some parts of the libstdc++-v3 library are compiled with the libtool +@code{--tags CXX} option (the C++ definitions for libtool). Therefore, +@file{ltcf-cxx.sh} in the top-level directory needs to have the correct +logic to compile and archive objects equivalent to the C version of libtool, +@file{ltcf-c.sh}. Some libtool targets have definitions for C but not +for C++, or C++ definitions which have not been kept up to date. + +The C++ run-time library contains initialization code that needs to be +run as the library is loaded. Often, that requires linking in special +object files when the C++ library is built as a shared library, or +taking other system-specific actions. + +The libstdc++-v3 library is linked with the C version of libtool, even though it +is a C++ library. Therefore, the C version of libtool needs to ensure +that the run-time library initializers are run. The usual way to do +this is to build the library using @code{gcc -shared}. + +If you need to change how the library is linked, look at +@file{ltcf-c.sh} in the top-level directory. Find the switch statement +that sets @code{archive_cmds}. Here, adjust the setting for your +operating system. + +@c --------------------------------------------------------------------- +@c GFDL +@c --------------------------------------------------------------------- + +@include fdl.texi + +@c --------------------------------------------------------------------- +@c Epilogue +@c --------------------------------------------------------------------- + +@contents +@bye diff --git a/libstdc++-v3/docs/html/Makefile b/libstdc++-v3/docs/html/Makefile index bedbd883f18..df46f74d7a2 100644 --- a/libstdc++-v3/docs/html/Makefile +++ b/libstdc++-v3/docs/html/Makefile @@ -1,5 +1,13 @@ +MAKEINFO=makeinfo +INC=../../../gcc/doc/include + +all: faq/index.txt 17_intro/porting.html + faq/index.txt: faq/index.html - lynx -dump faq/index.html | sed "s%file://localhost`pwd`%..%" > $@ + lynx -dump $< | sed "s%file://localhost`pwd`%..%" > $@ + +17_intro/porting.html: 17_intro/porting.texi + ${MAKEINFO} -I ${INC} --html --no-split $< -o $@ diff --git a/libstdc++-v3/porting.texi b/libstdc++-v3/porting.texi deleted file mode 100644 index 9114806b63f..00000000000 --- a/libstdc++-v3/porting.texi +++ /dev/null @@ -1,510 +0,0 @@ -\input texinfo - -@c --------------------------------------------------------------------- -@c Prologue -@c --------------------------------------------------------------------- - -@setfilename porting.info -@settitle Porting libstdc++-v3 -@setchapternewpage odd - -@ifinfo -This file explains how to port libstdc++-v3 (the GNU C++ library) to -a new target. - -Copyright (c) 2000, 2001 Free Software Foundation, Inc. -@end ifinfo - -@c --------------------------------------------------------------------- -@c Titlepage -@c --------------------------------------------------------------------- - -@titlepage -@title Porting libstdc++-v3 -@author Mark Mitchell -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', the Front-Cover -texts 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++-v3 - -This 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 new -target, you must edit some configuration files and provide some new -header files. - -Before you get started, make sure that you have a working C library on -your target. The C library need not precisely comply with any -particular standard, but should generally conform to the requirements -imposed by the ANSI/ISO standard. - -In addition, you should try to verify that the C++ compiler generally -works. It is difficult to test the C++ compiler without a working -library, 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. -* 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 system - -If you are porting to a new operating-system (as opposed to a new chip -using an existing operating system), you will need to create a new -directory in the @file{config/os} hierarchy. For example, the IRIX -configuration files are all in @file{config/os/irix}. There is no set -way 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 configuration -directories for these two versions of Solaris. On the other hand, both -Solaris 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 a -directory under @file{config/os} to store the files for your operating -system. - -You'll have to change the @file{configure.target} file to ensure that -your new directory is activated. Look for the switch statement that -sets @code{os_include_dir}, and add a pattern to handle your operating -system. The switch statement switches on only the OS portion of the -standard 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{bits/os_defines.h}. This file contains basic macro definitions -that 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 looks -like: - -@example -#define __off_t off_t -#define __off64_t off64_t -#define __ssize_t ssize_t -@end example - -@noindent -You don't have to provide these definitions if your system library -already defines these types -- but the only library known to provide -these types is the GNU C Library, so you will almost certainly have to -provide these macros. Note that this file does not have to include a -header file that defines @code{off_t}, or the other types; you simply -have to provide the macros. - -In addition, several libstdc++-v3 source files unconditionally define -the macro @code{_POSIX_SOURCE}. On many systems, defining this macro -causes large portions of the C library header files to be eliminated -at preprocessing time. Therefore, you may have to @code{#undef} this -macro, or define other macros (like @code{_LARGEFILE_SOURCE} or -@code{__EXTENSIONS__}). You won't know what macros to define or -undefine at this point; you'll have to try compiling the library and -seeing what goes wrong. If you see errors about calling functions -that have not been declared, look in your C library headers to see if -the functions are declared there, and then figure out what macros you -need to define. You will need to add them to the -@code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for your -target. It will not work to simply define these macros in -@file{os_defines.h}. - -At this time, there are two libstdc++-v3-specific macros which may be -defined. @code{_G_USING_THUNKS} may be defined to 0 to express that the -port doesn't use thunks (although it is unclear that this is still -useful since libio support isn't currently working and the g++ v3 ABI -invalidates the assumption that some ports don't use thunks). -@code{_GLIBCPP_AVOID_FSEEK} may be defined if seeking on an interactive -stream (or one hooked to a pipe) is not allowed by the OS. In this -case, getc()/ungetc() will be used at some key locations in the library -implementation instead of fseek(). Currently, the code path to avoid -fseek() is only enabled when the seek size is 1 character away from the -current stream position. This is known to improve *-unknown-freebsd* -and sparc-sun-solaris2.*. - -Finally, you should bracket the entire file in an include-guard, like -this: - -@example -#ifndef _GLIBCPP_OS_DEFINES -#define _GLIBCPP_OS_DEFINES -... -#endif -@end example - -We recommend copying an existing @file{bits/os_defines.h} to use as a -starting point. - -@c --------------------------------------------------------------------- -@c Character types -@c --------------------------------------------------------------------- - -@node Character types -@chapter Character types - -The library requires that you provide three header files to implement -character classification, analagous to that provided by the C libraries -@file{} header. You can model these on the files provided in -@file{config/os/generic/bits}. However, these files will almost -certainly need some modification. - -The first file to write is @file{bits/ctype_base.h}. This file provides -some very basic information about character classification. The libstdc++-v3 -library assumes that your C library implements @file{} by using -a table (indexed by character code) containing integers, where each of -these integers is a bit-mask indicating whether the charcter is -upper-case, lower-case, alphabetic, etc. The @file{bits/ctype_base.h} -file gives the type of the integer, and the values of the various bit -masks. You will have to peer at your own @file{} to figure out -how to define the values required by this file. - -The @file{bits/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 type -declarations, and one enumeration declaration, like this example, taken -from the IRIX configuration: - -@example -struct 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 - -@noindent -The @code{mask} type is the type of the elements in the table. If your -C 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 the -elements in that table. If you don't mind taking a minor performance -penalty, 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 above -example, using the values from your native @file{}. They can -be given symbolically (as above), or numerically, if you prefer. You do -not have to include @file{} in this header; it will always be -included before @file{bits/ctype_base.h} is included. - -The next file to write is @file{bits/ctype_noninline.h}, which also does -not require include guards. This file defines a few member functions -that will be included in @file{include/bits/locale_facets.h}. The first -function that must be written is the @code{ctype::ctype} -constructor. Here is the IRIX example: - -@example -ctype::ctype(const mask* __table = 0, bool __del = false, - size_t __refs = 0) - : _Ctype_nois(__refs), _M_del(__table != 0 && __del), - _M_toupper(NULL), - _M_tolower(NULL), - _M_ctable(NULL), - _M_table(!__table - ? (const mask*) (__libc_attr._ctype_tbl->_class + 1) - : __table) - @{ @} -@end example - -@noindent -There are two parts of this that you might choose to alter. The first, -and most important, is the line involving @code{__libc_attr}. That is -IRIX system-dependent code that gets the base of the table mapping -character codes to attributes. You need to substitute code that obtains -the address of this table on your system. If you want to use your -operating system's tables to map upper-case letters to lower-case, and -vice versa, you should initialize @code{_M_toupper} and -@code{_M_tolower} with those tables, in similar fashion. - -Now, you have to write two functions to convert from upper-case to -lower-case, and vice versa. Here are the IRIX versions: - -@example -char -ctype::do_toupper(char __c) const -@{ return _toupper(__c); @} - -char -ctype::do_tolower(char __c) const -@{ return _tolower(__c); @} -@end example - -@noindent -Your C library provides equivalents to IRIX's @code{_toupper} and -@code{_tolower}. If you initialized @code{_M_toupper} and -@code{_M_tolower} above, then you could use those tables instead. - -Finally, you have to provide two utility functions that convert strings -of characters. The versions provided here will always work -- but you -could use specialized routines for greater performance if you have -machinery to do that on your system: - -@example -const char* -ctype::do_toupper(char* __low, const char* __high) const -@{ - while (__low < __high) - @{ - *__low = do_toupper(*__low); - ++__low; - @} - return __high; -@} - -const char* -ctype::do_tolower(char* __low, const char* __high) const -@{ - while (__low < __high) - @{ - *__low = do_tolower(*__low); - ++__low; - @} - return __high; -@} -@end example - -You must also provide the @file{bits/ctype_inline.h} file, which -contains a few more functions. On most systems, you can just copy -@file{config/os/generic/ctype_inline.h} and use it on your system. - -In detail, the functions provided test characters for particular -properties; they are analagous to the functions like @code{isalpha} and -@code{islower} provided by the C library. - -The first function is implemented like this on IRIX: - -@example -bool -ctype:: -is(mask __m, char __c) const throw() -@{ return (_M_table)[(unsigned char)(__c)] & __m; @} -@end example - -@noindent -The @code{_M_table} is the table passed in above, in the constructor. -This is the table that contains the bitmasks for each character. The -implementation here should work on all systems. - -The next function is: - -@example -const char* -ctype:: -is(const char* __low, const char* __high, mask* __vec) const throw() -@{ - while (__low < __high) - *__vec++ = (_M_table)[(unsigned char)(*__low++)]; - return __high; -@} -@end example - -@noindent -This function is similar; it copies the masks for all the characters -from @code{__low} up until @code{__high} into the vector given by -@code{__vec}. - -The last two functions again are entirely generic: - -@example -const char* -ctype:: -scan_is(mask __m, const char* __low, const char* __high) const throw() -@{ - while (__low < __high && !this->is(__m, *__low)) - ++__low; - return __low; -@} - -const char* -ctype:: -scan_not(mask __m, const char* __low, const char* __high) const throw() -@{ - while (__low < __high && this->is(__m, *__low)) - ++__low; - return __low; -@} -@end example - -@c --------------------------------------------------------------------- -@c Thread safety -@c --------------------------------------------------------------------- - -@node Thread safety -@chapter Thread safety - -The C++ library string functionality requires a couple of atomic -operations to provide thread-safety. If you don't take any special -action, the library will use stub versions of these functions that are -not thread-safe. They will work fine, unless your applications are -multi-threaded. - -If you want to provide custom, safe, versions of these functions, there -are two distinct approaches. One is to provide a version for your CPU, -using assembly language constructs. The other is to use the -thread-safety primitives in your operating system. In either case, you -make a file called @file{bits/atomicity.h}. - -If you are using the assembly-language approach, put this code in -@file{config/cpu//bits/atomicity.h}, where chip is the name of -your processor. In that case, edit the switch statement in -@file{configure.target} to set the @code{cpu_include_dir}. In either -case, set the switch statement that sets @code{ATOMICITYH} to be the -directory containing @file{bits/atomicity.h}. - -With those bits out of the way, you have to actually write -@file{bits/atomicity.h} itself. This file should be wrapped in an -include guard named @code{_BITS_ATOMICITY_H}. It should define one -type, and two functions. - -The type is @code{_Atomic_word}. Here is the version used on IRIX: - -@example -typedef long _Atomic_word; -@end example - -@noindent -This type must be a signed integral type supporting atomic operations. -If you're using the OS approach, use the same type used by your system's -primitives. Otherwise, use the type for which your CPU provides atomic -primitives. - -Then, you must provide two functions. The bodies of these functions -must be equivalent to those provided here, but using atomic operations: - -@example -static inline _Atomic_word -__attribute__ ((__unused__)) -__exchange_and_add (_Atomic_word* __mem, int __val) -@{ - _Atomic_word __result = *__mem; - *__mem += __val; - return __result; -@} - -static inline void -__attribute__ ((__unused__)) -__atomic_add (_Atomic_word* __mem, int __val) -@{ - *__mem += __val; -@} -@end example - -@c --------------------------------------------------------------------- -@c Numeric limits -@c --------------------------------------------------------------------- - -@node Numeric limits -@chapter Numeric limits - -The C++ library requires information about the fundamental data types, -such as the minimum and maximum representable values of each type. -You can define each of these values individually, but it is usually -easiest just to indicate how many bits are used in each of the data -types and let the library do the rest. For information about the -macros to define, see the top of @file{include/bits/std_limits.h}. - -If you need to define any macros, you can do so in -@file{os_defines.h}. However, if all operating systems for your CPU -are likely to use the same values, you can provide a CPU-specific file -instead so that you do not have to provide the same definitions for -each operating system. To take that approach, create a new file -called @file{limits.h} in your CPU configuration directory (e.g., -@file{config/cpu/i386/bits}) and then modify @file{configure.target} -so that @code{LIMITSH} is set to the CPU directory (e.g., -@file{config/cpu/i386}). Note that @code{LIMITSH} should not include -the @samp{bits} part of the directory name. - -@c --------------------------------------------------------------------- -@c Libtool -@c --------------------------------------------------------------------- - -@node Libtool -@chapter Libtool - -The C++ library is compiled, archived and linked with libtool. -Explaining the full workings of libtool is beyond the scope of this -document, but there are a few, particular bits that are necessary for -porting. - -Some parts of the libstdc++-v3 library are compiled with the libtool -@code{--tags CXX} option (the C++ definitions for libtool). Therefore, -@file{ltcf-cxx.sh} in the top-level directory needs to have the correct -logic to compile and archive objects equivalent to the C version of libtool, -@file{ltcf-c.sh}. Some libtool targets have definitions for C but not -for C++, or C++ definitions which have not been kept up to date. - -The C++ run-time library contains initialization code that needs to be -run as the library is loaded. Often, that requires linking in special -object files when the C++ library is built as a shared library, or -taking other system-specific actions. - -The libstdc++-v3 library is linked with the C version of libtool, even though it -is a C++ library. Therefore, the C version of libtool needs to ensure -that the run-time library initializers are run. The usual way to do -this is to build the library using @code{gcc -shared}. - -If you need to change how the library is linked, look at -@file{ltcf-c.sh} in the top-level directory. Find the switch statement -that sets @code{archive_cmds}. Here, adjust the setting for your -operating system. - -@c --------------------------------------------------------------------- -@c GFDL -@c --------------------------------------------------------------------- - -@include fdl.texi - -@c --------------------------------------------------------------------- -@c Epilogue -@c --------------------------------------------------------------------- - -@contents -@bye