ftmemsim-valgrind/docs/xml/manual-intro.xml

<?xml version="1.0"?> <!-- -*- sgml -*- -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>

<chapter id="manual-intro" xreflabel="Introduction">
<title>Introduction</title>

<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
<title>An Overview of Valgrind</title>

<para>Valgrind is an instrumentation framework for building dynamic analysis
tools.  It comes with a set of tools each of which performs some kind of
debugging, profiling, or similar task that helps you improve your programs.
Valgrind's architecture is modular, so new tools can be created easily
and without disturbing the existing structure.</para>

<para>A number of useful tools are supplied as standard.</para>

<orderedlist>

  <listitem>
    <para><command>Memcheck</command> is a memory error detector.  It helps
    you make your programs, particularly those written in C and C++, more
    correct.</para>
  </listitem>
 
  <listitem>
    <para><command>Cachegrind</command> is a cache and branch-prediction
    profiler.  It can help you make your programs run faster.</para>
  </listitem>

  <listitem>
    <para><command>Callgrind</command> is a call-graph generating cache
    profiler.  It has some overlap with Cachegrind, but also gathers some
    information that Cachegrind does not.</para>
  </listitem>

  <listitem>
    <para><command>Helgrind</command> is a thread error detector.
    It can help you make your multi-threaded programs more correct.
    </para>
  </listitem>

  <listitem>
    <para><command>DRD</command> is also a thread error detector.  It is
    similar to Helgrind but uses different analysis techniques and so may
    find different problems.</para>
  </listitem>

  <listitem>
    <para><command>Massif</command> is a heap profiler.  It can help you
    make your programs use less memory.</para>
  </listitem>

  <listitem>
    <para><command>Ptrcheck</command> is an experimental heap, stack and
    global array overrun detector.  Its functionality overlaps somewhat
    with Memcheck's, but it can find some problems that Memcheck would
    miss.</para>
  </listitem>

  <listitem>
    <para><command>BBV</command> is an experimental SimPoint basic block
    vector generator.  It is useful to people doing computer architecture
    research and development.</para>
  </listitem>

</orderedlist>
  
<para>There are also a couple of minor tools that aren't useful to
most users:  <command>Lackey</command> is an example tool that illustrates
some instrumentation basics; and <command>Nulgrind</command> is the minimal
Valgrind tool that does no analysis or instrumentation, and is only useful
for testing purposes.</para>

<para>Valgrind is closely tied to details of the CPU and operating
system, and to a lesser extent, the compiler and basic C libraries.
Nonetheless, it supports a number of widely-used platforms, listed in full
at <ulink url="&vg-url;">&vg-url;</ulink>.</para>

<para>Valgrind is built via the standard Unix
<computeroutput>./configure</computeroutput>,
<computeroutput>make</computeroutput>, <computeroutput>make
install</computeroutput> process;  full details are given in the
README file in the distribution.</para>

<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
version 2.  The <computeroutput>valgrind/*.h</computeroutput> headers
that you may wish to include in your code (eg.
<filename>valgrind.h</filename>, <filename>memcheck.h</filename>,
<filename>helgrind.h</filename>, etc.) are
distributed under a BSD-style license, so you may include them in your
code without worrying about license conflicts.  Some of the PThreads
test cases, <filename>pth_*.c</filename>, are taken from "Pthreads
Programming" by Bradford Nichols, Dick Buttlar &amp; Jacqueline Proulx
Farrell, ISBN 1-56592-115-1, published by O'Reilly &amp; Associates,
Inc.</para>

<para>If you contribute code to Valgrind, please ensure your
contributions are licensed as "GPLv2, or (at your option) any later
version."  This is so as to allow the possibility of easily upgrading
the license to GPLv3 in future.  If you want to modify code in the VEX
subdirectory, please also see the file VEX/HACKING.README in the
distribution.</para>


</sect1>


<sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
<title>How to navigate this manual</title>

<para>This manual's structure reflects the structure of Valgrind itself.
First, we describe the Valgrind core, how to use it, and the flags
it supports.  Then, each tool has its own chapter in this manual.  You
only need to read the documentation for the core and for the tool(s) you
actually use, although you may find it helpful to be at least a little
bit familiar with what all tools do.  If you're new to all this, you probably
want to run the Memcheck tool.  The final chapter explains how to write a
new tool.</para>

<para>Be aware that the core understands some command line flags, and
the tools have their own flags which they know about.  This means
there is no central place describing all the flags that are
accepted -- you have to read the flags documentation both for
<xref linkend="manual-core"/> and for the tool you want to use.</para>

<para>The manual is quite big and complex.  If you want to start using
Valgrind more quickly, read <xref linkend="quick-start"/>.</para>

</sect1>

</chapter>