source: general/prog/gdb.xml@ b09ae7a

lazarus trunk
Last change on this file since b09ae7a was 715f392, checked in by Douglas R. Reno <renodr@…>, 3 months ago

Update to gdb-14.2

  • Property mode set to 100644
File size: 11.1 KB
RevLine 
[ab4fdfc]1<?xml version="1.0" encoding="UTF-8"?>
[4b0ebf70]2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
[8dfc5c3]7 <!ENTITY gdb-download-http "&gnu-http;/gdb/gdb-&gdb-version;.tar.xz">
[e1e58be]8 <!ENTITY gdb-download-ftp " ">
[715f392]9 <!ENTITY gdb-md5sum "4452f575d09f94276cb0a1e95ecff856">
[6f0a8c86]10 <!ENTITY gdb-size "23 MB">
[715f392]11 <!ENTITY gdb-buildsize "964 MB (add 805 MB for docs; add 654 MB for tests)">
12 <!ENTITY gdb-time "1.8 SBU (add 0.4 SBU for docs; add 15 SBU for tests; all using parallelism=4)">
[4b0ebf70]13]>
14
[d3970e1]15<sect1 id="gdb" xreflabel="GDB-&gdb-version;">
[4b0ebf70]16 <?dbhtml filename="gdb.html"?>
17
18
[d3970e1]19 <title>GDB-&gdb-version;</title>
[4b0ebf70]20
21 <indexterm zone="gdb">
[4890200]22 <primary sortas="a-GDB">GDB</primary>
[4b0ebf70]23 </indexterm>
24
25 <sect2 role="package">
[d3970e1]26 <title>Introduction to GDB</title>
27
28 <para>
29 <application>GDB</application>, the GNU Project debugger, allows you
30 to see what is going on <quote>inside</quote> another program while it
31 executes -- or what another program was doing at the moment it crashed.
32 Note that <application>GDB</application> is most effective when tracing
33 programs and libraries that were built with debugging symbols and not
34 stripped.
35 </para>
[4b0ebf70]36
[99c90fa]37 &lfs121_checked;
[4b0ebf70]38
39 <bridgehead renderas="sect3">Package Information</bridgehead>
40 <itemizedlist spacing="compact">
41 <listitem>
[4890200]42 <para>
43 Download (HTTP): <ulink url="&gdb-download-http;"/>
44 </para>
[4b0ebf70]45 </listitem>
46 <listitem>
[4890200]47 <para>
48 Download (FTP): <ulink url="&gdb-download-ftp;"/>
49 </para>
[4b0ebf70]50 </listitem>
51 <listitem>
[4890200]52 <para>
53 Download MD5 sum: &gdb-md5sum;
54 </para>
[4b0ebf70]55 </listitem>
56 <listitem>
[4890200]57 <para>
58 Download size: &gdb-size;
59 </para>
[4b0ebf70]60 </listitem>
61 <listitem>
[4890200]62 <para>
63 Estimated disk space required: &gdb-buildsize;
64 </para>
[4b0ebf70]65 </listitem>
66 <listitem>
[4890200]67 <para>
68 Estimated build time: &gdb-time;
69 </para>
[4b0ebf70]70 </listitem>
71 </itemizedlist>
[da73c1c]72 <!--
[17817c8]73 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
74 <itemizedlist spacing="compact">
75 <listitem>
76 <para>
77 Required patch:
78 <ulink url="&patch-root;/gdb-&gdb-version;-upstream_fixes-1.patch"/>
79 </para>
80 </listitem>
81 </itemizedlist>
[da73c1c]82 -->
[d3970e1]83 <bridgehead renderas="sect3">GDB Dependencies</bridgehead>
[d4c9b7c]84
[9533795]85 <bridgehead renderas="sect4">Recommended Runtime Dependency</bridgehead>
86 <para role="recommended">
87 <xref linkend="six"/> (Python 3 module, required at run-time to
88 use GDB scripts from various LFS/BLFS packages with Python 3
89 installed in LFS)
90 </para>
91
[d4c9b7c]92 <bridgehead renderas="sect4">Optional</bridgehead>
93 <para role="optional">
[852fc810]94 <xref linkend="doxygen"/>,
[a2e21ee]95 <xref linkend="gcc"/> (ada, gfortran, and go are used for tests),
[51cb7cd]96 <xref linkend="guile"/>,
97 <xref linkend="rust"/> (used for some tests),
[2029b72]98 <xref linkend="valgrind"/>, and
99 <ulink url="https://sourceware.org/systemtap/">SystemTap</ulink>
[51cb7cd]100 (run-time, used for tests)
[d4c9b7c]101 </para>
102
[4b0ebf70]103 </sect2>
104
105 <sect2 role="installation">
[d3970e1]106 <title>Installation of GDB</title>
[da73c1c]107 <!--
[d1e4f43]108 <para>
109 First, apply a patch that fixes problems when debugging programs compiled
110 with <xref linkend="rust" role="nodep"/>:
111 </para>
112
113<screen><userinput remap="pre">patch -Np1 -i ../gdb-&gdb-version;-upstream_fixes-1.patch</userinput></screen>
[da73c1c]114-->
[d3970e1]115 <para>
116 Install <application>GDB</application> by running the following
117 commands:
118 </para>
[4b0ebf70]119
[29d11601]120<screen><userinput>mkdir build &amp;&amp;
121cd build &amp;&amp;
122
123../configure --prefix=/usr \
124 --with-system-readline \
125 --with-python=/usr/bin/python3 &amp;&amp;
[4b0ebf70]126make</userinput></screen>
127
[46fd248]128 <para>
129 Optionally, to build the API documentation using
130 <xref linkend="doxygen"/>, run:
131 </para>
132
[a42c273]133<screen remap="doc"><userinput>make -C gdb/doc doxy</userinput></screen>
[46fd248]134
[d3970e1]135 <para>
[03b05e7]136 To test the results, issue:
137 </para>
138
[a42c273]139<screen remap="test"><userinput>pushd gdb/testsuite &amp;&amp;
[03b05e7]140make site.exp &amp;&amp;
141echo "set gdb_test_timeout 120" &gt;&gt; site.exp &amp;&amp;
[a114fcc]142runtest
[03b05e7]143popd</userinput></screen>
144
145 <para>
146 See <emphasis>gdb/testsuite/README</emphasis> and <ulink
147 url="https://sourceware.org/gdb/wiki/TestingGDB">TestingGDB</ulink>.
[39e42c88]148 There are many problems with the test suite:
[d3970e1]149 </para>
[8558044]150
[39e42c88]151 <itemizedlist>
152 <listitem>
153 <para>
[3e42104]154 Clean directories are needed if re-running the tests. For that
[6a1237d]155 reason, make a copy of the compiled source code
[8558044]156 directory before the tests in case you need to run the tests again.
[39e42c88]157 </para>
158 </listitem>
[8558044]159
[39e42c88]160 <listitem>
161 <para>
162 Results depend on installed compilers.
163 </para>
164 </listitem>
[8558044]165<!-- I did not see this
[39e42c88]166 <listitem>
167 <para>
[8558044]168 There are a large number of timeouts (there is a variable
169 that can be set to increase time for timeout, but
170 changing it will result in a different number of tests being
[3e42104]171 run).
[39e42c88]172 </para>
173 </listitem>
[29d11601]174or this
[39e42c88]175 <listitem>
176 <para>
177 There are failures associated with system readline 6.x.
178 </para>
179 </listitem>
[29d11601]180-->
[e2fe6d4]181<!--
[39e42c88]182 <listitem>
183 <para>
184 A few tests assume that the header file
185 <filename>&lt;sys/sdt.h&gt;</filename>, part of <ulink
186 url="https://sourceware.org/systemtap/">SystemTap</ulink>, is
187 present.
188 </para>
189 </listitem>
[e2fe6d4]190-->
[29d11601]191<!-- I don't know if this is true or not. I tested on a Haswell.
[24c0a06e]192 <listitem>
193 <para>
194 If the test suite is run on a Skylake-based Intel CPU or newer,
195 many tests will fail due to the removal of the deprecated/problematic
196 libmpx library in GCC.
197 </para>
198 </listitem>
[8558044]199-->
[39e42c88]200 <listitem>
201 <para>
[1fe05eb]202<!-- for gdb-11.1, gcc-11.2 - pierre
[54bd123]203 A test run of the test suite had about 1700 unexpected failures
[f863fd7d]204 (out of over 80000 tests). Over 1370 of the failures were related
[e2fe6d4]205 to FORTRAN tests. -->
[e440af5]206<!-- for gdb-12.1, gcc-11.3.0 - bdubbs
[e2fe6d4]207 A test run of the test suite had a little over 200 unexpected failures
[6f0a8c86]208 out of over 94000 tests.-->
[da73c1c]209<!-- for gdb-13.0, gcc-12.2.0 - bdubbs
[6f0a8c86]210 A test run of the test suite had 33 unexpected failures
[da73c1c]211 out of over 106000 tests. -->
[15abfad]212<!-- for gdb-13.2, gcc-13.1.0 - pierre
[da73c1c]213 A test run of the test suite had 183 unexpected failures
[15abfad]214 out of over 105000 tests. -->
215<!-- for gdb-14.1, gcc 13.2.0 - rahul -->
216 A test run of the test suite had 51 unexpected failures
217 out of the over 106000 tests.
[39e42c88]218 </para>
219 </listitem>
[aea8090f]220
[bfbc72a]221 <listitem>
222 <para>
223 On some systems, the gdb.tui test suite will fail if running over
224 SSH.
225 </para>
226 </listitem>
227
[aea8090f]228 <listitem>
229 <para>
230 On some AMD-based systems, over 200 additional tests
231 may fail due to a difference in the threading implementation
232 on those CPUs.
233 </para>
234 </listitem>
235
[39e42c88]236 </itemizedlist>
[4b0ebf70]237
[d3970e1]238 <para>
239 Now, as the <systemitem class="username">root</systemitem> user:
240 </para>
[4b0ebf70]241
[da73c1c]242<screen role="root"><userinput>make -C gdb install &amp;&amp;
243make -C gdbserver install</userinput></screen>
[4b0ebf70]244
[852fc810]245 <para>
[46fd248]246 If you have built the API documentation, it is now in gdb/doc/doxy.
247 You can install it (as the <systemitem class="username">root</systemitem>
248 user):
[852fc810]249 </para>
250
[a42c273]251<screen role="root"
252 remap="doc"><userinput>install -d /usr/share/doc/gdb-&gdb-version; &amp;&amp;
[03b05e7]253rm -rf gdb/doc/doxy/xml &amp;&amp;
[852fc810]254cp -Rv gdb/doc/doxy /usr/share/doc/gdb-&gdb-version;</userinput></screen>
255
[4b0ebf70]256 </sect2>
[d3970e1]257
[870e9f05]258 <sect2 role="commands">
259 <title>Command Explanations</title>
[8558044]260
[870e9f05]261 <para>
262 <parameter>--with-system-readline</parameter>: This switch forces
263 <application>GDB</application> to use the copy of
264 <application>Readline</application> installed in LFS.
265 </para>
266
[d38dc9a]267 <para>
268 <parameter>--with-python=/usr/bin/python3</parameter>: This switch
[54bd123]269 forces <application>GDB</application> to use Python 3.
[d38dc9a]270 </para>
271
[870e9f05]272 </sect2>
273
[4b0ebf70]274 <sect2 role="content">
275 <title>Contents</title>
276
277 <segmentedlist>
278 <segtitle>Installed Programs</segtitle>
279 <segtitle>Installed Library</segtitle>
280 <segtitle>Installed Directories</segtitle>
281
282 <seglistitem>
[4890200]283 <seg>
[da73c1c]284 gcore, gdb, gdbserver, and gdb-add-index
[4890200]285 </seg>
286 <seg>
[da73c1c]287 libinproctrace.so
[4890200]288 </seg>
289 <seg>
[03b05e7]290 /usr/{include,share}/gdb and /usr/share/doc/gdb-&gdb-version;
[4890200]291 </seg>
[4b0ebf70]292 </seglistitem>
293 </segmentedlist>
294
295 <variablelist>
296 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
297 <?dbfo list-presentation="list"?>
298 <?dbhtml list-presentation="table"?>
299
[a55a187]300 <varlistentry id="gcore">
301 <term><command>gcore</command></term>
302 <listitem>
303 <para>
[4c24eb0a]304 generates a core dump of a running program
[a55a187]305 </para>
306 <indexterm zone="gdb gcore">
307 <primary sortas="b-gcore">gcore</primary>
308 </indexterm>
309 </listitem>
310 </varlistentry>
311
[4b0ebf70]312 <varlistentry id="gdb-prog">
313 <term><command>gdb</command></term>
314 <listitem>
[d3970e1]315 <para>
[4c24eb0a]316 is the GNU Debugger
[d3970e1]317 </para>
[4b0ebf70]318 <indexterm zone="gdb gdb-prog">
319 <primary sortas="b-gdb-prog">gdb-prog</primary>
320 </indexterm>
321 </listitem>
322 </varlistentry>
323
324 <varlistentry id="gdbserver">
325 <term><command>gdbserver</command></term>
326 <listitem>
[d3970e1]327 <para>
[4890200]328 is a remote server for the GNU debugger (it allows programs
[4c24eb0a]329 to be debugged from a different machine)
[d3970e1]330 </para>
[4b0ebf70]331 <indexterm zone="gdb gdbserver">
332 <primary sortas="b-gdbserver">gdbserver</primary>
333 </indexterm>
334 </listitem>
335 </varlistentry>
336
[11f9b1d1]337 <varlistentry id="gdb-add-index">
338 <term><command>gdb-add-index</command></term>
339 <listitem>
340 <para>
341 Allows adding index files to ELF binaries. This speeds up
342 <command>gdb</command> start on large programs.
343 </para>
344 <indexterm zone="gdb gdb-add-index">
345 <primary sortas="b-gdb-add-index">gdb-add-index</primary>
346 </indexterm>
347 </listitem>
348 </varlistentry>
349
[4b0ebf70]350 <varlistentry id="libinproctrace">
[4890200]351 <term><filename class="libraryfile">libinproctrace.so</filename></term>
[4b0ebf70]352 <listitem>
[d3970e1]353 <para>
354 contains functions for the in-process tracing agent. The agent
355 allows for installing fast tracepoints, listing static tracepoint
356 markers, probing static tracepoints markers, and starting trace
357 monitoring.
358 </para>
[4b0ebf70]359 <indexterm zone="gdb libinproctrace">
360 <primary sortas="c-libinproctrace">libinproctrace.so</primary>
361 </indexterm>
362 </listitem>
[d3970e1]363 </varlistentry>
[11f9b1d1]364
[4b0ebf70]365 </variablelist>
366
367 </sect2>
368
369</sect1>
Note: See TracBrowser for help on using the repository browser.