]>
Commit | Line | Data |
---|---|---|
16d0b033 | 1 | <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" |
c6a21af2 | 2 | xml:id="manual.ext.debug_mode" xreflabel="Debug Mode"> |
8a165db0 | 3 | <?dbhtml filename="debug_mode.html"?> |
03a32789 | 4 | |
c6a21af2 | 5 | <info><title>Debug Mode</title> |
8a165db0 | 6 | <keywordset> |
92eba400 AS |
7 | <keyword>C++</keyword> |
8 | <keyword>library</keyword> | |
9 | <keyword>debug</keyword> | |
8a165db0 | 10 | </keywordset> |
c6a21af2 BK |
11 | </info> |
12 | ||
8a165db0 | 13 | |
8a165db0 | 14 | |
c6a21af2 | 15 | <section xml:id="manual.ext.debug_mode.intro" xreflabel="Intro"><info><title>Intro</title></info> |
16d0b033 | 16 | |
8a165db0 BK |
17 | <para> |
18 | By default, libstdc++ is built with efficiency in mind, and | |
19 | therefore performs little or no error checking that is not | |
20 | required by the C++ standard. This means that programs that | |
21 | incorrectly use the C++ standard library will exhibit behavior | |
22 | that is not portable and may not even be predictable, because they | |
23 | tread into implementation-specific or undefined behavior. To | |
24 | detect some of these errors before they can become problematic, | |
25 | libstdc++ offers a debug mode that provides additional checking of | |
26 | library facilities, and will report errors in the use of libstdc++ | |
27 | as soon as they can be detected by emitting a description of the | |
28 | problem to standard error and aborting the program. This debug | |
03a32789 | 29 | mode is available with GCC 3.4.0 and later versions. |
8a165db0 BK |
30 | </para> |
31 | ||
32 | <para> | |
33 | The libstdc++ debug mode performs checking for many areas of the | |
34 | C++ standard, but the focus is on checking interactions among | |
35 | standard iterators, containers, and algorithms, including: | |
36 | </para> | |
37 | ||
38 | <itemizedlist> | |
39 | <listitem><para><emphasis>Safe iterators</emphasis>: Iterators keep track of the | |
40 | container whose elements they reference, so errors such as | |
41 | incrementing a past-the-end iterator or dereferencing an iterator | |
42 | that points to a container that has been destructed are diagnosed | |
43 | immediately.</para></listitem> | |
03a32789 | 44 | |
8a165db0 BK |
45 | <listitem><para><emphasis>Algorithm preconditions</emphasis>: Algorithms attempt to |
46 | validate their input parameters to detect errors as early as | |
47 | possible. For instance, the <code>set_intersection</code> | |
48 | algorithm requires that its iterator | |
49 | parameters <code>first1</code> and <code>last1</code> form a valid | |
50 | iterator range, and that the sequence | |
51 | [<code>first1</code>, <code>last1</code>) is sorted according to | |
52 | the same predicate that was passed | |
53 | to <code>set_intersection</code>; the libstdc++ debug mode will | |
54 | detect an error if the sequence is not sorted or was sorted by a | |
55 | different predicate.</para></listitem> | |
56 | </itemizedlist> | |
57 | ||
c6a21af2 | 58 | </section> |
8a165db0 | 59 | |
c6a21af2 | 60 | <section xml:id="manual.ext.debug_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info> |
898be2f3 | 61 | <?dbhtml filename="debug_mode_semantics.html"?> |
16d0b033 | 62 | |
8a165db0 BK |
63 | <para> |
64 | </para> | |
65 | ||
66 | <para>A program that uses the C++ standard library correctly | |
67 | will maintain the same semantics under debug mode as it had with | |
68 | the normal (release) library. All functional and exception-handling | |
69 | guarantees made by the normal library also hold for the debug mode | |
70 | library, with one exception: performance guarantees made by the | |
71 | normal library may not hold in the debug mode library. For | |
72 | instance, erasing an element in a <code>std::list</code> is a | |
73 | constant-time operation in normal library, but in debug mode it is | |
74 | linear in the number of iterators that reference that particular | |
03a32789 | 75 | list. So while your (correct) program won't change its results, it |
8a165db0 BK |
76 | is likely to execute more slowly.</para> |
77 | ||
78 | <para>libstdc++ includes many extensions to the C++ standard library. In | |
79 | some cases the extensions are obvious, such as the hashed | |
80 | associative containers, whereas other extensions give predictable | |
81 | results to behavior that would otherwise be undefined, such as | |
82 | throwing an exception when a <code>std::basic_string</code> is | |
83 | constructed from a NULL character pointer. This latter category also | |
84 | includes implementation-defined and unspecified semantics, such as | |
85 | the growth rate of a vector. Use of these extensions is not | |
86 | considered incorrect, so code that relies on them will not be | |
87 | rejected by debug mode. However, use of these extensions may affect | |
88 | the portability of code to other implementations of the C++ standard | |
89 | library, and is therefore somewhat hazardous. For this reason, the | |
90 | libstdc++ debug mode offers a "pedantic" mode (similar to | |
91 | GCC's <code>-pedantic</code> compiler flag) that attempts to emulate | |
92 | the semantics guaranteed by the C++ standard. For | |
93 | instance, constructing a <code>std::basic_string</code> with a NULL | |
94 | character pointer would result in an exception under normal mode or | |
95 | non-pedantic debug mode (this is a libstdc++ extension), whereas | |
96 | under pedantic debug mode libstdc++ would signal an error. To enable | |
97 | the pedantic debug mode, compile your program with | |
98 | both <code>-D_GLIBCXX_DEBUG</code> | |
99 | and <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> . | |
100 | (N.B. In GCC 3.4.x and 4.0.0, due to a bug, | |
101 | <code>-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has | |
102 | been fixed in GCC 4.0.1 and later versions.) </para> | |
103 | ||
104 | <para>The following library components provide extra debugging | |
105 | capabilities in debug mode:</para> | |
106 | <itemizedlist> | |
254e5d19 | 107 | <listitem><para><code>std::array</code> (no safe iterators)</para></listitem> |
8a165db0 BK |
108 | <listitem><para><code>std::basic_string</code> (no safe iterators and see note below)</para></listitem> |
109 | <listitem><para><code>std::bitset</code></para></listitem> | |
110 | <listitem><para><code>std::deque</code></para></listitem> | |
111 | <listitem><para><code>std::list</code></para></listitem> | |
112 | <listitem><para><code>std::map</code></para></listitem> | |
113 | <listitem><para><code>std::multimap</code></para></listitem> | |
114 | <listitem><para><code>std::multiset</code></para></listitem> | |
115 | <listitem><para><code>std::set</code></para></listitem> | |
116 | <listitem><para><code>std::vector</code></para></listitem> | |
117 | <listitem><para><code>std::unordered_map</code></para></listitem> | |
118 | <listitem><para><code>std::unordered_multimap</code></para></listitem> | |
119 | <listitem><para><code>std::unordered_set</code></para></listitem> | |
120 | <listitem><para><code>std::unordered_multiset</code></para></listitem> | |
121 | </itemizedlist> | |
122 | ||
123 | <para>N.B. although there are precondition checks for some string operations, | |
124 | e.g. <code>operator[]</code>, | |
125 | they will not always be run when using the <code>char</code> and | |
254e5d19 | 126 | <code>wchar_t</code> specializations (<code>std::string</code> and |
8a165db0 BK |
127 | <code>std::wstring</code>). This is because libstdc++ uses GCC's |
128 | <code>extern template</code> extension to provide explicit instantiations | |
129 | of <code>std::string</code> and <code>std::wstring</code>, and those | |
130 | explicit instantiations don't include the debug-mode checks. If the | |
131 | containing functions are inlined then the checks will run, so compiling | |
132 | with <code>-O1</code> might be enough to enable them. Alternatively | |
133 | <code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations | |
134 | of the explicit instantiations and cause the functions to be instantiated | |
135 | with the debug-mode checks included, but this is unsupported and not | |
136 | guaranteed to work. For full debug-mode support you can use the | |
137 | <code>__gnu_debug::basic_string</code> debugging container directly, | |
138 | which always works correctly. | |
139 | </para> | |
140 | ||
c6a21af2 | 141 | </section> |
8a165db0 | 142 | |
c6a21af2 | 143 | <section xml:id="manual.ext.debug_mode.using" xreflabel="Using"><info><title>Using</title></info> |
898be2f3 | 144 | <?dbhtml filename="debug_mode_using.html"?> |
16d0b033 | 145 | |
8a165db0 BK |
146 | <para> |
147 | </para> | |
c6a21af2 | 148 | <section xml:id="debug_mode.using.mode" xreflabel="Using Mode"><info><title>Using the Debug Mode</title></info> |
16d0b033 | 149 | |
8a165db0 BK |
150 | |
151 | <para>To use the libstdc++ debug mode, compile your application with the | |
152 | compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag | |
153 | changes the sizes and behavior of standard class templates such | |
154 | as <code>std::vector</code>, and therefore you can only link code | |
155 | compiled with debug mode and code compiled without debug mode if no | |
156 | instantiation of a container is passed between the two translation | |
157 | units.</para> | |
158 | ||
159 | <para>By default, error messages are formatted to fit on lines of about | |
160 | 78 characters. The environment variable | |
161 | <code>GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a | |
162 | different length.</para> | |
163 | ||
c6a21af2 | 164 | </section> |
8a165db0 | 165 | |
c6a21af2 | 166 | <section xml:id="debug_mode.using.specific" xreflabel="Using Specific"><info><title>Using a Specific Debug Container</title></info> |
16d0b033 | 167 | |
8a165db0 BK |
168 | <para>When it is not feasible to recompile your entire application, or |
169 | only specific containers need checking, debugging containers are | |
170 | available as GNU extensions. These debugging containers are | |
171 | functionally equivalent to the standard drop-in containers used in | |
172 | debug mode, but they are available in a separate namespace as GNU | |
173 | extensions and may be used in programs compiled with either release | |
174 | mode or with debug mode. The | |
175 | following table provides the names and headers of the debugging | |
176 | containers: | |
177 | </para> | |
178 | ||
109a3af4 | 179 | <table frame="all" xml:id="table.debug_mode_containers"> |
8a165db0 | 180 | <title>Debugging Containers</title> |
c6a21af2 BK |
181 | |
182 | <tgroup cols="4" align="left" colsep="1" rowsep="1"> | |
183 | <colspec colname="c1"/> | |
184 | <colspec colname="c2"/> | |
185 | <colspec colname="c3"/> | |
186 | <colspec colname="c4"/> | |
8a165db0 BK |
187 | |
188 | <thead> | |
189 | <row> | |
190 | <entry>Container</entry> | |
191 | <entry>Header</entry> | |
192 | <entry>Debug container</entry> | |
193 | <entry>Debug header</entry> | |
194 | </row> | |
195 | </thead> | |
196 | <tbody> | |
197 | <row> | |
198 | <entry><classname>std::bitset</classname></entry> | |
199 | <entry><filename class="headerfile">bitset</filename></entry> | |
200 | <entry><classname>__gnu_debug::bitset</classname></entry> | |
2b72aa26 | 201 | <entry><filename class="headerfile"><debug/bitset></filename></entry> |
8a165db0 BK |
202 | </row> |
203 | <row> | |
204 | <entry><classname>std::deque</classname></entry> | |
205 | <entry><filename class="headerfile">deque</filename></entry> | |
206 | <entry><classname>__gnu_debug::deque</classname></entry> | |
2b72aa26 | 207 | <entry><filename class="headerfile"><debug/deque></filename></entry> |
8a165db0 BK |
208 | </row> |
209 | <row> | |
210 | <entry><classname>std::list</classname></entry> | |
211 | <entry><filename class="headerfile">list</filename></entry> | |
212 | <entry><classname>__gnu_debug::list</classname></entry> | |
2b72aa26 | 213 | <entry><filename class="headerfile"><debug/list></filename></entry> |
8a165db0 BK |
214 | </row> |
215 | <row> | |
216 | <entry><classname>std::map</classname></entry> | |
217 | <entry><filename class="headerfile">map</filename></entry> | |
218 | <entry><classname>__gnu_debug::map</classname></entry> | |
2b72aa26 | 219 | <entry><filename class="headerfile"><debug/map></filename></entry> |
8a165db0 BK |
220 | </row> |
221 | <row> | |
222 | <entry><classname>std::multimap</classname></entry> | |
223 | <entry><filename class="headerfile">map</filename></entry> | |
224 | <entry><classname>__gnu_debug::multimap</classname></entry> | |
2b72aa26 | 225 | <entry><filename class="headerfile"><debug/map></filename></entry> |
8a165db0 BK |
226 | </row> |
227 | <row> | |
228 | <entry><classname>std::multiset</classname></entry> | |
229 | <entry><filename class="headerfile">set</filename></entry> | |
230 | <entry><classname>__gnu_debug::multiset</classname></entry> | |
2b72aa26 | 231 | <entry><filename class="headerfile"><debug/set></filename></entry> |
8a165db0 BK |
232 | </row> |
233 | <row> | |
234 | <entry><classname>std::set</classname></entry> | |
235 | <entry><filename class="headerfile">set</filename></entry> | |
236 | <entry><classname>__gnu_debug::set</classname></entry> | |
2b72aa26 | 237 | <entry><filename class="headerfile"><debug/set></filename></entry> |
8a165db0 BK |
238 | </row> |
239 | <row> | |
240 | <entry><classname>std::string</classname></entry> | |
241 | <entry><filename class="headerfile">string</filename></entry> | |
242 | <entry><classname>__gnu_debug::string</classname></entry> | |
2b72aa26 | 243 | <entry><filename class="headerfile"><debug/string></filename></entry> |
8a165db0 BK |
244 | </row> |
245 | <row> | |
246 | <entry><classname>std::wstring</classname></entry> | |
247 | <entry><filename class="headerfile">string</filename></entry> | |
248 | <entry><classname>__gnu_debug::wstring</classname></entry> | |
2b72aa26 | 249 | <entry><filename class="headerfile"><debug/string></filename></entry> |
8a165db0 BK |
250 | </row> |
251 | <row> | |
252 | <entry><classname>std::basic_string</classname></entry> | |
253 | <entry><filename class="headerfile">string</filename></entry> | |
254 | <entry><classname>__gnu_debug::basic_string</classname></entry> | |
2b72aa26 | 255 | <entry><filename class="headerfile"><debug/string></filename></entry> |
8a165db0 BK |
256 | </row> |
257 | <row> | |
258 | <entry><classname>std::vector</classname></entry> | |
259 | <entry><filename class="headerfile">vector</filename></entry> | |
260 | <entry><classname>__gnu_debug::vector</classname></entry> | |
2b72aa26 | 261 | <entry><filename class="headerfile"><debug/vector></filename></entry> |
8a165db0 BK |
262 | </row> |
263 | </tbody> | |
264 | </tgroup> | |
265 | </table> | |
266 | ||
254e5d19 | 267 | <para>When compiling in C++11 mode (or newer), these |
8a165db0 BK |
268 | containers have additional debug capability. |
269 | </para> | |
270 | ||
109a3af4 | 271 | <table frame="all" xml:id="table.debug_mode_containers_cxx11"> |
f25481f4 | 272 | <title>Debugging Containers C++11</title> |
c6a21af2 BK |
273 | |
274 | <tgroup cols="4" align="left" colsep="1" rowsep="1"> | |
275 | <colspec colname="c1"/> | |
276 | <colspec colname="c2"/> | |
277 | <colspec colname="c3"/> | |
278 | <colspec colname="c4"/> | |
8a165db0 BK |
279 | |
280 | <thead> | |
281 | <row> | |
282 | <entry>Container</entry> | |
283 | <entry>Header</entry> | |
284 | <entry>Debug container</entry> | |
285 | <entry>Debug header</entry> | |
286 | </row> | |
287 | </thead> | |
288 | <tbody> | |
0f8a1c15 JW |
289 | <row> |
290 | <entry><classname>std::forward_list</classname></entry> | |
291 | <entry><filename class="headerfile">forward_list</filename></entry> | |
292 | <entry><classname>__gnu_debug::forward_list</classname></entry> | |
293 | <entry><filename class="headerfile"><debug/forward_list></filename></entry> | |
294 | </row> | |
295 | <row> | |
8a165db0 BK |
296 | <entry><classname>std::unordered_map</classname></entry> |
297 | <entry><filename class="headerfile">unordered_map</filename></entry> | |
298 | <entry><classname>__gnu_debug::unordered_map</classname></entry> | |
2b72aa26 | 299 | <entry><filename class="headerfile"><debug/unordered_map></filename></entry> |
8a165db0 BK |
300 | </row> |
301 | <row> | |
302 | <entry><classname>std::unordered_multimap</classname></entry> | |
303 | <entry><filename class="headerfile">unordered_map</filename></entry> | |
304 | <entry><classname>__gnu_debug::unordered_multimap</classname></entry> | |
2b72aa26 | 305 | <entry><filename class="headerfile"><debug/unordered_map></filename></entry> |
8a165db0 BK |
306 | </row> |
307 | <row> | |
308 | <entry><classname>std::unordered_set</classname></entry> | |
309 | <entry><filename class="headerfile">unordered_set</filename></entry> | |
310 | <entry><classname>__gnu_debug::unordered_set</classname></entry> | |
2b72aa26 | 311 | <entry><filename class="headerfile"><debug/unordered_set></filename></entry> |
8a165db0 BK |
312 | </row> |
313 | <row> | |
314 | <entry><classname>std::unordered_multiset</classname></entry> | |
315 | <entry><filename class="headerfile">unordered_set</filename></entry> | |
316 | <entry><classname>__gnu_debug::unordered_multiset</classname></entry> | |
2b72aa26 | 317 | <entry><filename class="headerfile"><debug/unordered_set></filename></entry> |
8a165db0 BK |
318 | </row> |
319 | </tbody> | |
320 | </tgroup> | |
321 | </table> | |
254e5d19 JW |
322 | |
323 | <para>Prior to GCC 11 a debug version of <classname>std::array</classname> | |
324 | was available as <classname>__gnu_debug::array</classname> in the | |
325 | header <filename class="headerfile"><debug/array></filename>. | |
326 | Because <classname>array::iterator</classname> is just a pointer, | |
327 | the debug <classname>array</classname> can't check iterator operations, | |
328 | it can only check direct accesses to the container. | |
329 | Starting with GCC 11 all the debug capabilities are available in | |
330 | <classname>std::array</classname>, without needing a separate type, | |
331 | so <classname>__gnu_debug::array</classname> is just an alias for | |
332 | <classname>std::array</classname>. | |
333 | That alias is deprecated and may be removed in a future release. | |
334 | </para> | |
335 | ||
c6a21af2 BK |
336 | </section> |
337 | </section> | |
8a165db0 | 338 | |
c6a21af2 | 339 | <section xml:id="manual.ext.debug_mode.design" xreflabel="Design"><info><title>Design</title></info> |
898be2f3 | 340 | <?dbhtml filename="debug_mode_design.html"?> |
16d0b033 | 341 | |
8a165db0 BK |
342 | <para> |
343 | </para> | |
c6a21af2 | 344 | <section xml:id="debug_mode.design.goals" xreflabel="Goals"><info><title>Goals</title></info> |
16d0b033 | 345 | |
8a165db0 BK |
346 | <para> |
347 | </para> | |
348 | <para> The libstdc++ debug mode replaces unsafe (but efficient) standard | |
349 | containers and iterators with semantically equivalent safe standard | |
350 | containers and iterators to aid in debugging user programs. The | |
351 | following goals directed the design of the libstdc++ debug mode:</para> | |
352 | ||
353 | <itemizedlist> | |
354 | ||
355 | <listitem><para><emphasis>Correctness</emphasis>: the libstdc++ debug mode must not change | |
356 | the semantics of the standard library for all cases specified in | |
357 | the ANSI/ISO C++ standard. The essence of this constraint is that | |
358 | any valid C++ program should behave in the same manner regardless | |
359 | of whether it is compiled with debug mode or release mode. In | |
360 | particular, entities that are defined in namespace std in release | |
361 | mode should remain defined in namespace std in debug mode, so that | |
362 | legal specializations of namespace std entities will remain | |
363 | valid. A program that is not valid C++ (e.g., invokes undefined | |
364 | behavior) is not required to behave similarly, although the debug | |
365 | mode will abort with a diagnostic when it detects undefined | |
366 | behavior.</para></listitem> | |
367 | ||
368 | <listitem><para><emphasis>Performance</emphasis>: the additional of the libstdc++ debug mode | |
369 | must not affect the performance of the library when it is compiled | |
370 | in release mode. Performance of the libstdc++ debug mode is | |
371 | secondary (and, in fact, will be worse than the release | |
372 | mode).</para></listitem> | |
373 | ||
374 | <listitem><para><emphasis>Usability</emphasis>: the libstdc++ debug mode should be easy to | |
375 | use. It should be easily incorporated into the user's development | |
376 | environment (e.g., by requiring only a single new compiler switch) | |
377 | and should produce reasonable diagnostics when it detects a | |
378 | problem with the user program. Usability also involves detection | |
379 | of errors when using the debug mode incorrectly, e.g., by linking | |
380 | a release-compiled object against a debug-compiled object if in | |
381 | fact the resulting program will not run correctly.</para></listitem> | |
382 | ||
383 | <listitem><para><emphasis>Minimize recompilation</emphasis>: While it is expected that | |
384 | users recompile at least part of their program to use debug | |
385 | mode, the amount of recompilation affects the | |
386 | detect-compile-debug turnaround time. This indirectly affects the | |
387 | usefulness of the debug mode, because debugging some applications | |
388 | may require rebuilding a large amount of code, which may not be | |
389 | feasible when the suspect code may be very localized. There are | |
390 | several levels of conformance to this requirement, each with its | |
391 | own usability and implementation characteristics. In general, the | |
392 | higher-numbered conformance levels are more usable (i.e., require | |
393 | less recompilation) but are more complicated to implement than | |
03a32789 | 394 | the lower-numbered conformance levels. |
c6a21af2 | 395 | <orderedlist inheritnum="ignore" continuation="restarts"> |
8a165db0 BK |
396 | <listitem><para><emphasis>Full recompilation</emphasis>: The user must recompile his or |
397 | her entire application and all C++ libraries it depends on, | |
398 | including the C++ standard library that ships with the | |
399 | compiler. This must be done even if only a small part of the | |
400 | program can use debugging features.</para></listitem> | |
401 | ||
402 | <listitem><para><emphasis>Full user recompilation</emphasis>: The user must recompile | |
403 | his or her entire application and all C++ libraries it depends | |
404 | on, but not the C++ standard library itself. This must be done | |
405 | even if only a small part of the program can use debugging | |
406 | features. This can be achieved given a full recompilation | |
407 | system by compiling two versions of the standard library when | |
408 | the compiler is installed and linking against the appropriate | |
409 | one, e.g., a multilibs approach.</para></listitem> | |
410 | ||
411 | <listitem><para><emphasis>Partial recompilation</emphasis>: The user must recompile the | |
412 | parts of his or her application and the C++ libraries it | |
413 | depends on that will use the debugging facilities | |
414 | directly. This means that any code that uses the debuggable | |
415 | standard containers would need to be recompiled, but code | |
416 | that does not use them (but may, for instance, use IOStreams) | |
417 | would not have to be recompiled.</para></listitem> | |
418 | ||
419 | <listitem><para><emphasis>Per-use recompilation</emphasis>: The user must recompile the | |
420 | parts of his or her application and the C++ libraries it | |
421 | depends on where debugging should occur, and any other code | |
422 | that interacts with those containers. This means that a set of | |
423 | translation units that accesses a particular standard | |
424 | container instance may either be compiled in release mode (no | |
425 | checking) or debug mode (full checking), but must all be | |
426 | compiled in the same way; a translation unit that does not see | |
427 | that standard container instance need not be recompiled. This | |
428 | also means that a translation unit <emphasis>A</emphasis> that contains a | |
429 | particular instantiation | |
430 | (say, <code>std::vector<int></code>) compiled in release | |
431 | mode can be linked against a translation unit <emphasis>B</emphasis> that | |
432 | contains the same instantiation compiled in debug mode (a | |
433 | feature not present with partial recompilation). While this | |
434 | behavior is technically a violation of the One Definition | |
435 | Rule, this ability tends to be very important in | |
436 | practice. The libstdc++ debug mode supports this level of | |
437 | recompilation. </para></listitem> | |
438 | ||
439 | <listitem><para><emphasis>Per-unit recompilation</emphasis>: The user must only | |
440 | recompile the translation units where checking should occur, | |
441 | regardless of where debuggable standard containers are | |
442 | used. This has also been dubbed "<code>-g</code> mode", | |
443 | because the <code>-g</code> compiler switch works in this way, | |
444 | emitting debugging information at a per--translation-unit | |
445 | granularity. We believe that this level of recompilation is in | |
446 | fact not possible if we intend to supply safe iterators, leave | |
447 | the program semantics unchanged, and not regress in | |
448 | performance under release mode because we cannot associate | |
449 | extra information with an iterator (to form a safe iterator) | |
450 | without either reserving that space in release mode | |
451 | (performance regression) or allocating extra memory associated | |
452 | with each iterator with <code>new</code> (changes the program | |
453 | semantics).</para></listitem> | |
454 | </orderedlist> | |
455 | </para></listitem> | |
456 | </itemizedlist> | |
c6a21af2 | 457 | </section> |
8a165db0 | 458 | |
c6a21af2 | 459 | <section xml:id="debug_mode.design.methods" xreflabel="Methods"><info><title>Methods</title></info> |
16d0b033 | 460 | |
8a165db0 BK |
461 | <para> |
462 | </para> | |
463 | <para>This section provides an overall view of the design of the | |
464 | libstdc++ debug mode and details the relationship between design | |
465 | decisions and the stated design goals.</para> | |
466 | ||
c6a21af2 | 467 | <section xml:id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"><info><title>The Wrapper Model</title></info> |
16d0b033 | 468 | |
50fbf0c3 BK |
469 | <para>The libstdc++ debug mode uses a wrapper model where the |
470 | debugging versions of library components (e.g., iterators and | |
471 | containers) form a layer on top of the release versions of the | |
472 | library components. The debugging components first verify that the | |
473 | operation is correct (aborting with a diagnostic if an error is | |
474 | found) and will then forward to the underlying release-mode | |
475 | container that will perform the actual work. This design decision | |
476 | ensures that we cannot regress release-mode performance (because the | |
477 | release-mode containers are left untouched) and partially | |
478 | enables <link linkend="methods.coexistence.link">mixing debug and | |
479 | release code</link> at link time, although that will not be | |
480 | discussed at this time.</para> | |
8a165db0 BK |
481 | |
482 | <para>Two types of wrappers are used in the implementation of the debug | |
483 | mode: container wrappers and iterator wrappers. The two types of | |
484 | wrappers interact to maintain relationships between iterators and | |
485 | their associated containers, which are necessary to detect certain | |
486 | types of standard library usage errors such as dereferencing | |
487 | past-the-end iterators or inserting into a container using an | |
488 | iterator from a different container.</para> | |
489 | ||
c6a21af2 | 490 | <section xml:id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"><info><title>Safe Iterators</title></info> |
16d0b033 | 491 | |
8a165db0 BK |
492 | <para>Iterator wrappers provide a debugging layer over any iterator that |
493 | is attached to a particular container, and will manage the | |
494 | information detailing the iterator's state (singular, | |
495 | dereferenceable, etc.) and tracking the container to which the | |
496 | iterator is attached. Because iterators have a well-defined, common | |
497 | interface the iterator wrapper is implemented with the iterator | |
498 | adaptor class template <code>__gnu_debug::_Safe_iterator</code>, | |
499 | which takes two template parameters:</para> | |
500 | ||
501 | <itemizedlist> | |
502 | <listitem><para><code>Iterator</code>: The underlying iterator type, which must | |
503 | be either the <code>iterator</code> or <code>const_iterator</code> | |
504 | typedef from the sequence type this iterator can reference.</para></listitem> | |
03a32789 | 505 | |
8a165db0 BK |
506 | <listitem><para><code>Sequence</code>: The type of sequence that this iterator |
507 | references. This sequence must be a safe sequence (discussed below) | |
508 | whose <code>iterator</code> or <code>const_iterator</code> typedef | |
509 | is the type of the safe iterator.</para></listitem> | |
510 | </itemizedlist> | |
c6a21af2 | 511 | </section> |
8a165db0 | 512 | |
c6a21af2 | 513 | <section xml:id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"><info><title>Safe Sequences (Containers)</title></info> |
16d0b033 | 514 | |
8a165db0 BK |
515 | |
516 | <para>Container wrappers provide a debugging layer over a particular | |
517 | container type. Because containers vary greatly in the member | |
518 | functions they support and the semantics of those member functions | |
519 | (especially in the area of iterator invalidation), container | |
520 | wrappers are tailored to the container they reference, e.g., the | |
521 | debugging version of <code>std::list</code> duplicates the entire | |
522 | interface of <code>std::list</code>, adding additional semantic | |
523 | checks and then forwarding operations to the | |
524 | real <code>std::list</code> (a public base class of the debugging | |
525 | version) as appropriate. However, all safe containers inherit from | |
526 | the class template <code>__gnu_debug::_Safe_sequence</code>, | |
527 | instantiated with the type of the safe container itself (an instance | |
528 | of the curiously recurring template pattern).</para> | |
529 | ||
03a32789 | 530 | <para>The iterators of a container wrapper will be |
50fbf0c3 BK |
531 | <link linkend="debug_mode.design.methods.safe_iter">safe |
532 | iterators</link> that reference sequences of this type and wrap the | |
533 | iterators provided by the release-mode base class. The debugging | |
534 | container will use only the safe iterators within its own interface | |
535 | (therefore requiring the user to use safe iterators, although this | |
536 | does not change correct user code) and will communicate with the | |
537 | release-mode base class with only the underlying, unsafe, | |
538 | release-mode iterators that the base class exports.</para> | |
8a165db0 BK |
539 | |
540 | <para> The debugging version of <code>std::list</code> will have the | |
541 | following basic structure:</para> | |
542 | ||
543 | <programlisting> | |
544 | template<typename _Tp, typename _Allocator = allocator<_Tp> | |
545 | class debug-list : | |
546 | public release-list<_Tp, _Allocator>, | |
547 | public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> > | |
548 | { | |
549 | typedef release-list<_Tp, _Allocator> _Base; | |
550 | typedef debug-list<_Tp, _Allocator> _Self; | |
551 | ||
552 | public: | |
553 | typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self> iterator; | |
554 | typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator; | |
555 | ||
556 | // duplicate std::list interface with debugging semantics | |
557 | }; | |
558 | </programlisting> | |
c6a21af2 BK |
559 | </section> |
560 | </section> | |
8a165db0 | 561 | |
c6a21af2 | 562 | <section xml:id="debug_mode.design.methods.precond" xreflabel="Precondition check"><info><title>Precondition Checking</title></info> |
16d0b033 | 563 | |
8a165db0 BK |
564 | <para>The debug mode operates primarily by checking the preconditions of |
565 | all standard library operations that it supports. Preconditions that | |
566 | are always checked (regardless of whether or not we are in debug | |
567 | mode) are checked via the <code>__check_xxx</code> macros defined | |
568 | and documented in the source | |
569 | file <code>include/debug/debug.h</code>. Preconditions that may or | |
570 | may not be checked, depending on the debug-mode | |
571 | macro <code>_GLIBCXX_DEBUG</code>, are checked via | |
572 | the <code>__requires_xxx</code> macros defined and documented in the | |
573 | same source file. Preconditions are validated using any additional | |
574 | information available at run-time, e.g., the containers that are | |
575 | associated with a particular iterator, the position of the iterator | |
576 | within those containers, the distance between two iterators that may | |
577 | form a valid range, etc. In the absence of suitable information, | |
578 | e.g., an input iterator that is not a safe iterator, these | |
579 | precondition checks will silently succeed.</para> | |
580 | ||
581 | <para>The majority of precondition checks use the aforementioned macros, | |
582 | which have the secondary benefit of having prewritten debug | |
583 | messages that use information about the current status of the | |
584 | objects involved (e.g., whether an iterator is singular or what | |
585 | sequence it is attached to) along with some static information | |
586 | (e.g., the names of the function parameters corresponding to the | |
587 | objects involved). When not using these macros, the debug mode uses | |
588 | either the debug-mode assertion | |
589 | macro <code>_GLIBCXX_DEBUG_ASSERT</code> , its pedantic | |
590 | cousin <code>_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion | |
591 | check macro that supports more advance formulation of error | |
592 | messages, <code>_GLIBCXX_DEBUG_VERIFY</code>. These macros are | |
593 | documented more thoroughly in the debug mode source code.</para> | |
c6a21af2 | 594 | </section> |
8a165db0 | 595 | |
c6a21af2 | 596 | <section xml:id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"><info><title>Release- and debug-mode coexistence</title></info> |
16d0b033 | 597 | |
8a165db0 BK |
598 | <para>The libstdc++ debug mode is the first debug mode we know of that |
599 | is able to provide the "Per-use recompilation" (4) guarantee, that | |
600 | allows release-compiled and debug-compiled code to be linked and | |
601 | executed together without causing unpredictable behavior. This | |
602 | guarantee minimizes the recompilation that users are required to | |
4394b61e | 603 | perform, shortening the detect-compile-debug bug hunting cycle |
8a165db0 BK |
604 | and making the debug mode easier to incorporate into development |
605 | environments by minimizing dependencies.</para> | |
606 | ||
607 | <para>Achieving link- and run-time coexistence is not a trivial | |
1a5a334e GP |
608 | implementation task. To achieve this goal we use inline namespaces and |
609 | a complex organization of debug- and release-modes. The end result is | |
610 | that we have achieved per-use recompilation but have had to give up | |
611 | some checking of the <code>std::basic_string</code> class template | |
612 | (namely, safe iterators).</para> | |
8a165db0 | 613 | |
c6a21af2 | 614 | <section xml:id="methods.coexistence.compile" xreflabel="Compile"><info><title>Compile-time coexistence of release- and debug-mode components</title></info> |
16d0b033 | 615 | |
8a165db0 BK |
616 | |
617 | <para>Both the release-mode components and the debug-mode | |
618 | components need to exist within a single translation unit so that | |
619 | the debug versions can wrap the release versions. However, only one | |
620 | of these components should be user-visible at any particular | |
621 | time with the standard name, e.g., <code>std::list</code>. </para> | |
622 | ||
623 | <para>In release mode, we define only the release-mode version of the | |
624 | component with its standard name and do not include the debugging | |
625 | component at all. The release mode version is defined within the | |
626 | namespace <code>std</code>. Minus the namespace associations, this | |
627 | method leaves the behavior of release mode completely unchanged from | |
628 | its behavior prior to the introduction of the libstdc++ debug | |
629 | mode. Here's an example of what this ends up looking like, in | |
630 | C++.</para> | |
631 | ||
632 | <programlisting> | |
633 | namespace std | |
634 | { | |
635 | template<typename _Tp, typename _Alloc = allocator<_Tp> > | |
636 | class list | |
637 | { | |
638 | // ... | |
639 | }; | |
640 | } // namespace std | |
641 | </programlisting> | |
03a32789 | 642 | |
8a165db0 | 643 | <para>In debug mode we include the release-mode container (which is now |
d2b0caaa | 644 | defined in the namespace <code>__cxx1998</code>) and also the |
8a165db0 BK |
645 | debug-mode container. The debug-mode container is defined within the |
646 | namespace <code>__debug</code>, which is associated with namespace | |
f25481f4 | 647 | <code>std</code> via the C++11 namespace association language feature. This |
8a165db0 BK |
648 | method allows the debug and release versions of the same component to |
649 | coexist at compile-time and link-time without causing an unreasonable | |
650 | maintenance burden, while minimizing confusion. Again, this boils down | |
651 | to C++ code as follows:</para> | |
652 | ||
653 | <programlisting> | |
654 | namespace std | |
655 | { | |
d2b0caaa | 656 | namespace __cxx1998 |
8a165db0 BK |
657 | { |
658 | template<typename _Tp, typename _Alloc = allocator<_Tp> > | |
659 | class list | |
660 | { | |
03a32789 | 661 | // ... |
8a165db0 BK |
662 | }; |
663 | } // namespace __gnu_norm | |
664 | ||
665 | namespace __debug | |
666 | { | |
667 | template<typename _Tp, typename _Alloc = allocator<_Tp> > | |
668 | class list | |
d2b0caaa | 669 | : public __cxx1998::list<_Tp, _Alloc>, |
03a32789 | 670 | public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > |
8a165db0 | 671 | { |
03a32789 | 672 | // ... |
8a165db0 | 673 | }; |
d2b0caaa | 674 | } // namespace __cxx1998 |
8a165db0 | 675 | |
50fbf0c3 | 676 | inline namespace __debug { } |
8a165db0 BK |
677 | } |
678 | </programlisting> | |
c6a21af2 | 679 | </section> |
8a165db0 | 680 | |
c6a21af2 BK |
681 | <section xml:id="methods.coexistence.link" xreflabel="Link"><info><title>Link- and run-time coexistence of release- and |
682 | debug-mode components</title></info> | |
16d0b033 | 683 | |
8a165db0 BK |
684 | |
685 | <para>Because each component has a distinct and separate release and | |
e2553a4c | 686 | debug implementation, there is no issue with link-time |
8a165db0 BK |
687 | coexistence: the separate namespaces result in different mangled |
688 | names, and thus unique linkage.</para> | |
689 | ||
690 | <para>However, components that are defined and used within the C++ | |
691 | standard library itself face additional constraints. For instance, | |
692 | some of the member functions of <code> std::moneypunct</code> return | |
693 | <code>std::basic_string</code>. Normally, this is not a problem, but | |
694 | with a mixed mode standard library that could be using either | |
695 | debug-mode or release-mode <code> basic_string</code> objects, things | |
696 | get more complicated. As the return value of a function is not | |
697 | encoded into the mangled name, there is no way to specify a | |
698 | release-mode or a debug-mode string. In practice, this results in | |
699 | runtime errors. A simplified example of this problem is as follows. | |
700 | </para> | |
701 | ||
702 | <para> Take this translation unit, compiled in debug-mode: </para> | |
703 | <programlisting> | |
704 | // -D_GLIBCXX_DEBUG | |
705 | #include <string> | |
706 | ||
707 | std::string test02(); | |
03a32789 | 708 | |
8a165db0 BK |
709 | std::string test01() |
710 | { | |
711 | return test02(); | |
712 | } | |
03a32789 | 713 | |
8a165db0 BK |
714 | int main() |
715 | { | |
716 | test01(); | |
717 | return 0; | |
718 | } | |
719 | </programlisting> | |
720 | ||
721 | <para> ... and linked to this translation unit, compiled in release mode:</para> | |
722 | ||
723 | <programlisting> | |
724 | #include <string> | |
03a32789 | 725 | |
8a165db0 BK |
726 | std::string |
727 | test02() | |
728 | { | |
729 | return std::string("toast"); | |
730 | } | |
731 | </programlisting> | |
732 | ||
733 | <para> For this reason we cannot easily provide safe iterators for | |
734 | the <code>std::basic_string</code> class template, as it is present | |
735 | throughout the C++ standard library. For instance, locale facets | |
736 | define typedefs that include <code>basic_string</code>: in a mixed | |
737 | debug/release program, should that typedef be based on the | |
738 | debug-mode <code>basic_string</code> or the | |
739 | release-mode <code>basic_string</code>? While the answer could be | |
740 | "both", and the difference hidden via renaming a la the | |
741 | debug/release containers, we must note two things about locale | |
742 | facets:</para> | |
743 | ||
c6a21af2 | 744 | <orderedlist inheritnum="ignore" continuation="restarts"> |
8a165db0 BK |
745 | <listitem><para>They exist as shared state: one can create a facet in one |
746 | translation unit and access the facet via the same type name in a | |
747 | different translation unit. This means that we cannot have two | |
748 | different versions of locale facets, because the types would not be | |
749 | the same across debug/release-mode translation unit barriers.</para></listitem> | |
750 | ||
751 | <listitem><para>They have virtual functions returning strings: these functions | |
752 | mangle in the same way regardless of the mangling of their return | |
753 | types (see above), and their precise signatures can be relied upon | |
754 | by users because they may be overridden in derived classes.</para></listitem> | |
755 | </orderedlist> | |
756 | ||
757 | <para>With the design of libstdc++ debug mode, we cannot effectively hide | |
758 | the differences between debug and release-mode strings from the | |
759 | user. Failure to hide the differences may result in unpredictable | |
760 | behavior, and for this reason we have opted to only | |
761 | perform <code>basic_string</code> changes that do not require ABI | |
762 | changes. The effect on users is expected to be minimal, as there are | |
763 | simple alternatives (e.g., <code>__gnu_debug::basic_string</code>), | |
764 | and the usability benefit we gain from the ability to mix debug- and | |
765 | release-compiled translation units is enormous.</para> | |
c6a21af2 BK |
766 | </section> |
767 | ||
768 | <section xml:id="methods.coexistence.alt" xreflabel="Alternatives"><info><title>Alternatives for Coexistence</title></info> | |
8a165db0 | 769 | |
8a165db0 BK |
770 | |
771 | <para>The coexistence scheme above was chosen over many alternatives, | |
772 | including language-only solutions and solutions that also required | |
773 | extensions to the C++ front end. The following is a partial list of | |
774 | solutions, with justifications for our rejection of each.</para> | |
775 | ||
776 | <itemizedlist> | |
777 | <listitem><para><emphasis>Completely separate debug/release libraries</emphasis>: This is by | |
778 | far the simplest implementation option, where we do not allow any | |
779 | coexistence of debug- and release-compiled translation units in a | |
780 | program. This solution has an extreme negative affect on usability, | |
781 | because it is quite likely that some libraries an application | |
782 | depends on cannot be recompiled easily. This would not meet | |
783 | our <emphasis>usability</emphasis> or <emphasis>minimize recompilation</emphasis> criteria | |
784 | well.</para></listitem> | |
785 | ||
786 | <listitem><para><emphasis>Add a <code>Debug</code> boolean template parameter</emphasis>: | |
787 | Partial specialization could be used to select the debug | |
788 | implementation when <code>Debug == true</code>, and the state | |
789 | of <code>_GLIBCXX_DEBUG</code> could decide whether the | |
790 | default <code>Debug</code> argument is <code>true</code> | |
791 | or <code>false</code>. This option would break conformance with the | |
792 | C++ standard in both debug <emphasis>and</emphasis> release modes. This would | |
793 | not meet our <emphasis>correctness</emphasis> criteria. </para></listitem> | |
794 | ||
795 | <listitem><para><emphasis>Packaging a debug flag in the allocators</emphasis>: We could | |
796 | reuse the <code>Allocator</code> template parameter of containers | |
797 | by adding a sentinel wrapper <code>debug<></code> that | |
798 | signals the user's intention to use debugging, and pick up | |
799 | the <code>debug<></code> allocator wrapper in a partial | |
800 | specialization. However, this has two drawbacks: first, there is a | |
801 | conformance issue because the default allocator would not be the | |
802 | standard-specified <code>std::allocator<T></code>. Secondly | |
803 | (and more importantly), users that specify allocators instead of | |
804 | implicitly using the default allocator would not get debugging | |
805 | containers. Thus this solution fails the <emphasis>correctness</emphasis> | |
806 | criteria.</para></listitem> | |
807 | ||
808 | <listitem><para><emphasis>Define debug containers in another namespace, and employ | |
809 | a <code>using</code> declaration (or directive)</emphasis>: This is an | |
810 | enticing option, because it would eliminate the need for | |
811 | the <code>link_name</code> extension by aliasing the | |
812 | templates. However, there is no true template aliasing mechanism | |
e2553a4c | 813 | in C++, because both <code>using</code> directives and using |
8a165db0 BK |
814 | declarations disallow specialization. This method fails |
815 | the <emphasis>correctness</emphasis> criteria.</para></listitem> | |
816 | ||
817 | <listitem><para><emphasis> Use implementation-specific properties of anonymous | |
818 | namespaces. </emphasis> | |
1b75c936 | 819 | See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html">this post</link>. |
8a165db0 BK |
820 | This method fails the <emphasis>correctness</emphasis> criteria.</para></listitem> |
821 | ||
822 | <listitem><para><emphasis>Extension: allow reopening on namespaces</emphasis>: This would | |
823 | allow the debug mode to effectively alias the | |
824 | namespace <code>std</code> to an internal namespace, such | |
825 | as <code>__gnu_std_debug</code>, so that it is completely | |
826 | separate from the release-mode <code>std</code> namespace. While | |
827 | this will solve some renaming problems and ensure that | |
828 | debug- and release-compiled code cannot be mixed unsafely, it ensures that | |
829 | debug- and release-compiled code cannot be mixed at all. For | |
830 | instance, the program would have two <code>std::cout</code> | |
831 | objects! This solution would fails the <emphasis>minimize | |
832 | recompilation</emphasis> requirement, because we would only be able to | |
833 | support option (1) or (2).</para></listitem> | |
834 | ||
1b75c936 JW |
835 | <listitem><para><emphasis>Extension: use link name</emphasis>: This option |
836 | involves complicated re-naming between debug-mode and release-mode | |
8a165db0 BK |
837 | components at compile time, and then a g++ extension called <emphasis> |
838 | link name </emphasis> to recover the original names at link time. There | |
839 | are two drawbacks to this approach. One, it's very verbose, | |
840 | relying on macro renaming at compile time and several levels of | |
841 | include ordering. Two, ODR issues remained with container member | |
842 | functions taking no arguments in mixed-mode settings resulting in | |
843 | equivalent link names, <code> vector::push_back() </code> being | |
03a32789 | 844 | one example. |
1b75c936 JW |
845 | See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">proof-of-concept using link |
846 | name</link>. </para></listitem> | |
8a165db0 BK |
847 | </itemizedlist> |
848 | ||
849 | <para>Other options may exist for implementing the debug mode, many of | |
850 | which have probably been considered and others that may still be | |
851 | lurking. This list may be expanded over time to include other | |
852 | options that we could have implemented, but in all cases the full | |
853 | ramifications of the approach (as measured against the design goals | |
854 | for a libstdc++ debug mode) should be considered first. The DejaGNU | |
855 | testsuite includes some testcases that check for known problems with | |
856 | some solutions (e.g., the <code>using</code> declaration solution | |
857 | that breaks user specialization), and additional testcases will be | |
858 | added as we are able to identify other typical problem cases. These | |
859 | test cases will serve as a benchmark by which we can compare debug | |
860 | mode implementations.</para> | |
c6a21af2 BK |
861 | </section> |
862 | </section> | |
863 | </section> | |
8a165db0 | 864 | |
c6a21af2 | 865 | <section xml:id="debug_mode.design.other" xreflabel="Other"><info><title>Other Implementations</title></info> |
16d0b033 | 866 | |
8a165db0 BK |
867 | <para> |
868 | </para> | |
869 | <para> There are several existing implementations of debug modes for C++ | |
870 | standard library implementations, although none of them directly | |
871 | supports debugging for programs using libstdc++. The existing | |
872 | implementations include:</para> | |
873 | <itemizedlist> | |
8bebe0af | 874 | <listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</link>: |
8a165db0 BK |
875 | SafeSTL was the original debugging version of the Standard Template |
876 | Library (STL), implemented by Cay S. Horstmann on top of the | |
877 | Hewlett-Packard STL. Though it inspired much work in this area, it | |
878 | has not been kept up-to-date for use with modern compilers or C++ | |
879 | standard library implementations.</para></listitem> | |
880 | ||
c6a21af2 | 881 | <listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stlport.org/">STLport</link>: STLport is a free |
25949ee3 | 882 | implementation of the C++ standard library derived from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/">SGI implementation</link>, and |
8a165db0 | 883 | ported to many other platforms. It includes a debug mode that uses a |
50fbf0c3 | 884 | wrapper model (that in some ways inspired the libstdc++ debug mode |
8a165db0 BK |
885 | design), although at the time of this writing the debug mode is |
886 | somewhat incomplete and meets only the "Full user recompilation" (2) | |
887 | recompilation guarantee by requiring the user to link against a | |
888 | different library in debug mode vs. release mode.</para></listitem> | |
889 | ||
50fbf0c3 BK |
890 | <listitem><para>Metrowerks CodeWarrior: The C++ standard library |
891 | that ships with Metrowerks CodeWarrior includes a debug mode. It is | |
892 | a full debug-mode implementation (including debugging for | |
893 | CodeWarrior extensions) and is easy to use, although it meets only | |
894 | the "Full recompilation" (1) recompilation | |
895 | guarantee.</para></listitem> | |
8a165db0 BK |
896 | </itemizedlist> |
897 | ||
c6a21af2 BK |
898 | </section> |
899 | </section> | |
8a165db0 BK |
900 | |
901 | </chapter> |