blob: 3a75cd7eb1592d3ba12f306e2231cb8cb7cedde8 [file] [log] [blame]
sewardjde4a1d02002-03-22 01:27:54 +00001
nethercote5da1e172003-12-03 21:44:45 +00002Release notes for Valgrind
3~~~~~~~~~~~~~~~~~~~~~~~~~~
nethercoteed7e0732003-12-02 15:30:28 +00004If you are building a binary package of Valgrind for distribution,
5please read README_PACKAGERS. It contains some important information.
sewardj365a8512002-07-01 08:30:05 +00006
nethercoteed7e0732003-12-02 15:30:28 +00007If you are developing Valgrind, please read README_DEVELOPERS. It contains
8some useful information.
9
10For instructions on how to build/install, see the end of this file.
sewardjde4a1d02002-03-22 01:27:54 +000011
nethercote5da1e172003-12-03 21:44:45 +000012Valgrind works on most, reasonably recent Linux setups. If you have
13problems, consult FAQ.txt to see if there are workarounds.
sewardjde4a1d02002-03-22 01:27:54 +000014
15Executive Summary
16~~~~~~~~~~~~~~~~~
njna2488752005-07-26 22:33:26 +000017Valgrind is an award-winning suite of tools for debugging and profiling
18Linux programs. With the tools that come with Valgrind, you can
19automatically detect many memory management and threading bugs, avoiding
20hours of frustrating bug-hunting, making your programs more stable. You can
21also perform detailed profiling, to speed up and reduce memory use of your
22programs.
sewardjde4a1d02002-03-22 01:27:54 +000023
sewardjbc39ad22007-12-09 02:24:02 +000024The Valgrind distribution currently includes five production grade
25tools: a memory error detector, a thread error detector, a cache
26profiler, a call graph profiler and a heap profiler. Experimental
27tools are also included. They are distinguished by the "exp-" prefix
28on their names.
nethercote5da1e172003-12-03 21:44:45 +000029
30To give you an idea of what Valgrind tools do, when a program is run
njn567c0142006-03-31 12:24:37 +000031under the supervision of Memcheck, the memory error detector tool, all
32reads and writes of memory are checked, and calls to malloc/new/free/delete
33are intercepted. As a result, Memcheck can detect if your program:
nethercote5da1e172003-12-03 21:44:45 +000034
njn567c0142006-03-31 12:24:37 +000035 - Accesses memory it shouldn't (areas not yet allocated, areas that have
36 been freed, areas past the end of heap blocks, inaccessible areas of
37 the stack).
38
39 - Uses uninitialised values in dangerous ways.
40
41 - Leaks memory.
42
43 - Does bad frees of heap blocks (double frees, mismatched frees).
44
45 - Passes overlapping source and destination memory blocks to memcpy() and
46 related functions.
sewardjde4a1d02002-03-22 01:27:54 +000047
nethercoteed7e0732003-12-02 15:30:28 +000048Problems like these can be difficult to find by other means, often
49lying undetected for long periods, then causing occasional,
nethercote5da1e172003-12-03 21:44:45 +000050difficult-to-diagnose crashes. When one of these errors occurs, you can
51attach GDB to your program, so you can poke around and see what's going
52on.
sewardjde4a1d02002-03-22 01:27:54 +000053
54Valgrind is closely tied to details of the CPU, operating system and
55to a less extent, compiler and basic C libraries. This makes it
njn0d733b82005-07-26 22:01:04 +000056difficult to make it portable. Nonetheless, it is available for
57the following platforms: x86/Linux, AMD64/Linux and PPC32/Linux.
sewardjde4a1d02002-03-22 01:27:54 +000058
59Valgrind is licensed under the GNU General Public License, version 2.
njn25e49d8e72002-09-23 09:36:25 +000060Read the file COPYING in the source distribution for details.
sewardjde4a1d02002-03-22 01:27:54 +000061
62
63Documentation
64~~~~~~~~~~~~~
65A comprehensive user guide is supplied. Point your browser at
nethercote5da1e172003-12-03 21:44:45 +000066$PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
67specified with --prefix= when building.
sewardjde4a1d02002-03-22 01:27:54 +000068
69
nethercoteed7e0732003-12-02 15:30:28 +000070Building and installing it
71~~~~~~~~~~~~~~~~~~~~~~~~~~
njn0d733b82005-07-26 22:01:04 +000072To install from the Subversion repository :
nethercoteed7e0732003-12-02 15:30:28 +000073
njn0d733b82005-07-26 22:01:04 +000074 0. Check out the code from SVN, following the instructions at
njn1b70e822005-11-08 19:38:58 +000075 http://www.valgrind.org/downloads/repository.html.
nethercoteed7e0732003-12-02 15:30:28 +000076
77 1. cd into the source directory.
78
79 2. Run ./autogen.sh to setup the environment (you need the standard
80 autoconf tools to do so).
81
njn0d733b82005-07-26 22:01:04 +000082 3. Continue with the following instructions...
83
nethercote5da1e172003-12-03 21:44:45 +000084To install from a tar.bz2 distribution:
nethercoteed7e0732003-12-02 15:30:28 +000085
njn0d733b82005-07-26 22:01:04 +000086 4. Run ./configure, with some options if you wish. The standard
nethercoteed7e0732003-12-02 15:30:28 +000087 options are documented in the INSTALL file. The only interesting
88 one is the usual --prefix=/where/you/want/it/installed.
89
njn0d733b82005-07-26 22:01:04 +000090 5. Do "make".
nethercoteed7e0732003-12-02 15:30:28 +000091
njn0d733b82005-07-26 22:01:04 +000092 6. Do "make install", possibly as root if the destination permissions
nethercoteed7e0732003-12-02 15:30:28 +000093 require that.
94
njn0d733b82005-07-26 22:01:04 +000095 7. See if it works. Try "valgrind ls -l". Either this works, or it
96 bombs out with some complaint. In that case, please let us know
97 (see www.valgrind.org).
nethercoteed7e0732003-12-02 15:30:28 +000098
99Important! Do not move the valgrind installation into a place
100different from that specified by --prefix at build time. This will
101cause things to break in subtle ways, mostly when Valgrind handles
102fork/exec calls.
103
sewardjde4a1d02002-03-22 01:27:54 +0000104
njn1b70e822005-11-08 19:38:58 +0000105The Valgrind Developers