source: general/prog/gdb.xml@ 7a34460d

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY gdb-download-http "https://ftp.gnu.org/gnu/gdb/gdb-&gdb-version;.tar.xz">
  <!ENTITY gdb-download-ftp  "ftp://ftp.gnu.org/gnu/gdb/gdb-&gdb-version;.tar.xz">
  <!ENTITY gdb-md5sum        "39e654460c9cdd80200a29ac020cfe11">
  <!ENTITY gdb-size          "18 MB">
  <!ENTITY gdb-buildsize     "419 MB (additional 349 MB for tests)">
  <!ENTITY gdb-time          "2.4 SBU (add up to 7.8 SBU for tests)">
]>

<sect1 id="gdb" xreflabel="GDB-&gdb-version;">
  <?dbhtml filename="gdb.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>GDB-&gdb-version;</title>

  <indexterm zone="gdb">
    <primary sortas="a-GDB">GDB</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to GDB</title>

    <para>
      <application>GDB</application>, the GNU Project debugger, allows you
      to see what is going on <quote>inside</quote> another program while it
      executes -- or what another program was doing at the moment it crashed.
      Note that <application>GDB</application> is most effective when tracing
      programs and libraries that were built with debugging symbols and not
      stripped.
    </para>

    &lfs79_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&gdb-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&gdb-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &gdb-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &gdb-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &gdb-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &gdb-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">GDB Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="dejagnu"/> (for tests),
      <xref linkend="doxygen"/>,
      <xref linkend="guile"/>,
      <xref linkend="python2"/>,
      <xref linkend="valgrind"/>, and
      <ulink url="https://sourceware.org/systemtap/">SystemTap</ulink>
      (run-time dependency, also used in a few tests)
    </para>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/gdb"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of GDB</title>

    <para>
      Install <application>GDB</application> by running the following
      commands:
    </para>

<screen><userinput>./configure --prefix=/usr --with-system-readline &amp;&amp;
make</userinput></screen>

    <para>
      Optionally, to build the API documentation using
      <xref linkend="doxygen"/>, run:
    </para>

<screen><userinput>make -C gdb/doc doxy</userinput></screen>

    <para>
      To test the results, issue:
    </para>

<screen><userinput>pushd gdb/testsuite &amp;&amp;
make  site.exp      &amp;&amp;
echo  "set gdb_test_timeout 120" &gt;&gt; site.exp &amp;&amp;
runtest TRANSCRIPT=y
popd</userinput></screen>

    <para>
      See <emphasis>gdb/testsuite/README</emphasis> and <ulink
      url="https://sourceware.org/gdb/wiki/TestingGDB">TestingGDB</ulink>.
      There are many problems with the test suite. First one is that you need
      to clean some directories, if re-running the tests. For that reason, it
      is recommended to make a copy of the compiled source code directory,
      before the tests, in case you need to run the tests again. Results depend
      on installed compilers, there are differences if run locally or remotely,
      a large number of timeouts (there is a variable that can be set to
      increase time for timeout, but changing it, apparently the total number
      of tests is not conserved), there are failures associated with system
      readline 6.x, between others. A few tests assume that the header file
      <filename>&lt;sys/sdt.h&gt;</filename>, part of <ulink
      url="https://sourceware.org/systemtap/">SystemTap</ulink>, is present.
      Unexpected failures are less than 0.3%.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make -C gdb install</userinput></screen>

    <para>
      If you have built the API documentation, it is now in gdb/doc/doxy.
      You can install it (as the <systemitem class="username">root</systemitem>
      user):
    </para>

<screen role="root"><userinput>install -d /usr/share/doc/gdb-&gdb-version; &amp;&amp;
rm -rf gdb/doc/doxy/xml &amp;&amp;
cp -Rv gdb/doc/doxy /usr/share/doc/gdb-&gdb-version;</userinput></screen>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          gcore, gdb and gdbserver
        </seg>
        <seg>
          libinproctrace.so
        </seg>
        <seg>
          /usr/{include,share}/gdb and /usr/share/doc/gdb-&gdb-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gcore">
        <term><command>gcore</command></term>
        <listitem>
          <para>
            generates a core dump of a running program.
          </para>
          <indexterm zone="gdb gcore">
            <primary sortas="b-gcore">gcore</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gdb-prog">
        <term><command>gdb</command></term>
        <listitem>
          <para>
            is the GNU Debugger.
          </para>
          <indexterm zone="gdb gdb-prog">
            <primary sortas="b-gdb-prog">gdb-prog</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gdbserver">
        <term><command>gdbserver</command></term>
        <listitem>
          <para>
            is a remote server for the GNU debugger (it allows programs
            to be debugged from a different machine).
          </para>
          <indexterm zone="gdb gdbserver">
            <primary sortas="b-gdbserver">gdbserver</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libinproctrace">
        <term><filename class="libraryfile">libinproctrace.so</filename></term>
        <listitem>
          <para>
            contains functions for the in-process tracing agent. The agent
            allows for installing fast tracepoints, listing static tracepoint
            markers, probing static tracepoints markers, and starting trace
            monitoring.
          </para>
          <indexterm zone="gdb libinproctrace">
            <primary sortas="c-libinproctrace">libinproctrace.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>