glfs/general/prog/valgrind.xml

371 lines
12 KiB
XML
Raw Normal View History

<?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 valgrind-download-http "https://sourceware.org/ftp/valgrind/valgrind-&valgrind-version;.tar.bz2">
<!ENTITY valgrind-download-ftp "ftp://sourceware.org/pub/valgrind/valgrind-&valgrind-version;.tar.bz2">
<!ENTITY valgrind-md5sum "817dd08f1e8a66336b9ff206400a5369">
<!ENTITY valgrind-size "14 MB">
<!ENTITY valgrind-buildsize "347 MB (additional 228 MB for tests)">
<!ENTITY valgrind-time "1.1 SBU (additional 5.1 SBU for tests)">
]>
<sect1 id="valgrind" xreflabel="Valgrind-&valgrind-version;">
<?dbhtml filename="valgrind.html"?>
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<title>Valgrind-&valgrind-version;</title>
<indexterm zone="valgrind">
<primary sortas="a-Valgrind">Valgrind</primary>
</indexterm>
<sect2 role="package">
<title>Introduction to Valgrind</title>
<para>
<application>Valgrind</application> is an instrumentation framework for
building dynamic analysis tools. There are Valgrind tools that can
automatically detect many memory management and threading bugs, and
profile programs in detail. Valgrind can also be used to build new
tools.
</para>
&lfs81_checked;
<bridgehead renderas="sect3">Package Information</bridgehead>
<itemizedlist spacing="compact">
<listitem>
<para>
Download (HTTP): <ulink url="&valgrind-download-http;"/>
</para>
</listitem>
<listitem>
<para>
Download (FTP): <ulink url="&valgrind-download-ftp;"/>
</para>
</listitem>
<listitem>
<para>
Download MD5 sum: &valgrind-md5sum;
</para>
</listitem>
<listitem>
<para>
Download size: &valgrind-size;
</para>
</listitem>
<listitem>
<para>
Estimated disk space required: &valgrind-buildsize;
</para>
</listitem>
<listitem>
<para>
Estimated build time: &valgrind-time;
</para>
</listitem>
</itemizedlist>
<bridgehead renderas="sect3">Valgrind Dependencies</bridgehead>
<bridgehead renderas="sect4">Optional</bridgehead>
<para role="optional">
<xref linkend="bind"/> or <xref linkend="bind-utils"/> (for tests),
<xref linkend="boost"/>,
<xref linkend="gdb"/> (for tests),
<xref linkend="llvm"/> (with Clang), and
<xref linkend="which"/> (for tests)
</para>
<!-- See "maintainer note", below
<bridgehead renderas="sect4">Optional for regenerating the documentation</bridgehead>
<para role="optional">
<xref linkend="libxslt"/> and
<xref linkend="texlive"/> (or <xref linkend="tl-installer"/>)
</para>
-->
<para condition="html" role="usernotes">User Notes:
<ulink url="&blfs-wiki;/valgrind"/>
</para>
</sect2>
<sect2 role="installation">
<title>Installation of Valgrind</title>
<!-- Fix applied upstream, remove in valgrind 1.14-->
<para>
First, fix a bug, which has been exposed by glibc-2.26:
</para>
<screen><userinput>sed -i '1904s/4/5/' coregrind/m_syswrap/syswrap-linux.c</userinput></screen>
<para>
Install <application>Valgrind</application> by running the following
commands:
</para>
<screen><userinput>sed -i 's|/doc/valgrind||' docs/Makefile.in &amp;&amp;
./configure --prefix=/usr \
--datadir=/usr/share/doc/valgrind-&valgrind-version; &amp;&amp;
make</userinput></screen>
<note>
<para>
To run the tests for this package, valgrind requires a version of the
/lib/ld-2.26.so (or later) library with debugging symbols present.
Normally in LFS these debugging symbols are stripped at the end of
Chapter 6. To get this library, glibc must be rebuilt with the current
glibc version using the same compiler that was used to build LFS. The
ld.so can then be renamed to ld-2.26.so.dbg and copied to /lib.
Then a symlink needs to be changed:</para>
<screen role="nodump"><userinput>ln -sfv ld-2.26.so.dbg /lib/ld-linux-x86-64.so.2</userinput></screen>
<para>
Adjust the above instruction as needed for a 32-bit system or for a
different version of glibc.
</para>
<para>
In addition, other glibc libraries with debugging symbols present
may be needed for some tests.
</para>
</note>
<para>
To test the results, issue: <command>make regtest</command>. The tests
may hang forever if <xref linkend="gdb"/> is not installed. Some tests
are known to hang also, depending on the version of glibc. Problematic
tests can be disabled by changing the <userinput>prereq:</userinput> line
in the corresponding <filename>.vgtest</filename> file to
<userinput>prereq: false</userinput>. For example:
</para>
<!-- For valgrind-3.12.0, the pth_cond_destroy_busy test hangs forever because
of some change in glibc-2.25. Should be fixed in next versions of
valgrind.-->
<screen><userinput>sed -e 's@prereq:.*@prereq: false@' \
-i {helgrind,drd}/tests/pth_cond_destroy_busy.vgtest</userinput></screen>
<note>
<para>
The <application>OpenMP</application> tests are skipped if libgomp
has been compiled with <option>--enable-linux-futex</option> (the
default). If needed, just recompile the libgomp library from
the gcc build tree, passing <option>--disable-linux-futex</option>
to configure, storing the library to some place and changing the link
from <filename>/usr/lib/libgomp.so.1</filename> to point to the new
library.
</para>
</note>
<!-- Note to maintainer: there is a long thread in ticket #5882 explaining
why we do not provide instructions to rebuild the documentation.
(still broken with TeXLive 2016) -->
<para>
Now, as the <systemitem class="username">root</systemitem> user:
</para>
<screen role="root"><userinput>make install</userinput></screen>
</sect2>
<sect2 role="commands">
<title>Command Explanations</title>
<para>
<command>sed -i ... docs/Makefile.in </command>: This sed provides for
installing the documentation in a versioned directory.
</para>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Library</segtitle>
<segtitle>Installed Directories</segtitle>
<seglistitem>
<seg>
callgrind_annotate,
callgrind_control,
cg_annotate,
cg_diff,
cg_merge,
ms_print,
valgrind,
valgrind-di-server,
valgrind-listener, and
vgdb
</seg>
<seg>
libcoregrind-&lt;Arch&gt;-linux.a,
libreplacemalloc_toolpreload-&lt;Arch&gt;-linux.a,
libvex-&lt;Arch&gt;-linux.a,
libvexmultiarch-amd64-linux.a,
vgpreload_core-&lt;Arch&gt;-linux.so,
vgpreload_drd-&lt;Arch&gt;-linux.so,
vgpreload_exp-dhat-&lt;Arch&gt;-linux.so,
vgpreload_exp-sgcheck-&lt;Arch&gt;-linux.so,
vgpreload_helgrind-&lt;Arch&gt;-linux.so,
vgpreload_massif-&lt;Arch&gt;-linux.so, and
vgpreload_memcheck-&lt;Arch&gt;-linux.so, where
&lt;Arch&gt; is x86 or amd64
</seg>
<seg>
/usr/lib/valgrind,
/usr/include/valgrind, and
/usr/share/doc/valgrind-&valgrind-version;
</seg>
</seglistitem>
</segmentedlist>
<variablelist>
<bridgehead renderas="sect3">Short Descriptions</bridgehead>
<?dbfo list-presentation="list"?>
<?dbhtml list-presentation="table"?>
<varlistentry id="valgrind-prog">
<term><command>valgrind</command></term>
<listitem>
<para>
is a program for debugging and profiling Linux executables.
</para>
<indexterm zone="valgrind valgrind-prog">
<primary sortas="b-valgrind">valgrind</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="callgrind_annotate">
<term><command>callgrind_annotate</command></term>
<listitem>
<para>
takes an output file produced by the
<application>Valgrind</application> tool Callgrind and prints the
information in an easy-to-read form.
</para>
<indexterm zone="callgrind_annotate">
<primary sortas="b-callgrind_annotate">callgrind_annotate</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="callgrind_control">
<term><command>callgrind_control</command></term>
<listitem>
<para>
controls programs being run by the <application>Valgrind</application>
tool Callgrind.
</para>
<indexterm zone="valgrind callgrind_control">
<primary sortas="b-callgrind_control">callgrind_control</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="cg_annotate">
<term><command>cg_annotate</command></term>
<listitem>
<para>
is a post-processing tool for the <application>Valgrind</application>
tool Cachegrind.
</para>
<indexterm zone="valgrind cg_annotate">
<primary sortas="b-cg_annotate">cg_annotate</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="cg_diff">
<term><command>cg_diff</command></term>
<listitem>
<para>
compares two Cachegrind output files.
</para>
<indexterm zone="valgrind cg_diff">
<primary sortas="b-cg_diff">cg_diff</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="cg_merge">
<term><command>cg_merge</command></term>
<listitem>
<para>
merges multiple Cachegrind output files into one.
</para>
<indexterm zone="valgrind cg_merge">
<primary sortas="b-cg_merge">cg_merge</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="ms_print">
<term><command>ms_print</command></term>
<listitem>
<para>
takes an output file produced by the <application>Valgrind</application>
tool Massif and prints the information in an easy-to-read form.
</para>
<indexterm zone="valgrind ms_print">
<primary sortas="b-ms_print">ms_print</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="valgrind-di-server">
<term><command>valgrind-di-server</command></term>
<listitem>
<para>
is a server that reads debuginfo from objects stored on a
different machine.
</para>
<indexterm zone="valgrind valgrind-di-server">
<primary sortas="b-valgrind-di-server">valgrind-di-server</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="valgrind-listener">
<term><command>valgrind-listener</command></term>
<listitem>
<para>
listens on a socket for Valgrind commentary.
</para>
<indexterm zone="valgrind valgrind-listener">
<primary sortas="b-valgrind-listener">valgrind-listener</primary>
</indexterm>
</listitem>
</varlistentry>
<varlistentry id="vgdb">
<term><command>vgdb</command></term>
<listitem>
<para>
is an intermediary between Valgrind and GDB or a shell.
</para>
<indexterm zone="valgrind vgdb">
<primary sortas="b-vgdb">vgdb</primary>
</indexterm>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>