]>
Commit | Line | Data |
---|---|---|
8a165db0 BK |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" | |
4 | [ ]> | |
5 | ||
6 | <appendix id="appendix.contrib" xreflabel="Contributing"> | |
7 | <?dbhtml filename="appendix_contributing.html"?> | |
c9024a78 | 8 | |
8a165db0 BK |
9 | <appendixinfo> |
10 | <keywordset> | |
11 | <keyword> | |
12 | ISO C++ | |
13 | </keyword> | |
14 | <keyword> | |
15 | library | |
16 | </keyword> | |
17 | </keywordset> | |
18 | </appendixinfo> | |
19 | ||
f86ce601 BK |
20 | <title> |
21 | Contributing | |
22 | <indexterm> | |
23 | <primary>Appendix</primary> | |
24 | <secondary>Contributing</secondary> | |
25 | </indexterm> | |
26 | </title> | |
8a165db0 BK |
27 | |
28 | <para> | |
29 | The GNU C++ Library follows an open development model. Active | |
30 | contributors are assigned maintainer-ship responsibility, and given | |
31 | write access to the source repository. First time contributors | |
32 | should follow this procedure: | |
33 | </para> | |
34 | ||
35 | <sect1 id="contrib.list" xreflabel="Contributor Checklist"> | |
36 | <title>Contributor Checklist</title> | |
37 | ||
38 | <sect2 id="list.reading" xreflabel="list.reading"> | |
39 | <title>Reading</title> | |
40 | ||
c9024a78 BK |
41 | <itemizedlist> |
42 | <listitem> | |
43 | <para> | |
44 | Get and read the relevant sections of the C++ language | |
45 | specification. Copies of the full ISO 14882 standard are | |
46 | available on line via the ISO mirror site for committee | |
47 | members. Non-members, or those who have not paid for the | |
48 | privilege of sitting on the committee and sustained their | |
49 | two meeting commitment for voting rights, may get a copy of | |
50 | the standard from their respective national standards | |
51 | organization. In the USA, this national standards | |
52 | organization is ANSI and their web-site is right | |
53 | <ulink url="http://www.ansi.org">here.</ulink> | |
54 | (And if you've already registered with them, clicking this link will take you to directly to the place where you can | |
55 | <ulink url="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%3A2003">buy the standard on-line.)</ulink> | |
56 | </para> | |
57 | </listitem> | |
58 | ||
59 | <listitem> | |
60 | <para> | |
61 | The library working group bugs, and known defects, can | |
62 | be obtained here: | |
63 | <ulink url="http://www.open-std.org/jtc1/sc22/wg21/">http://www.open-std.org/jtc1/sc22/wg21 </ulink> | |
64 | </para> | |
65 | </listitem> | |
66 | ||
67 | <listitem> | |
68 | <para> | |
69 | The newsgroup dedicated to standardization issues is | |
70 | comp.std.c++: this FAQ for this group is quite useful and | |
71 | can be | |
72 | found <ulink url="http://www.jamesd.demon.co.uk/csc/faq.html"> | |
73 | here </ulink>. | |
8a165db0 | 74 | </para> |
c9024a78 BK |
75 | </listitem> |
76 | ||
77 | <listitem> | |
78 | <para> | |
79 | Peruse | |
80 | the <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU | |
81 | Coding Standards</ulink>, and chuckle when you hit the part | |
82 | about <quote>Using Languages Other Than C</quote>. | |
83 | </para> | |
84 | </listitem> | |
85 | ||
86 | <listitem> | |
87 | <para> | |
88 | Be familiar with the extensions that preceded these | |
89 | general GNU rules. These style issues for libstdc++ can be | |
90 | found <link linkend="contrib.coding_style">here</link>. | |
91 | </para> | |
92 | </listitem> | |
8a165db0 | 93 | |
c9024a78 BK |
94 | <listitem> |
95 | <para> | |
96 | And last but certainly not least, read the | |
97 | library-specific information | |
98 | found <link linkend="appendix.porting"> here</link>. | |
99 | </para> | |
100 | </listitem> | |
101 | </itemizedlist> | |
8a165db0 | 102 | |
c9024a78 BK |
103 | </sect2> |
104 | <sect2 id="list.copyright" xreflabel="list.copyright"> | |
105 | <title>Assignment</title> | |
106 | <para> | |
107 | Small changes can be accepted without a copyright assignment form on | |
108 | file. New code and additions to the library need completed copyright | |
109 | assignment form on file at the FSF. Note: your employer may be required | |
110 | to fill out appropriate disclaimer forms as well. | |
111 | </para> | |
8a165db0 | 112 | |
c9024a78 BK |
113 | <para> |
114 | Historically, the libstdc++ assignment form added the following | |
115 | question: | |
116 | </para> | |
8a165db0 | 117 | |
8a165db0 | 118 | <para> |
c9024a78 BK |
119 | <quote> |
120 | Which Belgian comic book character is better, Tintin or Asterix, and | |
121 | why? | |
122 | </quote> | |
8a165db0 | 123 | </para> |
8a165db0 | 124 | |
c9024a78 BK |
125 | <para> |
126 | While not strictly necessary, humoring the maintainers and answering | |
127 | this question would be appreciated. | |
128 | </para> | |
8a165db0 | 129 | |
c9024a78 BK |
130 | <para> |
131 | For more information about getting a copyright assignment, please see | |
132 | <ulink url="http://www.gnu.org/prep/maintain/html_node/Legal-Matters.html">Legal | |
133 | Matters</ulink>. | |
134 | </para> | |
8a165db0 | 135 | |
c9024a78 BK |
136 | <para> |
137 | Please contact Benjamin Kosnik at | |
138 | <email>bkoz+assign@redhat.com</email> if you are confused | |
139 | about the assignment or have general licensing questions. When | |
140 | requesting an assignment form from | |
141 | <email>mailto:assign@gnu.org</email>, please cc the libstdc++ | |
142 | maintainer above so that progress can be monitored. | |
143 | </para> | |
144 | </sect2> | |
8a165db0 | 145 | |
c9024a78 BK |
146 | <sect2 id="list.getting" xreflabel="list.getting"> |
147 | <title>Getting Sources</title> | |
148 | <para> | |
149 | <ulink url="http://gcc.gnu.org/svnwrite.html">Getting write access | |
150 | (look for "Write after approval")</ulink> | |
151 | </para> | |
152 | </sect2> | |
8a165db0 | 153 | |
c9024a78 BK |
154 | <sect2 id="list.patches" xreflabel="list.patches"> |
155 | <title>Submitting Patches</title> | |
8a165db0 | 156 | |
c9024a78 BK |
157 | <para> |
158 | Every patch must have several pieces of information before it can be | |
159 | properly evaluated. Ideally (and to ensure the fastest possible | |
160 | response from the maintainers) it would have all of these pieces: | |
161 | </para> | |
8a165db0 | 162 | |
c9024a78 BK |
163 | <itemizedlist> |
164 | <listitem> | |
165 | <para> | |
166 | A description of the bug and how your patch fixes this | |
167 | bug. For new features a description of the feature and your | |
168 | implementation. | |
169 | </para> | |
170 | </listitem> | |
171 | ||
172 | <listitem> | |
173 | <para> | |
174 | A ChangeLog entry as plain text; see the various | |
175 | ChangeLog files for format and content. If using you are | |
176 | using emacs as your editor, simply position the insertion | |
177 | point at the beginning of your change and hit CX-4a to bring | |
178 | up the appropriate ChangeLog entry. See--magic! Similar | |
179 | functionality also exists for vi. | |
180 | </para> | |
181 | </listitem> | |
182 | ||
183 | <listitem> | |
184 | <para> | |
185 | A testsuite submission or sample program that will | |
186 | easily and simply show the existing error or test new | |
187 | functionality. | |
188 | </para> | |
189 | </listitem> | |
190 | ||
191 | <listitem> | |
192 | <para> | |
193 | The patch itself. If you are accessing the SVN | |
194 | repository use <command>svn update; svn diff NEW</command>; | |
195 | else, use <command>diff -cp OLD NEW</command> ... If your | |
196 | version of diff does not support these options, then get the | |
197 | latest version of GNU | |
198 | diff. The <ulink url="http://gcc.gnu.org/wiki/SvnTricks">SVN | |
199 | Tricks</ulink> wiki page has information on customising the | |
200 | output of <code>svn diff</code>. | |
201 | </para> | |
202 | </listitem> | |
203 | ||
204 | <listitem> | |
205 | <para> | |
206 | When you have all these pieces, bundle them up in a | |
207 | mail message and send it to libstdc++@gcc.gnu.org. All | |
208 | patches and related discussion should be sent to the | |
209 | libstdc++ mailing list. | |
210 | </para> | |
211 | </listitem> | |
212 | </itemizedlist> | |
213 | ||
214 | </sect2> | |
215 | ||
216 | </sect1> | |
217 | ||
218 | <sect1 id="contrib.organization" xreflabel="Source Organization"> | |
5e623d0b | 219 | <?dbhtml filename="source_organization.html"?> |
c9024a78 BK |
220 | <title>Directory Layout and Source Conventions</title> |
221 | ||
222 | <para> | |
223 | The unpacked source directory of libstdc++ contains the files | |
224 | needed to create the GNU C++ Library. | |
225 | </para> | |
226 | ||
227 | <literallayout> | |
228 | It has subdirectories: | |
229 | ||
230 | doc | |
231 | Files in HTML and text format that document usage, quirks of the | |
232 | implementation, and contributor checklists. | |
233 | ||
234 | include | |
235 | All header files for the C++ library are within this directory, | |
236 | modulo specific runtime-related files that are in the libsupc++ | |
237 | directory. | |
238 | ||
239 | include/std | |
240 | Files meant to be found by #include <name> directives in | |
241 | standard-conforming user programs. | |
242 | ||
243 | include/c | |
244 | Headers intended to directly include standard C headers. | |
245 | [NB: this can be enabled via --enable-cheaders=c] | |
246 | ||
247 | include/c_global | |
248 | Headers intended to include standard C headers in | |
249 | the global namespace, and put select names into the std:: | |
250 | namespace. [NB: this is the default, and is the same as | |
251 | --enable-cheaders=c_global] | |
252 | ||
253 | include/c_std | |
254 | Headers intended to include standard C headers | |
255 | already in namespace std, and put select names into the std:: | |
256 | namespace. [NB: this is the same as --enable-cheaders=c_std] | |
257 | ||
258 | include/bits | |
259 | Files included by standard headers and by other files in | |
260 | the bits directory. | |
261 | ||
262 | include/backward | |
263 | Headers provided for backward compatibility, such as <iostream.h>. | |
264 | They are not used in this library. | |
265 | ||
266 | include/ext | |
267 | Headers that define extensions to the standard library. No | |
268 | standard header refers to any of them. | |
269 | ||
270 | scripts | |
271 | Scripts that are used during the configure, build, make, or test | |
272 | process. | |
273 | ||
274 | src | |
275 | Files that are used in constructing the library, but are not | |
276 | installed. | |
277 | ||
278 | testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*] | |
279 | Test programs are here, and may be used to begin to exercise the | |
280 | library. Support for "make check" and "make check-install" is | |
281 | complete, and runs through all the subdirectories here when this | |
282 | command is issued from the build directory. Please note that | |
283 | "make check" requires DejaGNU 1.4 or later to be installed. Please | |
284 | note that "make check-script" calls the script mkcheck, which | |
285 | requires bash, and which may need the paths to bash adjusted to | |
286 | work properly, as /bin/bash is assumed. | |
287 | ||
288 | Other subdirectories contain variant versions of certain files | |
289 | that are meant to be copied or linked by the configure script. | |
290 | Currently these are: | |
291 | ||
292 | config/abi | |
293 | config/cpu | |
294 | config/io | |
295 | config/locale | |
296 | config/os | |
297 | ||
adc8a1e3 | 298 | In addition, a subdirectory holds the convenience library libsupc++. |
c9024a78 BK |
299 | |
300 | libsupc++ | |
301 | Contains the runtime library for C++, including exception | |
302 | handling and memory allocation and deallocation, RTTI, terminate | |
303 | handlers, etc. | |
304 | ||
305 | Note that glibc also has a bits/ subdirectory. We will either | |
306 | need to be careful not to collide with names in its bits/ | |
307 | directory; or rename bits to (e.g.) cppbits/. | |
308 | ||
309 | In files throughout the system, lines marked with an "XXX" indicate | |
310 | a bug or incompletely-implemented feature. Lines marked "XXX MT" | |
311 | indicate a place that may require attention for multi-thread safety. | |
312 | </literallayout> | |
313 | ||
314 | </sect1> | |
315 | ||
316 | <sect1 id="contrib.coding_style" xreflabel="Coding Style"> | |
5e623d0b | 317 | <?dbhtml filename="source_code_style.html"?> |
c9024a78 BK |
318 | <title>Coding Style</title> |
319 | <para> | |
320 | </para> | |
321 | <sect2 id="coding_style.bad_identifiers" xreflabel="coding_style.bad"> | |
4394b61e | 322 | <title>Bad Identifiers</title> |
c9024a78 BK |
323 | <para> |
324 | Identifiers that conflict and should be avoided. | |
325 | </para> | |
8a165db0 | 326 | |
c9024a78 BK |
327 | <literallayout> |
328 | This is the list of names <quote>reserved to the | |
329 | implementation</quote> that have been claimed by certain | |
330 | compilers and system headers of interest, and should not be used | |
331 | in the library. It will grow, of course. We generally are | |
332 | interested in names that are not all-caps, except for those like | |
333 | "_T" | |
334 | ||
335 | For Solaris: | |
336 | _B | |
337 | _C | |
338 | _L | |
339 | _N | |
340 | _P | |
341 | _S | |
342 | _U | |
343 | _X | |
344 | _E1 | |
345 | .. | |
346 | _E24 | |
347 | ||
348 | Irix adds: | |
349 | _A | |
350 | _G | |
351 | ||
352 | MS adds: | |
353 | _T | |
354 | ||
355 | BSD adds: | |
356 | __used | |
357 | __unused | |
358 | __inline | |
359 | _Complex | |
360 | __istype | |
361 | __maskrune | |
362 | __tolower | |
363 | __toupper | |
364 | __wchar_t | |
365 | __wint_t | |
366 | _res | |
367 | _res_ext | |
368 | __tg_* | |
369 | ||
22493a73 PC |
370 | SPU adds: |
371 | __ea | |
372 | ||
c9024a78 BK |
373 | For GCC: |
374 | ||
375 | [Note that this list is out of date. It applies to the old | |
376 | name-mangling; in G++ 3.0 and higher a different name-mangling is | |
377 | used. In addition, many of the bugs relating to G++ interpreting | |
378 | these names as operators have been fixed.] | |
379 | ||
380 | The full set of __* identifiers (combined from gcc/cp/lex.c and | |
381 | gcc/cplus-dem.c) that are either old or new, but are definitely | |
382 | recognized by the demangler, is: | |
383 | ||
384 | __aa | |
385 | __aad | |
386 | __ad | |
387 | __addr | |
388 | __adv | |
389 | __aer | |
390 | __als | |
391 | __alshift | |
392 | __amd | |
393 | __ami | |
394 | __aml | |
395 | __amu | |
396 | __aor | |
397 | __apl | |
398 | __array | |
399 | __ars | |
400 | __arshift | |
401 | __as | |
402 | __bit_and | |
403 | __bit_ior | |
404 | __bit_not | |
405 | __bit_xor | |
406 | __call | |
407 | __cl | |
408 | __cm | |
409 | __cn | |
410 | __co | |
411 | __component | |
412 | __compound | |
413 | __cond | |
414 | __convert | |
415 | __delete | |
416 | __dl | |
417 | __dv | |
418 | __eq | |
419 | __er | |
420 | __ge | |
421 | __gt | |
422 | __indirect | |
423 | __le | |
424 | __ls | |
425 | __lt | |
426 | __max | |
427 | __md | |
428 | __method_call | |
429 | __mi | |
430 | __min | |
431 | __minus | |
432 | __ml | |
433 | __mm | |
434 | __mn | |
435 | __mult | |
436 | __mx | |
437 | __ne | |
438 | __negate | |
439 | __new | |
440 | __nop | |
441 | __nt | |
442 | __nw | |
443 | __oo | |
444 | __op | |
445 | __or | |
446 | __pl | |
447 | __plus | |
448 | __postdecrement | |
449 | __postincrement | |
450 | __pp | |
451 | __pt | |
452 | __rf | |
453 | __rm | |
454 | __rs | |
455 | __sz | |
456 | __trunc_div | |
457 | __trunc_mod | |
458 | __truth_andif | |
459 | __truth_not | |
460 | __truth_orif | |
461 | __vc | |
462 | __vd | |
463 | __vn | |
464 | ||
465 | SGI badnames: | |
466 | __builtin_alloca | |
467 | __builtin_fsqrt | |
468 | __builtin_sqrt | |
469 | __builtin_fabs | |
470 | __builtin_dabs | |
471 | __builtin_cast_f2i | |
472 | __builtin_cast_i2f | |
473 | __builtin_cast_d2ll | |
474 | __builtin_cast_ll2d | |
475 | __builtin_copy_dhi2i | |
476 | __builtin_copy_i2dhi | |
477 | __builtin_copy_dlo2i | |
478 | __builtin_copy_i2dlo | |
479 | __add_and_fetch | |
480 | __sub_and_fetch | |
481 | __or_and_fetch | |
482 | __xor_and_fetch | |
483 | __and_and_fetch | |
484 | __nand_and_fetch | |
485 | __mpy_and_fetch | |
486 | __min_and_fetch | |
487 | __max_and_fetch | |
488 | __fetch_and_add | |
489 | __fetch_and_sub | |
490 | __fetch_and_or | |
491 | __fetch_and_xor | |
492 | __fetch_and_and | |
493 | __fetch_and_nand | |
494 | __fetch_and_mpy | |
495 | __fetch_and_min | |
496 | __fetch_and_max | |
497 | __lock_test_and_set | |
498 | __lock_release | |
499 | __lock_acquire | |
500 | __compare_and_swap | |
501 | __synchronize | |
502 | __high_multiply | |
503 | __unix | |
504 | __sgi | |
505 | __linux__ | |
506 | __i386__ | |
507 | __i486__ | |
508 | __cplusplus | |
509 | __embedded_cplusplus | |
510 | // long double conversion members mangled as __opr | |
511 | // http://gcc.gnu.org/ml/libstdc++/1999-q4/msg00060.html | |
512 | _opr | |
513 | </literallayout> | |
514 | </sect2> | |
515 | ||
516 | <sect2 id="coding_style.example" xreflabel="coding_style.example"> | |
517 | <title>By Example</title> | |
518 | <literallayout> | |
519 | This library is written to appropriate C++ coding standards. As such, | |
520 | it is intended to precede the recommendations of the GNU Coding | |
521 | Standard, which can be referenced in full here: | |
522 | ||
523 | http://www.gnu.org/prep/standards/standards.html#Formatting | |
524 | ||
525 | The rest of this is also interesting reading, but skip the "Design | |
526 | Advice" part. | |
527 | ||
528 | The GCC coding conventions are here, and are also useful: | |
529 | http://gcc.gnu.org/codingconventions.html | |
530 | ||
531 | In addition, because it doesn't seem to be stated explicitly anywhere | |
532 | else, there is an 80 column source limit. | |
533 | ||
534 | ChangeLog entries for member functions should use the | |
535 | classname::member function name syntax as follows: | |
536 | ||
537 | 1999-04-15 Dennis Ritchie <dr@att.com> | |
538 | ||
539 | * src/basic_file.cc (__basic_file::open): Fix thinko in | |
540 | _G_HAVE_IO_FILE_OPEN bits. | |
541 | ||
542 | Notable areas of divergence from what may be previous local practice | |
543 | (particularly for GNU C) include: | |
544 | ||
545 | 01. Pointers and references | |
546 | char* p = "flop"; | |
547 | char& c = *p; | |
548 | -NOT- | |
549 | char *p = "flop"; // wrong | |
550 | char &c = *p; // wrong | |
551 | ||
552 | Reason: In C++, definitions are mixed with executable code. Here, | |
553 | p is being initialized, not *p. This is near-universal | |
554 | practice among C++ programmers; it is normal for C hackers | |
555 | to switch spontaneously as they gain experience. | |
556 | ||
557 | 02. Operator names and parentheses | |
558 | operator==(type) | |
559 | -NOT- | |
560 | operator == (type) // wrong | |
561 | ||
562 | Reason: The == is part of the function name. Separating | |
563 | it makes the declaration look like an expression. | |
8a165db0 | 564 | |
c9024a78 BK |
565 | 03. Function names and parentheses |
566 | void mangle() | |
567 | -NOT- | |
568 | void mangle () // wrong | |
8a165db0 | 569 | |
c9024a78 BK |
570 | Reason: no space before parentheses (except after a control-flow |
571 | keyword) is near-universal practice for C++. It identifies the | |
572 | parentheses as the function-call operator or declarator, as | |
573 | opposed to an expression or other overloaded use of parentheses. | |
8a165db0 | 574 | |
c9024a78 BK |
575 | 04. Template function indentation |
576 | template<typename T> | |
577 | void | |
578 | template_function(args) | |
579 | { } | |
8a165db0 | 580 | -NOT- |
c9024a78 BK |
581 | template<class T> |
582 | void template_function(args) {}; | |
583 | ||
584 | Reason: In class definitions, without indentation whitespace is | |
585 | needed both above and below the declaration to distinguish | |
586 | it visually from other members. (Also, re: "typename" | |
587 | rather than "class".) T often could be int, which is | |
588 | not a class. ("class", here, is an anachronism.) | |
589 | ||
590 | 05. Template class indentation | |
591 | template<typename _CharT, typename _Traits> | |
592 | class basic_ios : public ios_base | |
593 | { | |
594 | public: | |
8a165db0 | 595 | // Types: |
c9024a78 BK |
596 | }; |
597 | -NOT- | |
598 | template<class _CharT, class _Traits> | |
599 | class basic_ios : public ios_base | |
600 | { | |
601 | public: | |
8a165db0 | 602 | // Types: |
c9024a78 BK |
603 | }; |
604 | -NOT- | |
605 | template<class _CharT, class _Traits> | |
606 | class basic_ios : public ios_base | |
607 | { | |
608 | public: | |
8a165db0 | 609 | // Types: |
c9024a78 BK |
610 | }; |
611 | ||
612 | 06. Enumerators | |
613 | enum | |
614 | { | |
615 | space = _ISspace, | |
616 | print = _ISprint, | |
617 | cntrl = _IScntrl | |
618 | }; | |
619 | -NOT- | |
620 | enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl }; | |
621 | ||
622 | 07. Member initialization lists | |
623 | All one line, separate from class name. | |
624 | ||
625 | gribble::gribble() | |
626 | : _M_private_data(0), _M_more_stuff(0), _M_helper(0); | |
627 | { } | |
628 | -NOT- | |
629 | gribble::gribble() : _M_private_data(0), _M_more_stuff(0), _M_helper(0); | |
630 | { } | |
631 | ||
632 | 08. Try/Catch blocks | |
633 | try | |
634 | { | |
8a165db0 | 635 | // |
c9024a78 BK |
636 | } |
637 | catch (...) | |
638 | { | |
8a165db0 | 639 | // |
c9024a78 BK |
640 | } |
641 | -NOT- | |
642 | try { | |
643 | // | |
644 | } catch(...) { | |
645 | // | |
646 | } | |
8a165db0 | 647 | |
c9024a78 BK |
648 | 09. Member functions declarations and definitions |
649 | Keywords such as extern, static, export, explicit, inline, etc | |
650 | go on the line above the function name. Thus | |
8a165db0 | 651 | |
c9024a78 BK |
652 | virtual int |
653 | foo() | |
654 | -NOT- | |
655 | virtual int foo() | |
8a165db0 | 656 | |
c9024a78 BK |
657 | Reason: GNU coding conventions dictate return types for functions |
658 | are on a separate line than the function name and parameter list | |
659 | for definitions. For C++, where we have member functions that can | |
660 | be either inline definitions or declarations, keeping to this | |
661 | standard allows all member function names for a given class to be | |
4394b61e | 662 | aligned to the same margin, increasing readability. |
8a165db0 BK |
663 | |
664 | ||
c9024a78 BK |
665 | 10. Invocation of member functions with "this->" |
666 | For non-uglified names, use this->name to call the function. | |
8a165db0 | 667 | |
c9024a78 BK |
668 | this->sync() |
669 | -NOT- | |
670 | sync() | |
8a165db0 | 671 | |
c9024a78 | 672 | Reason: Koenig lookup. |
8a165db0 | 673 | |
c9024a78 BK |
674 | 11. Namespaces |
675 | namespace std | |
676 | { | |
677 | blah blah blah; | |
678 | } // namespace std | |
8a165db0 | 679 | |
c9024a78 | 680 | -NOT- |
8a165db0 | 681 | |
c9024a78 BK |
682 | namespace std { |
683 | blah blah blah; | |
684 | } // namespace std | |
8a165db0 | 685 | |
c9024a78 BK |
686 | 12. Spacing under protected and private in class declarations: |
687 | space above, none below | |
4394b61e | 688 | i.e. |
8a165db0 | 689 | |
c9024a78 BK |
690 | public: |
691 | int foo; | |
8a165db0 | 692 | |
c9024a78 BK |
693 | -NOT- |
694 | public: | |
695 | ||
696 | int foo; | |
8a165db0 | 697 | |
c9024a78 BK |
698 | 13. Spacing WRT return statements. |
699 | no extra spacing before returns, no parenthesis | |
4394b61e | 700 | i.e. |
8a165db0 | 701 | |
c9024a78 BK |
702 | } |
703 | return __ret; | |
8a165db0 | 704 | |
c9024a78 BK |
705 | -NOT- |
706 | } | |
8a165db0 | 707 | |
c9024a78 | 708 | return __ret; |
8a165db0 | 709 | |
c9024a78 | 710 | -NOT- |
8a165db0 | 711 | |
c9024a78 BK |
712 | } |
713 | return (__ret); | |
8a165db0 BK |
714 | |
715 | ||
c9024a78 | 716 | 14. Location of global variables. |
4394b61e | 717 | All global variables of class type, whether in the "user visible" |
c9024a78 BK |
718 | space (e.g., cin) or the implementation namespace, must be defined |
719 | as a character array with the appropriate alignment and then later | |
720 | re-initialized to the correct value. | |
8a165db0 | 721 | |
c9024a78 BK |
722 | This is due to startup issues on certain platforms, such as AIX. |
723 | For more explanation and examples, see src/globals.cc. All such | |
724 | variables should be contained in that file, for simplicity. | |
8a165db0 | 725 | |
c9024a78 BK |
726 | 15. Exception abstractions |
727 | Use the exception abstractions found in functexcept.h, which allow | |
728 | C++ programmers to use this library with -fno-exceptions. (Even if | |
729 | that is rarely advisable, it's a necessary evil for backwards | |
730 | compatibility.) | |
8a165db0 | 731 | |
c9024a78 BK |
732 | 16. Exception error messages |
733 | All start with the name of the function where the exception is | |
734 | thrown, and then (optional) descriptive text is added. Example: | |
8a165db0 | 735 | |
c9024a78 | 736 | __throw_logic_error(__N("basic_string::_S_construct NULL not valid")); |
8a165db0 | 737 | |
c9024a78 BK |
738 | Reason: The verbose terminate handler prints out exception::what(), |
739 | as well as the typeinfo for the thrown exception. As this is the | |
740 | default terminate handler, by putting location info into the | |
741 | exception string, a very useful error message is printed out for | |
742 | uncaught exceptions. So useful, in fact, that non-programmers can | |
743 | give useful error messages, and programmers can intelligently | |
744 | speculate what went wrong without even using a debugger. | |
8a165db0 | 745 | |
c9024a78 BK |
746 | 17. The doxygen style guide to comments is a separate document, |
747 | see index. | |
8a165db0 | 748 | |
c9024a78 BK |
749 | The library currently has a mixture of GNU-C and modern C++ coding |
750 | styles. The GNU C usages will be combed out gradually. | |
8a165db0 | 751 | |
c9024a78 | 752 | Name patterns: |
8a165db0 | 753 | |
c9024a78 BK |
754 | For nonstandard names appearing in Standard headers, we are constrained |
755 | to use names that begin with underscores. This is called "uglification". | |
756 | The convention is: | |
8a165db0 | 757 | |
c9024a78 | 758 | Local and argument names: __[a-z].* |
8a165db0 | 759 | |
c9024a78 | 760 | Examples: __count __ix __s1 |
8a165db0 | 761 | |
c9024a78 | 762 | Type names and template formal-argument names: _[A-Z][^_].* |
8a165db0 | 763 | |
c9024a78 | 764 | Examples: _Helper _CharT _N |
8a165db0 | 765 | |
c9024a78 | 766 | Member data and function names: _M_.* |
8a165db0 | 767 | |
c9024a78 | 768 | Examples: _M_num_elements _M_initialize () |
8a165db0 | 769 | |
c9024a78 | 770 | Static data members, constants, and enumerations: _S_.* |
8a165db0 | 771 | |
c9024a78 | 772 | Examples: _S_max_elements _S_default_value |
8a165db0 | 773 | |
c9024a78 BK |
774 | Don't use names in the same scope that differ only in the prefix, |
775 | e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names. | |
776 | (The most tempting of these seem to be and "_T" and "__sz".) | |
8a165db0 | 777 | |
c9024a78 BK |
778 | Names must never have "__" internally; it would confuse name |
779 | unmanglers on some targets. Also, never use "__[0-9]", same reason. | |
8a165db0 | 780 | |
c9024a78 | 781 | -------------------------- |
8a165db0 | 782 | |
c9024a78 BK |
783 | [BY EXAMPLE] |
784 | ||
785 | #ifndef _HEADER_ | |
786 | #define _HEADER_ 1 | |
8a165db0 | 787 | |
c9024a78 BK |
788 | namespace std |
789 | { | |
790 | class gribble | |
791 | { | |
792 | public: | |
793 | gribble() throw(); | |
8a165db0 | 794 | |
c9024a78 | 795 | gribble(const gribble&); |
8a165db0 | 796 | |
c9024a78 BK |
797 | explicit |
798 | gribble(int __howmany); | |
8a165db0 | 799 | |
c9024a78 BK |
800 | gribble& |
801 | operator=(const gribble&); | |
8a165db0 | 802 | |
c9024a78 BK |
803 | virtual |
804 | ~gribble() throw (); | |
8a165db0 | 805 | |
c9024a78 BK |
806 | // Start with a capital letter, end with a period. |
807 | inline void | |
808 | public_member(const char* __arg) const; | |
8a165db0 | 809 | |
c9024a78 BK |
810 | // In-class function definitions should be restricted to one-liners. |
811 | int | |
812 | one_line() { return 0 } | |
8a165db0 | 813 | |
c9024a78 BK |
814 | int |
815 | two_lines(const char* arg) | |
816 | { return strchr(arg, 'a'); } | |
8a165db0 | 817 | |
c9024a78 BK |
818 | inline int |
819 | three_lines(); // inline, but defined below. | |
8a165db0 | 820 | |
c9024a78 BK |
821 | // Note indentation. |
822 | template<typename _Formal_argument> | |
8a165db0 BK |
823 | void |
824 | public_template() const throw(); | |
825 | ||
c9024a78 | 826 | template<typename _Iterator> |
8a165db0 BK |
827 | void |
828 | other_template(); | |
829 | ||
c9024a78 BK |
830 | private: |
831 | class _Helper; | |
8a165db0 | 832 | |
c9024a78 BK |
833 | int _M_private_data; |
834 | int _M_more_stuff; | |
835 | _Helper* _M_helper; | |
836 | int _M_private_function(); | |
8a165db0 | 837 | |
c9024a78 | 838 | enum _Enum |
8a165db0 | 839 | { |
c9024a78 BK |
840 | _S_one, |
841 | _S_two | |
8a165db0 BK |
842 | }; |
843 | ||
c9024a78 BK |
844 | static void |
845 | _S_initialize_library(); | |
846 | }; | |
8a165db0 | 847 | |
c9024a78 BK |
848 | // More-or-less-standard language features described by lack, not presence. |
849 | # ifndef _G_NO_LONGLONG | |
850 | extern long long _G_global_with_a_good_long_name; // avoid globals! | |
851 | # endif | |
8a165db0 | 852 | |
c9024a78 BK |
853 | // Avoid in-class inline definitions, define separately; |
854 | // likewise for member class definitions: | |
855 | inline int | |
856 | gribble::public_member() const | |
857 | { int __local = 0; return __local; } | |
8a165db0 | 858 | |
c9024a78 BK |
859 | class gribble::_Helper |
860 | { | |
861 | int _M_stuff; | |
8a165db0 | 862 | |
c9024a78 BK |
863 | friend class gribble; |
864 | }; | |
865 | } | |
8a165db0 | 866 | |
c9024a78 BK |
867 | // Names beginning with "__": only for arguments and |
868 | // local variables; never use "__" in a type name, or | |
869 | // within any name; never use "__[0-9]". | |
8a165db0 | 870 | |
c9024a78 | 871 | #endif /* _HEADER_ */ |
8a165db0 BK |
872 | |
873 | ||
c9024a78 BK |
874 | namespace std |
875 | { | |
876 | template<typename T> // notice: "typename", not "class", no space | |
877 | long_return_value_type<with_many, args> | |
878 | function_name(char* pointer, // "char *pointer" is wrong. | |
879 | char* argument, | |
880 | const Reference& ref) | |
881 | { | |
8a165db0 BK |
882 | // int a_local; /* wrong; see below. */ |
883 | if (test) | |
884 | { | |
c9024a78 | 885 | nested code |
8a165db0 | 886 | } |
c9024a78 | 887 | |
8a165db0 BK |
888 | int a_local = 0; // declare variable at first use. |
889 | ||
890 | // char a, b, *p; /* wrong */ | |
891 | char a = 'a'; | |
892 | char b = a + 1; | |
893 | char* c = "abc"; // each variable goes on its own line, always. | |
894 | ||
895 | // except maybe here... | |
896 | for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1) { | |
c9024a78 | 897 | // ... |
8a165db0 | 898 | } |
c9024a78 BK |
899 | } |
900 | ||
901 | gribble::gribble() | |
902 | : _M_private_data(0), _M_more_stuff(0), _M_helper(0); | |
903 | { } | |
904 | ||
905 | inline int | |
906 | gribble::three_lines() | |
907 | { | |
908 | // doesn't fit in one line. | |
909 | } | |
910 | } // namespace std | |
911 | </literallayout> | |
912 | </sect2> | |
913 | </sect1> | |
914 | ||
915 | <sect1 id="contrib.doc_style" xreflabel="Documentation Style"> | |
5e623d0b | 916 | <?dbhtml filename="documentation_style.html"?> |
c9024a78 BK |
917 | <title>Documentation Style</title> |
918 | <sect2 id="doc_style.doxygen" xreflabel="doc_style.doxygen"> | |
919 | <title>Doxygen</title> | |
920 | <sect3 id="doxygen.prereq" xreflabel="doxygen.prereq"> | |
921 | <title>Prerequisites</title> | |
922 | <para> | |
923 | Prerequisite tools are Bash 2.x, | |
924 | <ulink url="http://www.doxygen.org/">Doxygen</ulink>, and | |
925 | the <ulink url="http://www.gnu.org/software/coreutils/">GNU | |
926 | coreutils</ulink>. (GNU versions of find, xargs, and possibly | |
927 | sed and grep are used, just because the GNU versions make | |
928 | things very easy.) | |
929 | </para> | |
8a165db0 | 930 | |
c9024a78 BK |
931 | <para> |
932 | To generate the pretty pictures and hierarchy | |
933 | graphs, the | |
934 | <ulink url="http://www.research.att.com/sw/tools/graphviz/download.html">Graphviz</ulink> | |
935 | package will need to be installed. | |
936 | </para> | |
937 | </sect3> | |
8a165db0 | 938 | |
c9024a78 | 939 | <sect3 id="doxygen.rules" xreflabel="doxygen.rules"> |
8a165db0 | 940 | <title>Generating the Doxygen Files</title> |
c9024a78 | 941 | <para> |
0075846f BK |
942 | The following Makefile rules run Doxygen to generate HTML |
943 | docs, XML docs, and the man pages. | |
c9024a78 | 944 | </para> |
0075846f | 945 | |
c9024a78 | 946 | <para> |
0075846f | 947 | <screen><userinput>make doc-html-doxygen</userinput></screen> |
c9024a78 | 948 | </para> |
0075846f | 949 | |
c9024a78 | 950 | <para> |
0075846f | 951 | <screen><userinput>make doc-xml-doxygen</userinput></screen> |
c9024a78 | 952 | </para> |
0075846f | 953 | |
c9024a78 | 954 | <para> |
0075846f | 955 | <screen><userinput>make doc-man-doxygen</userinput></screen> |
c9024a78 | 956 | </para> |
8a165db0 | 957 | |
c9024a78 BK |
958 | <para> |
959 | Careful observers will see that the Makefile rules simply call | |
960 | a script from the source tree, <filename>run_doxygen</filename>, which | |
961 | does the actual work of running Doxygen and then (most | |
962 | importantly) massaging the output files. If for some reason | |
963 | you prefer to not go through the Makefile, you can call this | |
964 | script directly. (Start by passing <literal>--help</literal>.) | |
965 | </para> | |
8a165db0 | 966 | |
c9024a78 BK |
967 | <para> |
968 | If you wish to tweak the Doxygen settings, do so by editing | |
969 | <filename>doc/doxygen/user.cfg.in</filename>. Notes to fellow | |
970 | library hackers are written in triple-# comments. | |
971 | </para> | |
8a165db0 BK |
972 | |
973 | </sect3> | |
974 | ||
975 | <sect3 id="doxygen.markup" xreflabel="doxygen.markup"> | |
976 | <title>Markup</title> | |
977 | ||
c9024a78 BK |
978 | <para> |
979 | In general, libstdc++ files should be formatted according to | |
980 | the rules found in the | |
981 | <link linkend="contrib.coding_style">Coding Standard</link>. Before | |
982 | any doxygen-specific formatting tweaks are made, please try to | |
983 | make sure that the initial formatting is sound. | |
984 | </para> | |
8a165db0 | 985 | |
c9024a78 BK |
986 | <para> |
987 | Adding Doxygen markup to a file (informally called | |
988 | <quote>doxygenating</quote>) is very simple. The Doxygen manual can be | |
989 | found | |
990 | <ulink url="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</ulink>. | |
991 | We try to use a very-recent version of Doxygen. | |
992 | </para> | |
8a165db0 | 993 | |
c9024a78 BK |
994 | <para> |
995 | For classes, use | |
996 | <classname>deque</classname>/<classname>vector</classname>/<classname>list</classname> | |
997 | and <classname>std::pair</classname> as examples. For | |
998 | functions, see their member functions, and the free functions | |
999 | in <filename>stl_algobase.h</filename>. Member functions of | |
1000 | other container-like types should read similarly to these | |
1001 | member functions. | |
1002 | </para> | |
8a165db0 | 1003 | |
c9024a78 BK |
1004 | <para> |
1005 | These points accompany the first list in section 3.1 of the | |
1006 | Doxygen manual: | |
1007 | </para> | |
8a165db0 | 1008 | |
c9024a78 BK |
1009 | <orderedlist> |
1010 | <listitem><para>Use the Javadoc style...</para></listitem> | |
1011 | <listitem> | |
1012 | <para> | |
1013 | ...not the Qt style. The intermediate *'s are preferred. | |
1014 | </para> | |
1015 | </listitem> | |
1016 | <listitem> | |
1017 | <para> | |
1018 | Use the triple-slash style only for one-line comments (the | |
1019 | <quote>brief</quote> mode). Very recent versions of Doxygen permit | |
1020 | full-mode comments in triple-slash blocks, but the | |
1021 | formatting still comes out wonky. | |
1022 | </para> | |
1023 | </listitem> | |
1024 | <listitem> | |
1025 | <para> | |
1026 | This is disgusting. Don't do this. | |
1027 | </para> | |
1028 | </listitem> | |
1029 | </orderedlist> | |
8a165db0 | 1030 | |
c9024a78 BK |
1031 | <para> |
1032 | Use the @-style of commands, not the !-style. Please be | |
1033 | careful about whitespace in your markup comments. Most of the | |
1034 | time it doesn't matter; doxygen absorbs most whitespace, and | |
1035 | both HTML and *roff are agnostic about whitespace. However, | |
1036 | in <pre> blocks and @code/@endcode sections, spacing can | |
1037 | have <quote>interesting</quote> effects. | |
1038 | </para> | |
1039 | ||
1040 | <para> | |
1041 | Use either kind of grouping, as | |
1042 | appropriate. <filename>doxygroups.cc</filename> exists for this | |
1043 | purpose. See <filename>stl_iterator.h</filename> for a good example | |
1044 | of the <quote>other</quote> kind of grouping. | |
1045 | </para> | |
1046 | ||
1047 | <para> | |
1048 | Please use markup tags like @p and @a when referring to things | |
1049 | such as the names of function parameters. Use @e for emphasis | |
1050 | when necessary. Use @c to refer to other standard names. | |
1051 | (Examples of all these abound in the present code.) | |
1052 | </para> | |
8a165db0 BK |
1053 | |
1054 | </sect3> | |
1055 | ||
c9024a78 | 1056 | </sect2> |
8a165db0 | 1057 | |
c9024a78 BK |
1058 | <sect2 id="doc_style.docbook" xreflabel="doc_style.docbook"> |
1059 | <title>Docbook</title> | |
8a165db0 | 1060 | |
c9024a78 BK |
1061 | <sect3 id="docbook.prereq" xreflabel="docbook.prereq"> |
1062 | <title>Prerequisites</title> | |
1063 | <para> | |
1064 | Editing the DocBook sources requires an XML editor. Many | |
4394b61e | 1065 | exist: some notable options |
c9024a78 BK |
1066 | include <command>emacs</command>, <application>Kate</application>, |
1067 | or <application>Conglomerate</application>. | |
1068 | </para> | |
8a165db0 | 1069 | |
c9024a78 BK |
1070 | <para> |
1071 | Some editors support special <quote>XML Validation</quote> | |
1072 | modes that can validate the file as it is | |
1073 | produced. Recommended is the <command>nXML Mode</command> | |
1074 | for <command>emacs</command>. | |
1075 | </para> | |
8a165db0 | 1076 | |
c9024a78 BK |
1077 | <para> |
1078 | Besides an editor, additional DocBook files and XML tools are | |
1079 | also required. | |
1080 | </para> | |
8a165db0 | 1081 | |
c9024a78 BK |
1082 | <para> |
1083 | Access to the DocBook stylesheets and DTD is required. The | |
1084 | stylesheets are usually packaged by vendor, in something | |
0075846f BK |
1085 | like <filename>docbook-style-xsl</filename>. To exactly match |
1086 | generated output, please use a version of the stylesheets | |
1087 | equivalent | |
1088 | to <filename>docbook-style-xsl-1.74.0-5</filename>. The | |
1089 | installation directory for this package corresponds to | |
c9024a78 BK |
1090 | the <literal>XSL_STYLE_DIR</literal> |
1091 | in <filename>doc/Makefile.am</filename> and defaults | |
1092 | to <filename class="directory">/usr/share/sgml/docbook/xsl-stylesheets</filename>. | |
1093 | </para> | |
8a165db0 | 1094 | |
c9024a78 | 1095 | <para> |
4394b61e | 1096 | For processing XML, an XML processor and some style |
c9024a78 BK |
1097 | sheets are necessary. Defaults are <command>xsltproc</command> |
1098 | provided by <filename>libxslt</filename>. | |
1099 | </para> | |
8a165db0 | 1100 | |
c9024a78 BK |
1101 | <para> |
1102 | For validating the XML document, you'll need | |
1103 | something like <command>xmllint</command> and access to the | |
1104 | DocBook DTD. These are provided | |
1105 | by a vendor package like <filename>lixml2</filename>. | |
1106 | </para> | |
8a165db0 | 1107 | |
c9024a78 BK |
1108 | <para> |
1109 | For PDF output, something that transforms valid XML to PDF is | |
1110 | required. Possible solutions include <command>xmlto</command>, | |
1111 | <ulink url="http://xmlgraphics.apache.org/fop/">Apache | |
1112 | FOP</ulink>, or <command>prince</command>. Other options are | |
1113 | listed on the DocBook web <ulink | |
1114 | url="http://wiki.docbook.org/topic/DocBookPublishingTools">pages</ulink>. Please | |
1115 | consult the <email>libstdc++@gcc.gnu.org</email> list when | |
1116 | preparing printed manuals for current best practice and suggestions. | |
1117 | </para> | |
1118 | ||
1119 | <para> | |
1120 | Make sure that the XML documentation and markup is valid for | |
1121 | any change. This can be done easily, with the validation rules | |
1122 | in the <filename>Makefile</filename>, which is equivalent to doing: | |
1123 | </para> | |
1124 | ||
1125 | <screen> | |
1126 | <userinput> | |
1127 | xmllint --noout --valid <filename>xml/index.xml</filename> | |
1128 | </userinput> | |
1129 | </screen> | |
1130 | </sect3> | |
1131 | ||
1132 | <sect3 id="docbook.rules" xreflabel="docbook.rules"> | |
1133 | <title>Generating the DocBook Files</title> | |
1134 | ||
1135 | <para> | |
0075846f BK |
1136 | The following Makefile rules generate (in order): an HTML |
1137 | version of all the documentation, a PDF version of the same, a | |
1138 | single XML document, and the result of validating the entire XML | |
1139 | document. | |
c9024a78 | 1140 | </para> |
0075846f | 1141 | |
c9024a78 | 1142 | <para> |
0075846f | 1143 | <screen><userinput>make doc-html</userinput></screen> |
c9024a78 | 1144 | </para> |
0075846f | 1145 | |
c9024a78 | 1146 | <para> |
0075846f | 1147 | <screen><userinput>make doc-pdf</userinput></screen> |
c9024a78 | 1148 | </para> |
0075846f | 1149 | |
c9024a78 | 1150 | <para> |
0075846f | 1151 | <screen><userinput>make doc-xml-single</userinput></screen> |
c9024a78 | 1152 | </para> |
8a165db0 | 1153 | |
c9024a78 | 1154 | <para> |
0075846f | 1155 | <screen><userinput>make doc-xml-validate</userinput></screen> |
c9024a78 | 1156 | </para> |
0075846f | 1157 | |
c9024a78 | 1158 | </sect3> |
8a165db0 | 1159 | |
c9024a78 BK |
1160 | <sect3 id="docbook.examples" xreflabel="docbook.examples"> |
1161 | <title>File Organization and Basics</title> | |
8a165db0 | 1162 | |
c9024a78 BK |
1163 | <literallayout> |
1164 | <emphasis>Which files are important</emphasis> | |
8a165db0 | 1165 | |
c9024a78 BK |
1166 | All Docbook files are in the directory |
1167 | libstdc++-v3/doc/xml | |
8a165db0 | 1168 | |
c9024a78 BK |
1169 | Inside this directory, the files of importance: |
1170 | spine.xml - index to documentation set | |
1171 | manual/spine.xml - index to manual | |
1172 | manual/*.xml - individual chapters and sections of the manual | |
1173 | faq.xml - index to FAQ | |
1174 | api.xml - index to source level / API | |
8a165db0 | 1175 | |
4394b61e | 1176 | All *.txml files are template xml files, i.e., otherwise empty files with |
c9024a78 | 1177 | the correct structure, suitable for filling in with new information. |
8a165db0 | 1178 | |
4394b61e | 1179 | <emphasis>Canonical Writing Style</emphasis> |
8a165db0 | 1180 | |
c9024a78 BK |
1181 | class template |
1182 | function template | |
1183 | member function template | |
1184 | (via C++ Templates, Vandevoorde) | |
8a165db0 | 1185 | |
c9024a78 | 1186 | class in namespace std: allocator, not std::allocator |
8a165db0 | 1187 | |
c9024a78 | 1188 | header file: iostream, not <iostream> |
8a165db0 | 1189 | |
8a165db0 | 1190 | |
c9024a78 | 1191 | <emphasis>General structure</emphasis> |
8a165db0 | 1192 | |
c9024a78 BK |
1193 | <set> |
1194 | <book> | |
1195 | </book> | |
8a165db0 | 1196 | |
c9024a78 BK |
1197 | <book> |
1198 | <chapter> | |
1199 | </chapter> | |
1200 | </book> | |
8a165db0 | 1201 | |
c9024a78 BK |
1202 | <book> |
1203 | <part> | |
1204 | <chapter> | |
1205 | <section> | |
1206 | </section> | |
8a165db0 | 1207 | |
c9024a78 BK |
1208 | <sect1> |
1209 | </sect1> | |
8a165db0 | 1210 | |
c9024a78 BK |
1211 | <sect1> |
1212 | <sect2> | |
1213 | </sect2> | |
1214 | </sect1> | |
1215 | </chapter> | |
8a165db0 | 1216 | |
c9024a78 BK |
1217 | <chapter> |
1218 | </chapter> | |
1219 | </part> | |
1220 | </book> | |
8a165db0 | 1221 | |
c9024a78 BK |
1222 | </set> |
1223 | </literallayout> | |
1224 | </sect3> | |
8a165db0 | 1225 | |
c9024a78 BK |
1226 | <sect3 id="docbook.markup" xreflabel="docbook.markup"> |
1227 | <title>Markup By Example</title> | |
8a165db0 | 1228 | |
0075846f BK |
1229 | <para> |
1230 | Complete details on Docbook markup can be found in the DocBook Element | |
1231 | Reference, <ulink url="http://www.docbook.org/tdg/en/html/part2.html">online</ulink>. An | |
1232 | incomplete reference for HTML to Docbook conversion is detailed in the | |
1233 | table below. | |
1234 | </para> | |
8a165db0 | 1235 | |
0075846f BK |
1236 | <table frame='all'> |
1237 | <title>HTML to Docbook XML markup comparison</title> | |
1238 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | |
1239 | <colspec colname='c1'></colspec> | |
1240 | <colspec colname='c2'></colspec> | |
1241 | ||
1242 | <thead> | |
1243 | <row> | |
1244 | <entry>HTML</entry> | |
1245 | <entry>XML</entry> | |
1246 | </row> | |
1247 | </thead> | |
1248 | ||
1249 | <tbody> | |
1250 | <row> | |
1251 | <entry><p></entry> | |
1252 | <entry><para></entry> | |
1253 | </row> | |
1254 | <row> | |
1255 | <entry><pre></entry> | |
1256 | <entry><computeroutput>, <programlisting>, | |
1257 | <literallayout></entry> | |
1258 | </row> | |
1259 | <row> | |
1260 | <entry><ul></entry> | |
1261 | <entry><itemizedlist></entry> | |
1262 | </row> | |
1263 | <row> | |
1264 | <entry><ol></entry> | |
1265 | <entry><orderedlist></entry> | |
1266 | </row> | |
1267 | <row> | |
1268 | <entry><il></entry> | |
1269 | <entry><listitem></entry> | |
1270 | </row> | |
1271 | <row> | |
1272 | <entry><dl></entry> | |
1273 | <entry><variablelist></entry> | |
1274 | </row> | |
1275 | <row> | |
1276 | <entry><dt></entry> | |
1277 | <entry><term></entry> | |
1278 | </row> | |
1279 | <row> | |
1280 | <entry><dd></entry> | |
1281 | <entry><listitem></entry> | |
1282 | </row> | |
1283 | ||
1284 | <row> | |
1285 | <entry><a href=""></entry> | |
1286 | <entry><ulink url=""></entry> | |
1287 | </row> | |
1288 | <row> | |
1289 | <entry><code></entry> | |
1290 | <entry><literal>, <programlisting></entry> | |
1291 | </row> | |
1292 | <row> | |
1293 | <entry><strong></entry> | |
1294 | <entry><emphasis></entry> | |
1295 | </row> | |
1296 | <row> | |
1297 | <entry><em></entry> | |
1298 | <entry><emphasis></entry> | |
1299 | </row> | |
1300 | <row> | |
1301 | <entry>"</entry> | |
1302 | <entry><quote></entry> | |
1303 | </row> | |
1304 | </tbody> | |
1305 | </tgroup> | |
1306 | </table> | |
1307 | ||
1308 | <para> | |
1309 | And examples of detailed markup for which there are no real HTML | |
1310 | equivalents are listed in the table below. | |
1311 | </para> | |
8a165db0 | 1312 | |
0075846f BK |
1313 | <table frame='all'> |
1314 | <title>Docbook XML Element Use</title> | |
1315 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | |
1316 | <colspec colname='c1'></colspec> | |
1317 | <colspec colname='c2'></colspec> | |
1318 | ||
1319 | <thead> | |
1320 | <row> | |
1321 | <entry>Element</entry> | |
1322 | <entry>Use</entry> | |
1323 | </row> | |
1324 | </thead> | |
1325 | ||
1326 | <tbody> | |
1327 | <row> | |
1328 | <entry><structname></entry> | |
1329 | <entry><structname>char_traits</structname></entry> | |
1330 | </row> | |
1331 | <row> | |
1332 | <entry><classname></entry> | |
1333 | <entry><classname>string</classname></entry> | |
1334 | </row> | |
1335 | <row> | |
1336 | <entry><function></entry> | |
1337 | <entry> | |
1338 | <para><function>clear()</function></para> | |
1339 | <para><function>fs.clear()</function></para> | |
1340 | </entry> | |
1341 | </row> | |
1342 | <row> | |
1343 | <entry><type></entry> | |
1344 | <entry><type>long long</type></entry> | |
1345 | </row> | |
1346 | <row> | |
1347 | <entry><varname></entry> | |
1348 | <entry><varname>fs</varname></entry> | |
1349 | </row> | |
1350 | <row> | |
1351 | <entry><literal></entry> | |
1352 | <entry> | |
1353 | <para><literal>-Weffc++</literal></para> | |
1354 | <para><literal>rel_ops</literal></para> | |
1355 | </entry> | |
1356 | </row> | |
1357 | <row> | |
1358 | <entry><constant></entry> | |
1359 | <entry> | |
1360 | <para><constant>_GNU_SOURCE</constant></para> | |
1361 | <para><constant>3.0</constant></para> | |
1362 | </entry> | |
1363 | </row> | |
1364 | <row> | |
1365 | <entry><command></entry> | |
1366 | <entry><command>g++</command></entry> | |
1367 | </row> | |
1368 | <row> | |
1369 | <entry><errortext></entry> | |
1370 | <entry><errortext>In instantiation of</errortext></entry> | |
1371 | </row> | |
1372 | <row> | |
1373 | <entry><filename></entry> | |
1374 | <entry> | |
1375 | <para><filename class="headerfile">ctype.h</filename></para> | |
1376 | <para><filename class="directory">/home/gcc/build</filename></para> | |
1377 | </entry> | |
1378 | </row> | |
1379 | </tbody> | |
1380 | </tgroup> | |
1381 | </table> | |
8a165db0 | 1382 | |
c9024a78 BK |
1383 | </sect3> |
1384 | </sect2> | |
1385 | ||
1386 | </sect1> | |
1387 | ||
1388 | <sect1 id="contrib.design_notes" xreflabel="Design Notes"> | |
5e623d0b | 1389 | <?dbhtml filename="source_design_notes.html"?> |
c9024a78 BK |
1390 | <title>Design Notes</title> |
1391 | <para> | |
1392 | </para> | |
1393 | ||
1394 | <literallayout> | |
1395 | ||
1396 | The Library | |
1397 | ----------- | |
1398 | ||
1399 | This paper is covers two major areas: | |
1400 | ||
1401 | - Features and policies not mentioned in the standard that | |
1402 | the quality of the library implementation depends on, including | |
1403 | extensions and "implementation-defined" features; | |
1404 | ||
1405 | - Plans for required but unimplemented library features and | |
1406 | optimizations to them. | |
1407 | ||
1408 | Overhead | |
1409 | -------- | |
1410 | ||
1411 | The standard defines a large library, much larger than the standard | |
1412 | C library. A naive implementation would suffer substantial overhead | |
1413 | in compile time, executable size, and speed, rendering it unusable | |
1414 | in many (particularly embedded) applications. The alternative demands | |
1415 | care in construction, and some compiler support, but there is no | |
1416 | need for library subsets. | |
1417 | ||
1418 | What are the sources of this overhead? There are four main causes: | |
1419 | ||
1420 | - The library is specified almost entirely as templates, which | |
1421 | with current compilers must be included in-line, resulting in | |
1422 | very slow builds as tens or hundreds of thousands of lines | |
1423 | of function definitions are read for each user source file. | |
1424 | Indeed, the entire SGI STL, as well as the dos Reis valarray, | |
1425 | are provided purely as header files, largely for simplicity in | |
1426 | porting. Iostream/locale is (or will be) as large again. | |
1427 | ||
1428 | - The library is very flexible, specifying a multitude of hooks | |
1429 | where users can insert their own code in place of defaults. | |
1430 | When these hooks are not used, any time and code expended to | |
1431 | support that flexibility is wasted. | |
1432 | ||
1433 | - Templates are often described as causing to "code bloat". In | |
1434 | practice, this refers (when it refers to anything real) to several | |
1435 | independent processes. First, when a class template is manually | |
1436 | instantiated in its entirely, current compilers place the definitions | |
1437 | for all members in a single object file, so that a program linking | |
1438 | to one member gets definitions of all. Second, template functions | |
1439 | which do not actually depend on the template argument are, under | |
1440 | current compilers, generated anew for each instantiation, rather | |
1441 | than being shared with other instantiations. Third, some of the | |
1442 | flexibility mentioned above comes from virtual functions (both in | |
1443 | regular classes and template classes) which current linkers add | |
1444 | to the executable file even when they manifestly cannot be called. | |
1445 | ||
1446 | - The library is specified to use a language feature, exceptions, | |
1447 | which in the current gcc compiler ABI imposes a run time and | |
1448 | code space cost to handle the possibility of exceptions even when | |
1449 | they are not used. Under the new ABI (accessed with -fnew-abi), | |
1450 | there is a space overhead and a small reduction in code efficiency | |
1451 | resulting from lost optimization opportunities associated with | |
1452 | non-local branches associated with exceptions. | |
1453 | ||
1454 | What can be done to eliminate this overhead? A variety of coding | |
1455 | techniques, and compiler, linker and library improvements and | |
1456 | extensions may be used, as covered below. Most are not difficult, | |
1457 | and some are already implemented in varying degrees. | |
1458 | ||
1459 | Overhead: Compilation Time | |
1460 | -------------------------- | |
1461 | ||
1462 | Providing "ready-instantiated" template code in object code archives | |
1463 | allows us to avoid generating and optimizing template instantiations | |
1464 | in each compilation unit which uses them. However, the number of such | |
1465 | instantiations that are useful to provide is limited, and anyway this | |
1466 | is not enough, by itself, to minimize compilation time. In particular, | |
1467 | it does not reduce time spent parsing conforming headers. | |
1468 | ||
1469 | Quicker header parsing will depend on library extensions and compiler | |
1470 | improvements. One approach is some variation on the techniques | |
1471 | previously marketed as "pre-compiled headers", now standardized as | |
1472 | support for the "export" keyword. "Exported" template definitions | |
1473 | can be placed (once) in a "repository" -- really just a library, but | |
1474 | of template definitions rather than object code -- to be drawn upon | |
1475 | at link time when an instantiation is needed, rather than placed in | |
1476 | header files to be parsed along with every compilation unit. | |
1477 | ||
1478 | Until "export" is implemented we can put some of the lengthy template | |
1479 | definitions in #if guards or alternative headers so that users can skip | |
1480 | over the full definitions when they need only the ready-instantiated | |
1481 | specializations. | |
1482 | ||
1483 | To be precise, this means that certain headers which define | |
1484 | templates which users normally use only for certain arguments | |
1485 | can be instrumented to avoid exposing the template definitions | |
1486 | to the compiler unless a macro is defined. For example, in | |
1487 | <string>, we might have: | |
1488 | ||
1489 | template <class _CharT, ... > class basic_string { | |
1490 | ... // member declarations | |
1491 | }; | |
1492 | ... // operator declarations | |
1493 | ||
1494 | #ifdef _STRICT_ISO_ | |
1495 | # if _G_NO_TEMPLATE_EXPORT | |
1496 | # include <bits/std_locale.h> // headers needed by definitions | |
1497 | # ... | |
1498 | # include <bits/string.tcc> // member and global template definitions. | |
1499 | # endif | |
1500 | #endif | |
1501 | ||
1502 | Users who compile without specifying a strict-ISO-conforming flag | |
1503 | would not see many of the template definitions they now see, and rely | |
1504 | instead on ready-instantiated specializations in the library. This | |
1505 | technique would be useful for the following substantial components: | |
1506 | string, locale/iostreams, valarray. It would *not* be useful or | |
1507 | usable with the following: containers, algorithms, iterators, | |
1508 | allocator. Since these constitute a large (though decreasing) | |
1509 | fraction of the library, the benefit the technique offers is | |
1510 | limited. | |
1511 | ||
1512 | The language specifies the semantics of the "export" keyword, but | |
1513 | the gcc compiler does not yet support it. When it does, problems | |
1514 | with large template inclusions can largely disappear, given some | |
1515 | minor library reorganization, along with the need for the apparatus | |
1516 | described above. | |
1517 | ||
1518 | Overhead: Flexibility Cost | |
1519 | -------------------------- | |
1520 | ||
1521 | The library offers many places where users can specify operations | |
1522 | to be performed by the library in place of defaults. Sometimes | |
1523 | this seems to require that the library use a more-roundabout, and | |
1524 | possibly slower, way to accomplish the default requirements than | |
1525 | would be used otherwise. | |
1526 | ||
1527 | The primary protection against this overhead is thorough compiler | |
1528 | optimization, to crush out layers of inline function interfaces. | |
1529 | Kuck & Associates has demonstrated the practicality of this kind | |
1530 | of optimization. | |
1531 | ||
1532 | The second line of defense against this overhead is explicit | |
1533 | specialization. By defining helper function templates, and writing | |
1534 | specialized code for the default case, overhead can be eliminated | |
1535 | for that case without sacrificing flexibility. This takes full | |
1536 | advantage of any ability of the optimizer to crush out degenerate | |
1537 | code. | |
1538 | ||
1539 | The library specifies many virtual functions which current linkers | |
1540 | load even when they cannot be called. Some minor improvements to the | |
1541 | compiler and to ld would eliminate any such overhead by simply | |
1542 | omitting virtual functions that the complete program does not call. | |
1543 | A prototype of this work has already been done. For targets where | |
1544 | GNU ld is not used, a "pre-linker" could do the same job. | |
1545 | ||
1546 | The main areas in the standard interface where user flexibility | |
1547 | can result in overhead are: | |
1548 | ||
1549 | - Allocators: Containers are specified to use user-definable | |
1550 | allocator types and objects, making tuning for the container | |
1551 | characteristics tricky. | |
1552 | ||
1553 | - Locales: the standard specifies locale objects used to implement | |
1554 | iostream operations, involving many virtual functions which use | |
1555 | streambuf iterators. | |
1556 | ||
1557 | - Algorithms and containers: these may be instantiated on any type, | |
1558 | frequently duplicating code for identical operations. | |
1559 | ||
1560 | - Iostreams and strings: users are permitted to use these on their | |
1561 | own types, and specify the operations the stream must use on these | |
1562 | types. | |
1563 | ||
1564 | Note that these sources of overhead are _avoidable_. The techniques | |
1565 | to avoid them are covered below. | |
1566 | ||
1567 | Code Bloat | |
1568 | ---------- | |
1569 | ||
1570 | In the SGI STL, and in some other headers, many of the templates | |
1571 | are defined "inline" -- either explicitly or by their placement | |
1572 | in class definitions -- which should not be inline. This is a | |
1573 | source of code bloat. Matt had remarked that he was relying on | |
1574 | the compiler to recognize what was too big to benefit from inlining, | |
1575 | and generate it out-of-line automatically. However, this also can | |
1576 | result in code bloat except where the linker can eliminate the extra | |
1577 | copies. | |
1578 | ||
1579 | Fixing these cases will require an audit of all inline functions | |
1580 | defined in the library to determine which merit inlining, and moving | |
1581 | the rest out of line. This is an issue mainly in chapters 23, 25, and | |
1582 | 27. Of course it can be done incrementally, and we should generally | |
1583 | accept patches that move large functions out of line and into ".tcc" | |
1584 | files, which can later be pulled into a repository. Compiler/linker | |
1585 | improvements to recognize very large inline functions and move them | |
1586 | out-of-line, but shared among compilation units, could make this | |
1587 | work unnecessary. | |
1588 | ||
1589 | Pre-instantiating template specializations currently produces large | |
1590 | amounts of dead code which bloats statically linked programs. The | |
1591 | current state of the static library, libstdc++.a, is intolerable on | |
1592 | this account, and will fuel further confused speculation about a need | |
1593 | for a library "subset". A compiler improvement that treats each | |
1594 | instantiated function as a separate object file, for linking purposes, | |
1595 | would be one solution to this problem. An alternative would be to | |
1596 | split up the manual instantiation files into dozens upon dozens of | |
1597 | little files, each compiled separately, but an abortive attempt at | |
1598 | this was done for <string> and, though it is far from complete, it | |
1599 | is already a nuisance. A better interim solution (just until we have | |
1600 | "export") is badly needed. | |
1601 | ||
1602 | When building a shared library, the current compiler/linker cannot | |
4394b61e | 1603 | automatically generate the instantiations needed. This creates a |
c9024a78 BK |
1604 | miserable situation; it means any time something is changed in the |
1605 | library, before a shared library can be built someone must manually | |
1606 | copy the declarations of all templates that are needed by other parts | |
1607 | of the library to an "instantiation" file, and add it to the build | |
1608 | system to be compiled and linked to the library. This process is | |
1609 | readily automated, and should be automated as soon as possible. | |
1610 | Users building their own shared libraries experience identical | |
1611 | frustrations. | |
1612 | ||
1613 | Sharing common aspects of template definitions among instantiations | |
1614 | can radically reduce code bloat. The compiler could help a great | |
1615 | deal here by recognizing when a function depends on nothing about | |
1616 | a template parameter, or only on its size, and giving the resulting | |
1617 | function a link-name "equate" that allows it to be shared with other | |
1618 | instantiations. Implementation code could take advantage of the | |
1619 | capability by factoring out code that does not depend on the template | |
1620 | argument into separate functions to be merged by the compiler. | |
1621 | ||
1622 | Until such a compiler optimization is implemented, much can be done | |
1623 | manually (if tediously) in this direction. One such optimization is | |
1624 | to derive class templates from non-template classes, and move as much | |
1625 | implementation as possible into the base class. Another is to partial- | |
1626 | specialize certain common instantiations, such as vector<T*>, to share | |
1627 | code for instantiations on all types T. While these techniques work, | |
1628 | they are far from the complete solution that a compiler improvement | |
1629 | would afford. | |
1630 | ||
1631 | Overhead: Expensive Language Features | |
1632 | ------------------------------------- | |
1633 | ||
1634 | The main "expensive" language feature used in the standard library | |
1635 | is exception support, which requires compiling in cleanup code with | |
1636 | static table data to locate it, and linking in library code to use | |
1637 | the table. For small embedded programs the amount of such library | |
1638 | code and table data is assumed by some to be excessive. Under the | |
1639 | "new" ABI this perception is generally exaggerated, although in some | |
1640 | cases it may actually be excessive. | |
1641 | ||
1642 | To implement a library which does not use exceptions directly is | |
1643 | not difficult given minor compiler support (to "turn off" exceptions | |
1644 | and ignore exception constructs), and results in no great library | |
1645 | maintenance difficulties. To be precise, given "-fno-exceptions", | |
1646 | the compiler should treat "try" blocks as ordinary blocks, and | |
1647 | "catch" blocks as dead code to ignore or eliminate. Compiler | |
1648 | support is not strictly necessary, except in the case of "function | |
1649 | try blocks"; otherwise the following macros almost suffice: | |
1650 | ||
1651 | #define throw(X) | |
1652 | #define try if (true) | |
1653 | #define catch(X) else if (false) | |
1654 | ||
1655 | However, there may be a need to use function try blocks in the | |
1656 | library implementation, and use of macros in this way can make | |
1657 | correct diagnostics impossible. Furthermore, use of this scheme | |
1658 | would require the library to call a function to re-throw exceptions | |
1659 | from a try block. Implementing the above semantics in the compiler | |
1660 | is preferable. | |
1661 | ||
1662 | Given the support above (however implemented) it only remains to | |
1663 | replace code that "throws" with a call to a well-documented "handler" | |
1664 | function in a separate compilation unit which may be replaced by | |
1665 | the user. The main source of exceptions that would be difficult | |
1666 | for users to avoid is memory allocation failures, but users can | |
1667 | define their own memory allocation primitives that never throw. | |
1668 | Otherwise, the complete list of such handlers, and which library | |
1669 | functions may call them, would be needed for users to be able to | |
1670 | implement the necessary substitutes. (Fortunately, they have the | |
1671 | source code.) | |
1672 | ||
1673 | Opportunities | |
1674 | ------------- | |
1675 | ||
1676 | The template capabilities of C++ offer enormous opportunities for | |
1677 | optimizing common library operations, well beyond what would be | |
1678 | considered "eliminating overhead". In particular, many operations | |
1679 | done in Glibc with macros that depend on proprietary language | |
1680 | extensions can be implemented in pristine Standard C++. For example, | |
1681 | the chapter 25 algorithms, and even C library functions such as strchr, | |
1682 | can be specialized for the case of static arrays of known (small) size. | |
1683 | ||
1684 | Detailed optimization opportunities are identified below where | |
1685 | the component where they would appear is discussed. Of course new | |
1686 | opportunities will be identified during implementation. | |
1687 | ||
1688 | Unimplemented Required Library Features | |
1689 | --------------------------------------- | |
1690 | ||
1691 | The standard specifies hundreds of components, grouped broadly by | |
1692 | chapter. These are listed in excruciating detail in the CHECKLIST | |
1693 | file. | |
1694 | ||
1695 | 17 general | |
1696 | 18 support | |
1697 | 19 diagnostics | |
1698 | 20 utilities | |
1699 | 21 string | |
1700 | 22 locale | |
1701 | 23 containers | |
1702 | 24 iterators | |
1703 | 25 algorithms | |
1704 | 26 numerics | |
1705 | 27 iostreams | |
1706 | Annex D backward compatibility | |
1707 | ||
1708 | Anyone participating in implementation of the library should obtain | |
1709 | a copy of the standard, ISO 14882. People in the U.S. can obtain an | |
1710 | electronic copy for US$18 from ANSI's web site. Those from other | |
1711 | countries should visit http://www.iso.ch/ to find out the location | |
1712 | of their country's representation in ISO, in order to know who can | |
1713 | sell them a copy. | |
1714 | ||
1715 | The emphasis in the following sections is on unimplemented features | |
1716 | and optimization opportunities. | |
1717 | ||
1718 | Chapter 17 General | |
1719 | ------------------- | |
1720 | ||
1721 | Chapter 17 concerns overall library requirements. | |
1722 | ||
1723 | The standard doesn't mention threads. A multi-thread (MT) extension | |
1724 | primarily affects operators new and delete (18), allocator (20), | |
1725 | string (21), locale (22), and iostreams (27). The common underlying | |
1726 | support needed for this is discussed under chapter 20. | |
1727 | ||
1728 | The standard requirements on names from the C headers create a | |
1729 | lot of work, mostly done. Names in the C headers must be visible | |
1730 | in the std:: and sometimes the global namespace; the names in the | |
1731 | two scopes must refer to the same object. More stringent is that | |
1732 | Koenig lookup implies that any types specified as defined in std:: | |
1733 | really are defined in std::. Names optionally implemented as | |
1734 | macros in C cannot be macros in C++. (An overview may be read at | |
1735 | <http://www.cantrip.org/cheaders.html>). The scripts "inclosure" | |
1736 | and "mkcshadow", and the directories shadow/ and cshadow/, are the | |
1737 | beginning of an effort to conform in this area. | |
1738 | ||
1739 | A correct conforming definition of C header names based on underlying | |
1740 | C library headers, and practical linking of conforming namespaced | |
1741 | customer code with third-party C libraries depends ultimately on | |
1742 | an ABI change, allowing namespaced C type names to be mangled into | |
1743 | type names as if they were global, somewhat as C function names in a | |
1744 | namespace, or C++ global variable names, are left unmangled. Perhaps | |
1745 | another "extern" mode, such as 'extern "C-global"' would be an | |
1746 | appropriate place for such type definitions. Such a type would | |
1747 | affect mangling as follows: | |
1748 | ||
1749 | namespace A { | |
8a165db0 BK |
1750 | struct X {}; |
1751 | extern "C-global" { // or maybe just 'extern "C"' | |
c9024a78 | 1752 | struct Y {}; |
8a165db0 | 1753 | }; |
c9024a78 BK |
1754 | } |
1755 | void f(A::X*); // mangles to f__FPQ21A1X | |
1756 | void f(A::Y*); // mangles to f__FP1Y | |
1757 | ||
1758 | (It may be that this is really the appropriate semantics for regular | |
1759 | 'extern "C"', and 'extern "C-global"', as an extension, would not be | |
1760 | necessary.) This would allow functions declared in non-standard C headers | |
1761 | (and thus fixable by neither us nor users) to link properly with functions | |
1762 | declared using C types defined in properly-namespaced headers. The | |
1763 | problem this solves is that C headers (which C++ programmers do persist | |
1764 | in using) frequently forward-declare C struct tags without including | |
1765 | the header where the type is defined, as in | |
1766 | ||
1767 | struct tm; | |
1768 | void munge(tm*); | |
1769 | ||
1770 | Without some compiler accommodation, munge cannot be called by correct | |
1771 | C++ code using a pointer to a correctly-scoped tm* value. | |
1772 | ||
1773 | The current C headers use the preprocessor extension "#include_next", | |
1774 | which the compiler complains about when run "-pedantic". | |
1775 | (Incidentally, it appears that "-fpedantic" is currently ignored, | |
1776 | probably a bug.) The solution in the C compiler is to use | |
1777 | "-isystem" rather than "-I", but unfortunately in g++ this seems | |
1778 | also to wrap the whole header in an 'extern "C"' block, so it's | |
1779 | unusable for C++ headers. The correct solution appears to be to | |
1780 | allow the various special include-directory options, if not given | |
1781 | an argument, to affect subsequent include-directory options additively, | |
1782 | so that if one said | |
1783 | ||
1784 | -pedantic -iprefix $(prefix) \ | |
1785 | -idirafter -ino-pedantic -ino-extern-c -iwithprefix -I g++-v3 \ | |
1786 | -iwithprefix -I g++-v3/ext | |
1787 | ||
1788 | the compiler would search $(prefix)/g++-v3 and not report | |
1789 | pedantic warnings for files found there, but treat files in | |
1790 | $(prefix)/g++-v3/ext pedantically. (The undocumented semantics | |
1791 | of "-isystem" in g++ stink. Can they be rescinded? If not it | |
1792 | must be replaced with something more rationally behaved.) | |
1793 | ||
1794 | All the C headers need the treatment above; in the standard these | |
1795 | headers are mentioned in various chapters. Below, I have only | |
1796 | mentioned those that present interesting implementation issues. | |
1797 | ||
1798 | The components identified as "mostly complete", below, have not been | |
1799 | audited for conformance. In many cases where the library passes | |
1800 | conformance tests we have non-conforming extensions that must be | |
1801 | wrapped in #if guards for "pedantic" use, and in some cases renamed | |
1802 | in a conforming way for continued use in the implementation regardless | |
1803 | of conformance flags. | |
1804 | ||
1805 | The STL portion of the library still depends on a header | |
1806 | stl/bits/stl_config.h full of #ifdef clauses. This apparatus | |
1807 | should be replaced with autoconf/automake machinery. | |
1808 | ||
1809 | The SGI STL defines a type_traits<> template, specialized for | |
1810 | many types in their code including the built-in numeric and | |
1811 | pointer types and some library types, to direct optimizations of | |
1812 | standard functions. The SGI compiler has been extended to generate | |
1813 | specializations of this template automatically for user types, | |
1814 | so that use of STL templates on user types can take advantage of | |
1815 | these optimizations. Specializations for other, non-STL, types | |
1816 | would make more optimizations possible, but extending the gcc | |
1817 | compiler in the same way would be much better. Probably the next | |
1818 | round of standardization will ratify this, but probably with | |
1819 | changes, so it probably should be renamed to place it in the | |
1820 | implementation namespace. | |
1821 | ||
1822 | The SGI STL also defines a large number of extensions visible in | |
1823 | standard headers. (Other extensions that appear in separate headers | |
1824 | have been sequestered in subdirectories ext/ and backward/.) All | |
1825 | these extensions should be moved to other headers where possible, | |
1826 | and in any case wrapped in a namespace (not std!), and (where kept | |
1827 | in a standard header) girded about with macro guards. Some cannot be | |
1828 | moved out of standard headers because they are used to implement | |
1829 | standard features. The canonical method for accommodating these | |
1830 | is to use a protected name, aliased in macro guards to a user-space | |
1831 | name. Unfortunately C++ offers no satisfactory template typedef | |
1832 | mechanism, so very ad-hoc and unsatisfactory aliasing must be used | |
1833 | instead. | |
1834 | ||
1835 | Implementation of a template typedef mechanism should have the highest | |
1836 | priority among possible extensions, on the same level as implementation | |
1837 | of the template "export" feature. | |
1838 | ||
1839 | Chapter 18 Language support | |
1840 | ---------------------------- | |
1841 | ||
1842 | Headers: <limits> <new> <typeinfo> <exception> | |
1843 | C headers: <cstddef> <climits> <cfloat> <cstdarg> <csetjmp> | |
1844 | <ctime> <csignal> <cstdlib> (also 21, 25, 26) | |
1845 | ||
1846 | This defines the built-in exceptions, rtti, numeric_limits<>, | |
1847 | operator new and delete. Much of this is provided by the | |
1848 | compiler in its static runtime library. | |
1849 | ||
1850 | Work to do includes defining numeric_limits<> specializations in | |
1851 | separate files for all target architectures. Values for integer types | |
1852 | except for bool and wchar_t are readily obtained from the C header | |
1853 | <limits.h>, but values for the remaining numeric types (bool, wchar_t, | |
1854 | float, double, long double) must be entered manually. This is | |
1855 | largely dog work except for those members whose values are not | |
1856 | easily deduced from available documentation. Also, this involves | |
1857 | some work in target configuration to identify the correct choice of | |
1858 | file to build against and to install. | |
1859 | ||
1860 | The definitions of the various operators new and delete must be | |
1861 | made thread-safe, which depends on a portable exclusion mechanism, | |
1862 | discussed under chapter 20. Of course there is always plenty of | |
1863 | room for improvements to the speed of operators new and delete. | |
1864 | ||
1865 | <cstdarg>, in Glibc, defines some macros that gcc does not allow to | |
1866 | be wrapped into an inline function. Probably this header will demand | |
1867 | attention whenever a new target is chosen. The functions atexit(), | |
1868 | exit(), and abort() in cstdlib have different semantics in C++, so | |
1869 | must be re-implemented for C++. | |
1870 | ||
1871 | Chapter 19 Diagnostics | |
1872 | ----------------------- | |
1873 | ||
1874 | Headers: <stdexcept> | |
1875 | C headers: <cassert> <cerrno> | |
1876 | ||
1877 | This defines the standard exception objects, which are "mostly complete". | |
1878 | Cygnus has a version, and now SGI provides a slightly different one. | |
1879 | It makes little difference which we use. | |
1880 | ||
1881 | The C global name "errno", which C allows to be a variable or a macro, | |
1882 | is required in C++ to be a macro. For MT it must typically result in | |
1883 | a function call. | |
1884 | ||
1885 | Chapter 20 Utilities | |
1886 | --------------------- | |
1887 | Headers: <utility> <functional> <memory> | |
1888 | C header: <ctime> (also in 18) | |
1889 | ||
1890 | SGI STL provides "mostly complete" versions of all the components | |
1891 | defined in this chapter. However, the auto_ptr<> implementation | |
1892 | is known to be wrong. Furthermore, the standard definition of it | |
1893 | is known to be unimplementable as written. A minor change to the | |
1894 | standard would fix it, and auto_ptr<> should be adjusted to match. | |
1895 | ||
1896 | Multi-threading affects the allocator implementation, and there must | |
1897 | be configuration/installation choices for different users' MT | |
1898 | requirements. Anyway, users will want to tune allocator options | |
1899 | to support different target conditions, MT or no. | |
1900 | ||
1901 | The primitives used for MT implementation should be exposed, as an | |
1902 | extension, for users' own work. We need cross-CPU "mutex" support, | |
1903 | multi-processor shared-memory atomic integer operations, and single- | |
1904 | processor uninterruptible integer operations, and all three configurable | |
1905 | to be stubbed out for non-MT use, or to use an appropriately-loaded | |
1906 | dynamic library for the actual runtime environment, or statically | |
1907 | compiled in for cases where the target architecture is known. | |
1908 | ||
1909 | Chapter 21 String | |
1910 | ------------------ | |
1911 | Headers: <string> | |
1912 | C headers: <cctype> <cwctype> <cstring> <cwchar> (also in 27) | |
1913 | <cstdlib> (also in 18, 25, 26) | |
1914 | ||
1915 | We have "mostly-complete" char_traits<> implementations. Many of the | |
1916 | char_traits<char> operations might be optimized further using existing | |
1917 | proprietary language extensions. | |
1918 | ||
1919 | We have a "mostly-complete" basic_string<> implementation. The work | |
1920 | to manually instantiate char and wchar_t specializations in object | |
1921 | files to improve link-time behavior is extremely unsatisfactory, | |
1922 | literally tripling library-build time with no commensurate improvement | |
1923 | in static program link sizes. It must be redone. (Similar work is | |
1924 | needed for some components in chapters 22 and 27.) | |
1925 | ||
1926 | Other work needed for strings is MT-safety, as discussed under the | |
1927 | chapter 20 heading. | |
1928 | ||
1929 | The standard C type mbstate_t from <cwchar> and used in char_traits<> | |
1930 | must be different in C++ than in C, because in C++ the default constructor | |
1931 | value mbstate_t() must be the "base" or "ground" sequence state. | |
1932 | (According to the likely resolution of a recently raised Core issue, | |
1933 | this may become unnecessary. However, there are other reasons to | |
1934 | use a state type not as limited as whatever the C library provides.) | |
1935 | If we might want to provide conversions from (e.g.) internally- | |
1936 | represented EUC-wide to externally-represented Unicode, or vice- | |
1937 | versa, the mbstate_t we choose will need to be more accommodating | |
1938 | than what might be provided by an underlying C library. | |
1939 | ||
1940 | There remain some basic_string template-member functions which do | |
1941 | not overload properly with their non-template brethren. The infamous | |
1942 | hack akin to what was done in vector<> is needed, to conform to | |
1943 | 23.1.1 para 10. The CHECKLIST items for basic_string marked 'X', | |
1944 | or incomplete, are so marked for this reason. | |
1945 | ||
1946 | Replacing the string iterators, which currently are simple character | |
1947 | pointers, with class objects would greatly increase the safety of the | |
1948 | client interface, and also permit a "debug" mode in which range, | |
1949 | ownership, and validity are rigorously checked. The current use of | |
1950 | raw pointers as string iterators is evil. vector<> iterators need the | |
1951 | same treatment. Note that the current implementation freely mixes | |
1952 | pointers and iterators, and that must be fixed before safer iterators | |
1953 | can be introduced. | |
1954 | ||
1955 | Some of the functions in <cstring> are different from the C version. | |
1956 | generally overloaded on const and non-const argument pointers. For | |
1957 | example, in <cstring> strchr is overloaded. The functions isupper | |
1958 | etc. in <cctype> typically implemented as macros in C are functions | |
1959 | in C++, because they are overloaded with others of the same name | |
1960 | defined in <locale>. | |
1961 | ||
1962 | Many of the functions required in <cwctype> and <cwchar> cannot be | |
1963 | implemented using underlying C facilities on intended targets because | |
1964 | such facilities only partly exist. | |
1965 | ||
1966 | Chapter 22 Locale | |
1967 | ------------------ | |
1968 | Headers: <locale> | |
1969 | C headers: <clocale> | |
1970 | ||
1971 | We have a "mostly complete" class locale, with the exception of | |
1972 | code for constructing, and handling the names of, named locales. | |
1973 | The ways that locales are named (particularly when categories | |
1974 | (e.g. LC_TIME, LC_COLLATE) are different) varies among all target | |
1975 | environments. This code must be written in various versions and | |
1976 | chosen by configuration parameters. | |
1977 | ||
1978 | Members of many of the facets defined in <locale> are stubs. Generally, | |
1979 | there are two sets of facets: the base class facets (which are supposed | |
1980 | to implement the "C" locale) and the "byname" facets, which are supposed | |
1981 | to read files to determine their behavior. The base ctype<>, collate<>, | |
1982 | and numpunct<> facets are "mostly complete", except that the table of | |
1983 | bitmask values used for "is" operations, and corresponding mask values, | |
1984 | are still defined in libio and just included/linked. (We will need to | |
1985 | implement these tables independently, soon, but should take advantage | |
1986 | of libio where possible.) The num_put<>::put members for integer types | |
1987 | are "mostly complete". | |
1988 | ||
1989 | A complete list of what has and has not been implemented may be | |
1990 | found in CHECKLIST. However, note that the current definition of | |
1991 | codecvt<wchar_t,char,mbstate_t> is wrong. It should simply write | |
1992 | out the raw bytes representing the wide characters, rather than | |
1993 | trying to convert each to a corresponding single "char" value. | |
1994 | ||
1995 | Some of the facets are more important than others. Specifically, | |
1996 | the members of ctype<>, numpunct<>, num_put<>, and num_get<> facets | |
1997 | are used by other library facilities defined in <string>, <istream>, | |
1998 | and <ostream>, and the codecvt<> facet is used by basic_filebuf<> | |
1999 | in <fstream>, so a conforming iostream implementation depends on | |
2000 | these. | |
2001 | ||
2002 | The "long long" type eventually must be supported, but code mentioning | |
2003 | it should be wrapped in #if guards to allow pedantic-mode compiling. | |
2004 | ||
2005 | Performance of num_put<> and num_get<> depend critically on | |
2006 | caching computed values in ios_base objects, and on extensions | |
2007 | to the interface with streambufs. | |
2008 | ||
2009 | Specifically: retrieving a copy of the locale object, extracting | |
2010 | the needed facets, and gathering data from them, for each call to | |
2011 | (e.g.) operator<< would be prohibitively slow. To cache format | |
2012 | data for use by num_put<> and num_get<> we have a _Format_cache<> | |
2013 | object stored in the ios_base::pword() array. This is constructed | |
2014 | and initialized lazily, and is organized purely for utility. It | |
2015 | is discarded when a new locale with different facets is imbued. | |
2016 | ||
2017 | Using only the public interfaces of the iterator arguments to the | |
2018 | facet functions would limit performance by forbidding "vector-style" | |
2019 | character operations. The streambuf iterator optimizations are | |
2020 | described under chapter 24, but facets can also bypass the streambuf | |
2021 | iterators via explicit specializations and operate directly on the | |
2022 | streambufs, and use extended interfaces to get direct access to the | |
2023 | streambuf internal buffer arrays. These extensions are mentioned | |
2024 | under chapter 27. These optimizations are particularly important | |
2025 | for input parsing. | |
2026 | ||
2027 | Unused virtual members of locale facets can be omitted, as mentioned | |
2028 | above, by a smart linker. | |
2029 | ||
2030 | Chapter 23 Containers | |
2031 | ---------------------- | |
2032 | Headers: <deque> <list> <queue> <stack> <vector> <map> <set> <bitset> | |
2033 | ||
2034 | All the components in chapter 23 are implemented in the SGI STL. | |
2035 | They are "mostly complete"; they include a large number of | |
2036 | nonconforming extensions which must be wrapped. Some of these | |
2037 | are used internally and must be renamed or duplicated. | |
2038 | ||
2039 | The SGI components are optimized for large-memory environments. For | |
2040 | embedded targets, different criteria might be more appropriate. Users | |
2041 | will want to be able to tune this behavior. We should provide | |
2042 | ways for users to compile the library with different memory usage | |
2043 | characteristics. | |
2044 | ||
2045 | A lot more work is needed on factoring out common code from different | |
2046 | specializations to reduce code size here and in chapter 25. The | |
2047 | easiest fix for this would be a compiler/ABI improvement that allows | |
2048 | the compiler to recognize when a specialization depends only on the | |
2049 | size (or other gross quality) of a template argument, and allow the | |
2050 | linker to share the code with similar specializations. In its | |
2051 | absence, many of the algorithms and containers can be partial- | |
2052 | specialized, at least for the case of pointers, but this only solves | |
2053 | a small part of the problem. Use of a type_traits-style template | |
2054 | allows a few more optimization opportunities, more if the compiler | |
2055 | can generate the specializations automatically. | |
2056 | ||
2057 | As an optimization, containers can specialize on the default allocator | |
2058 | and bypass it, or take advantage of details of its implementation | |
2059 | after it has been improved upon. | |
2060 | ||
2061 | Replacing the vector iterators, which currently are simple element | |
2062 | pointers, with class objects would greatly increase the safety of the | |
2063 | client interface, and also permit a "debug" mode in which range, | |
2064 | ownership, and validity are rigorously checked. The current use of | |
2065 | pointers for iterators is evil. | |
2066 | ||
2067 | As mentioned for chapter 24, the deque iterator is a good example of | |
2068 | an opportunity to implement a "staged" iterator that would benefit | |
2069 | from specializations of some algorithms. | |
2070 | ||
2071 | Chapter 24 Iterators | |
2072 | --------------------- | |
2073 | Headers: <iterator> | |
2074 | ||
2075 | Standard iterators are "mostly complete", with the exception of | |
2076 | the stream iterators, which are not yet templatized on the | |
2077 | stream type. Also, the base class template iterator<> appears | |
2078 | to be wrong, so everything derived from it must also be wrong, | |
2079 | currently. | |
2080 | ||
2081 | The streambuf iterators (currently located in stl/bits/std_iterator.h, | |
2082 | but should be under bits/) can be rewritten to take advantage of | |
2083 | friendship with the streambuf implementation. | |
2084 | ||
2085 | Matt Austern has identified opportunities where certain iterator | |
2086 | types, particularly including streambuf iterators and deque | |
2087 | iterators, have a "two-stage" quality, such that an intermediate | |
2088 | limit can be checked much more quickly than the true limit on | |
2089 | range operations. If identified with a member of iterator_traits, | |
2090 | algorithms may be specialized for this case. Of course the | |
2091 | iterators that have this quality can be identified by specializing | |
2092 | a traits class. | |
2093 | ||
2094 | Many of the algorithms must be specialized for the streambuf | |
2095 | iterators, to take advantage of block-mode operations, in order | |
2096 | to allow iostream/locale operations' performance not to suffer. | |
2097 | It may be that they could be treated as staged iterators and | |
2098 | take advantage of those optimizations. | |
2099 | ||
2100 | Chapter 25 Algorithms | |
2101 | ---------------------- | |
2102 | Headers: <algorithm> | |
2103 | C headers: <cstdlib> (also in 18, 21, 26)) | |
2104 | ||
2105 | The algorithms are "mostly complete". As mentioned above, they | |
2106 | are optimized for speed at the expense of code and data size. | |
2107 | ||
2108 | Specializations of many of the algorithms for non-STL types would | |
2109 | give performance improvements, but we must use great care not to | |
2110 | interfere with fragile template overloading semantics for the | |
2111 | standard interfaces. Conventionally the standard function template | |
2112 | interface is an inline which delegates to a non-standard function | |
2113 | which is then overloaded (this is already done in many places in | |
2114 | the library). Particularly appealing opportunities for the sake of | |
2115 | iostream performance are for copy and find applied to streambuf | |
2116 | iterators or (as noted elsewhere) for staged iterators, of which | |
2117 | the streambuf iterators are a good example. | |
2118 | ||
2119 | The bsearch and qsort functions cannot be overloaded properly as | |
2120 | required by the standard because gcc does not yet allow overloading | |
2121 | on the extern-"C"-ness of a function pointer. | |
2122 | ||
2123 | Chapter 26 Numerics | |
2124 | -------------------- | |
2125 | Headers: <complex> <valarray> <numeric> | |
2126 | C headers: <cmath>, <cstdlib> (also 18, 21, 25) | |
2127 | ||
2128 | Numeric components: Gabriel dos Reis's valarray, Drepper's complex, | |
2129 | and the few algorithms from the STL are "mostly done". Of course | |
2130 | optimization opportunities abound for the numerically literate. It | |
2131 | is not clear whether the valarray implementation really conforms | |
2132 | fully, in the assumptions it makes about aliasing (and lack thereof) | |
2133 | in its arguments. | |
2134 | ||
2135 | The C div() and ldiv() functions are interesting, because they are the | |
2136 | only case where a C library function returns a class object by value. | |
2137 | Since the C++ type div_t must be different from the underlying C type | |
2138 | (which is in the wrong namespace) the underlying functions div() and | |
2139 | ldiv() cannot be re-used efficiently. Fortunately they are trivial to | |
2140 | re-implement. | |
2141 | ||
2142 | Chapter 27 Iostreams | |
2143 | --------------------- | |
2144 | Headers: <iosfwd> <streambuf> <ios> <ostream> <istream> <iostream> | |
2145 | <iomanip> <sstream> <fstream> | |
2146 | C headers: <cstdio> <cwchar> (also in 21) | |
2147 | ||
2148 | Iostream is currently in a very incomplete state. <iosfwd>, <iomanip>, | |
2149 | ios_base, and basic_ios<> are "mostly complete". basic_streambuf<> and | |
2150 | basic_ostream<> are well along, but basic_istream<> has had little work | |
2151 | done. The standard stream objects, <sstream> and <fstream> have been | |
2152 | started; basic_filebuf<> "write" functions have been implemented just | |
2153 | enough to do "hello, world". | |
2154 | ||
2155 | Most of the istream and ostream operators << and >> (with the exception | |
2156 | of the op<<(integer) ones) have not been changed to use locale primitives, | |
2157 | sentry objects, or char_traits members. | |
2158 | ||
2159 | All these templates should be manually instantiated for char and | |
2160 | wchar_t in a way that links only used members into user programs. | |
2161 | ||
2162 | Streambuf is fertile ground for optimization extensions. An extended | |
2163 | interface giving iterator access to its internal buffer would be very | |
2164 | useful for other library components. | |
2165 | ||
2166 | Iostream operations (primarily operators << and >>) can take advantage | |
2167 | of the case where user code has not specified a locale, and bypass locale | |
2168 | operations entirely. The current implementation of op<</num_put<>::put, | |
2169 | for the integer types, demonstrates how they can cache encoding details | |
2170 | from the locale on each operation. There is lots more room for | |
2171 | optimization in this area. | |
2172 | ||
2173 | The definition of the relationship between the standard streams | |
2174 | cout et al. and stdout et al. requires something like a "stdiobuf". | |
2175 | The SGI solution of using double-indirection to actually use a | |
2176 | stdio FILE object for buffering is unsatisfactory, because it | |
2177 | interferes with peephole loop optimizations. | |
2178 | ||
2179 | The <sstream> header work has begun. stringbuf can benefit from | |
2180 | friendship with basic_string<> and basic_string<>::_Rep to use | |
2181 | those objects directly as buffers, and avoid allocating and making | |
2182 | copies. | |
2183 | ||
2184 | The basic_filebuf<> template is a complex beast. It is specified to | |
2185 | use the locale facet codecvt<> to translate characters between native | |
2186 | files and the locale character encoding. In general this involves | |
2187 | two buffers, one of "char" representing the file and another of | |
2188 | "char_type", for the stream, with codecvt<> translating. The process | |
2189 | is complicated by the variable-length nature of the translation, and | |
2190 | the need to seek to corresponding places in the two representations. | |
2191 | For the case of basic_filebuf<char>, when no translation is needed, | |
2192 | a single buffer suffices. A specialized filebuf can be used to reduce | |
2193 | code space overhead when no locale has been imbued. Matt Austern's | |
2194 | work at SGI will be useful, perhaps directly as a source of code, or | |
2195 | at least as an example to draw on. | |
2196 | ||
2197 | Filebuf, almost uniquely (cf. operator new), depends heavily on | |
2198 | underlying environmental facilities. In current releases iostream | |
2199 | depends fairly heavily on libio constant definitions, but it should | |
2200 | be made independent. It also depends on operating system primitives | |
2201 | for file operations. There is immense room for optimizations using | |
2202 | (e.g.) mmap for reading. The shadow/ directory wraps, besides the | |
2203 | standard C headers, the libio.h and unistd.h headers, for use mainly | |
2204 | by filebuf. These wrappings have not been completed, though there | |
2205 | is scaffolding in place. | |
2206 | ||
4394b61e | 2207 | The encapsulation of certain C header <cstdio> names presents an |
c9024a78 BK |
2208 | interesting problem. It is possible to define an inline std::fprintf() |
2209 | implemented in terms of the 'extern "C"' vfprintf(), but there is no | |
2210 | standard vfscanf() to use to implement std::fscanf(). It appears that | |
2211 | vfscanf but be re-implemented in C++ for targets where no vfscanf | |
2212 | extension has been defined. This is interesting in that it seems | |
2213 | to be the only significant case in the C library where this kind of | |
2214 | rewriting is necessary. (Of course Glibc provides the vfscanf() | |
2215 | extension.) (The functions related to exit() must be rewritten | |
2216 | for other reasons.) | |
2217 | ||
2218 | ||
2219 | Annex D | |
2220 | ------- | |
2221 | Headers: <strstream> | |
2222 | ||
2223 | Annex D defines many non-library features, and many minor | |
2224 | modifications to various headers, and a complete header. | |
2225 | It is "mostly done", except that the libstdc++-2 <strstream> | |
2226 | header has not been adopted into the library, or checked to | |
2227 | verify that it matches the draft in those details that were | |
2228 | clarified by the committee. Certainly it must at least be | |
2229 | moved into the std namespace. | |
2230 | ||
2231 | We still need to wrap all the deprecated features in #if guards | |
2232 | so that pedantic compile modes can detect their use. | |
2233 | ||
2234 | Nonstandard Extensions | |
2235 | ---------------------- | |
2236 | Headers: <iostream.h> <strstream.h> <hash> <rbtree> | |
2237 | <pthread_alloc> <stdiobuf> (etc.) | |
2238 | ||
2239 | User code has come to depend on a variety of nonstandard components | |
2240 | that we must not omit. Much of this code can be adopted from | |
2241 | libstdc++-v2 or from the SGI STL. This particularly includes | |
2242 | <iostream.h>, <strstream.h>, and various SGI extensions such | |
2243 | as <hash_map.h>. Many of these are already placed in the | |
2244 | subdirectories ext/ and backward/. (Note that it is better to | |
2245 | include them via "<backward/hash_map.h>" or "<ext/hash_map>" than | |
2246 | to search the subdirectory itself via a "-I" directive. | |
2247 | </literallayout> | |
2248 | </sect1> | |
8a165db0 BK |
2249 | |
2250 | </appendix> |