l4/pkg/valgrind/src/valgrind-3.6.0-svn/docs/xml/manual-intro.xml

   1 <?xml version="1.0"?> <!-- -*- sgml -*- -->
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   4 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
   5
   6 <chapter id="manual-intro" xreflabel="Introduction">
   7 <title>Introduction</title>
   8
   9 <sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
  10 <title>An Overview of Valgrind</title>
  11
  12 <para>Valgrind is an instrumentation framework for building dynamic analysis
  13 tools.  It comes with a set of tools each of which performs some kind of
  14 debugging, profiling, or similar task that helps you improve your programs.
  15 Valgrind's architecture is modular, so new tools can be created easily
  16 and without disturbing the existing structure.</para>
  17
  18 <para>A number of useful tools are supplied as standard.</para>
  19
  20 <orderedlist>
  21
  22   <listitem>
  23     <para><command>Memcheck</command> is a memory error detector.  It helps
  24     you make your programs, particularly those written in C and C++, more
  25     correct.</para>
  26   </listitem>
  27
  28   <listitem>
  29     <para><command>Cachegrind</command> is a cache and branch-prediction
  30     profiler.  It helps you make your programs run faster.</para>
  31   </listitem>
  32
  33   <listitem>
  34     <para><command>Callgrind</command> is a call-graph generating cache
  35     profiler.  It has some overlap with Cachegrind, but also gathers some
  36     information that Cachegrind does not.</para>
  37   </listitem>
  38
  39   <listitem>
  40     <para><command>Helgrind</command> is a thread error detector.
  41     It helps you make your multi-threaded programs more correct.
  42     </para>
  43   </listitem>
  44
  45   <listitem>
  46     <para><command>DRD</command> is also a thread error detector.  It is
  47     similar to Helgrind but uses different analysis techniques and so may
  48     find different problems.</para>
  49   </listitem>
  50
  51   <listitem>
  52     <para><command>Massif</command> is a heap profiler.  It helps you
  53     make your programs use less memory.</para>
  54   </listitem>
  55
  56   <listitem>
  57     <para><command>DHAT</command> is a different kind of heap
  58     profiler.  It helps you understand issues of block lifetimes,
  59     block utilisation, and layout inefficiencies.</para>
  60   </listitem>
  61
  62   <listitem>
  63     <para><command>Ptrcheck</command> is an experimental heap, stack and
  64     global array overrun detector.  Its functionality overlaps somewhat
  65     with Memcheck's, but it can find some problems that Memcheck would
  66     miss.</para>
  67   </listitem>
  68
  69   <listitem>
  70     <para><command>BBV</command> is an experimental SimPoint basic block
  71     vector generator.  It is useful to people doing computer architecture
  72     research and development.</para>
  73   </listitem>
  74
  75 </orderedlist>
  76
  77 <para>There are also a couple of minor tools that aren't useful to
  78 most users:  <command>Lackey</command> is an example tool that illustrates
  79 some instrumentation basics; and <command>Nulgrind</command> is the minimal
  80 Valgrind tool that does no analysis or instrumentation, and is only useful
  81 for testing purposes.</para>
  82
  83 <para>Valgrind is closely tied to details of the CPU and operating
  84 system, and to a lesser extent, the compiler and basic C libraries.
  85 Nonetheless, it supports a number of widely-used platforms, listed in full
  86 at <ulink url="&vg-url;">&vg-url;</ulink>.</para>
  87
  88 <para>Valgrind is built via the standard Unix
  89 <computeroutput>./configure</computeroutput>,
  90 <computeroutput>make</computeroutput>, <computeroutput>make
  91 install</computeroutput> process;  full details are given in the
  92 README file in the distribution.</para>
  93
  94 <para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
  95 version 2.  The <computeroutput>valgrind/*.h</computeroutput> headers
  96 that you may wish to include in your code (eg.
  97 <filename>valgrind.h</filename>, <filename>memcheck.h</filename>,
  98 <filename>helgrind.h</filename>, etc.) are
  99 distributed under a BSD-style license, so you may include them in your
 100 code without worrying about license conflicts.  Some of the PThreads
 101 test cases, <filename>pth_*.c</filename>, are taken from "Pthreads
 102 Programming" by Bradford Nichols, Dick Buttlar &amp; Jacqueline Proulx
 103 Farrell, ISBN 1-56592-115-1, published by O'Reilly &amp; Associates,
 104 Inc.</para>
 105
 106 <para>If you contribute code to Valgrind, please ensure your
 107 contributions are licensed as "GPLv2, or (at your option) any later
 108 version."  This is so as to allow the possibility of easily upgrading
 109 the license to GPLv3 in future.  If you want to modify code in the VEX
 110 subdirectory, please also see the file VEX/HACKING.README in the
 111 distribution.</para>
 112
 113
 114 </sect1>
 115
 116
 117 <sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
 118 <title>How to navigate this manual</title>
 119
 120 <para>This manual's structure reflects the structure of Valgrind itself.
 121 First, we describe the Valgrind core, how to use it, and the options
 122 it supports.  Then, each tool has its own chapter in this manual.  You
 123 only need to read the documentation for the core and for the tool(s) you
 124 actually use, although you may find it helpful to be at least a little
 125 bit familiar with what all tools do.  If you're new to all this, you probably
 126 want to run the Memcheck tool and you might find the <xref
 127 linkend="quick-start"/> useful.</para>
 128
 129 <para>Be aware that the core understands some command line options, and
 130 the tools have their own options which they know about.  This means
 131 there is no central place describing all the options that are
 132 accepted -- you have to read the options documentation both for
 133 <xref linkend="manual-core"/> and for the tool you want to use.</para>
 134
 135
 136 </sect1>
 137
 138 </chapter>