blob: 71ac479bcd7c8d6f2e9c3d4340a4d1eca6c163e9 [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
njna2488752005-07-26 22:33:26 +000024The Valgrind distribution currently includes five tools: two memory error
nethercote075a1022004-04-10 00:36:25 +000025detectors, a thread error detector, a cache profiler and a heap profiler.
nethercote5da1e172003-12-03 21:44:45 +000026
27To give you an idea of what Valgrind tools do, when a program is run
28under the supervision of the first memory error detector tool, all reads
29and writes of memory are checked, and calls to malloc/new/free/delete
30are intercepted. As a result, it can detect problems such as:
31
32 Use of uninitialised memory
33 Reading/writing memory after it has been free'd
34 Reading/writing off the end of malloc'd blocks
35 Reading/writing inappropriate areas on the stack
nethercoteed7e0732003-12-02 15:30:28 +000036 Memory leaks -- where pointers to malloc'd blocks are lost forever
37 Passing of uninitialised and/or unaddressible memory to system calls
nethercote5da1e172003-12-03 21:44:45 +000038 Mismatched use of malloc/new/new [] vs free/delete/delete []
39 Overlaps of arguments to strcpy() and related functions
nethercoteed7e0732003-12-02 15:30:28 +000040 Some abuses of the POSIX pthread API
sewardjde4a1d02002-03-22 01:27:54 +000041
nethercoteed7e0732003-12-02 15:30:28 +000042Problems like these can be difficult to find by other means, often
43lying undetected for long periods, then causing occasional,
nethercote5da1e172003-12-03 21:44:45 +000044difficult-to-diagnose crashes. When one of these errors occurs, you can
45attach GDB to your program, so you can poke around and see what's going
46on.
sewardjde4a1d02002-03-22 01:27:54 +000047
48Valgrind is closely tied to details of the CPU, operating system and
49to a less extent, compiler and basic C libraries. This makes it
njn0d733b82005-07-26 22:01:04 +000050difficult to make it portable. Nonetheless, it is available for
51the following platforms: x86/Linux, AMD64/Linux and PPC32/Linux.
sewardjde4a1d02002-03-22 01:27:54 +000052
53Valgrind is licensed under the GNU General Public License, version 2.
njn25e49d8e72002-09-23 09:36:25 +000054Read the file COPYING in the source distribution for details.
sewardjde4a1d02002-03-22 01:27:54 +000055
56
57Documentation
58~~~~~~~~~~~~~
59A comprehensive user guide is supplied. Point your browser at
nethercote5da1e172003-12-03 21:44:45 +000060$PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you
61specified with --prefix= when building.
sewardjde4a1d02002-03-22 01:27:54 +000062
63
nethercoteed7e0732003-12-02 15:30:28 +000064Building and installing it
65~~~~~~~~~~~~~~~~~~~~~~~~~~
njn0d733b82005-07-26 22:01:04 +000066To install from the Subversion repository :
nethercoteed7e0732003-12-02 15:30:28 +000067
njn0d733b82005-07-26 22:01:04 +000068 0. Check out the code from SVN, following the instructions at
69 http://valgrind.org/devel/cvs_svn.html.
nethercoteed7e0732003-12-02 15:30:28 +000070
71 1. cd into the source directory.
72
73 2. Run ./autogen.sh to setup the environment (you need the standard
74 autoconf tools to do so).
75
njn0d733b82005-07-26 22:01:04 +000076 3. Continue with the following instructions...
77
nethercote5da1e172003-12-03 21:44:45 +000078To install from a tar.bz2 distribution:
nethercoteed7e0732003-12-02 15:30:28 +000079
njn0d733b82005-07-26 22:01:04 +000080 4. Run ./configure, with some options if you wish. The standard
nethercoteed7e0732003-12-02 15:30:28 +000081 options are documented in the INSTALL file. The only interesting
82 one is the usual --prefix=/where/you/want/it/installed.
83
njn0d733b82005-07-26 22:01:04 +000084 5. Do "make".
nethercoteed7e0732003-12-02 15:30:28 +000085
njn0d733b82005-07-26 22:01:04 +000086 6. Do "make install", possibly as root if the destination permissions
nethercoteed7e0732003-12-02 15:30:28 +000087 require that.
88
njn0d733b82005-07-26 22:01:04 +000089 7. See if it works. Try "valgrind ls -l". Either this works, or it
90 bombs out with some complaint. In that case, please let us know
91 (see www.valgrind.org).
nethercoteed7e0732003-12-02 15:30:28 +000092
93Important! Do not move the valgrind installation into a place
94different from that specified by --prefix at build time. This will
95cause things to break in subtle ways, mostly when Valgrind handles
96fork/exec calls.
97
sewardjde4a1d02002-03-22 01:27:54 +000098
sewardjde4a1d02002-03-22 01:27:54 +000099Julian Seward (jseward@acm.org)
njn2bc10122005-05-08 02:10:27 +0000100Nick Nethercote (njn@valgrind.org)
nethercote5da1e172003-12-03 21:44:45 +0000101Jeremy Fitzhardinge (jeremy@goop.org)