| |
| Release notes for Valgrind |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| If you are building a binary package of Valgrind for distribution, |
| please read README_PACKAGERS. It contains some important information. |
| |
| If you are developing Valgrind, please read README_DEVELOPERS. It contains |
| some useful information. |
| |
| For instructions on how to build/install, see the end of this file. |
| |
| Valgrind works on most, reasonably recent Linux setups. If you have |
| problems, consult FAQ.txt to see if there are workarounds. |
| |
| Executive Summary |
| ~~~~~~~~~~~~~~~~~ |
| Valgrind is a GPL'd system for debugging and profiling x86-Linux programs. |
| With the tools that come with Valgrind, you can automatically detect |
| many memory management and threading bugs, avoiding hours of frustrating |
| bug-hunting, making your programs more stable. You can also perform |
| detailed profiling to help speed up your programs. |
| |
| The Valgrind distribution includes five tools: two memory error |
| detectors, a thread error detector, a cache profiler and a heap profiler. |
| Several other tools have been built with Valgrind. |
| |
| To give you an idea of what Valgrind tools do, when a program is run |
| under the supervision of the first memory error detector tool, all reads |
| and writes of memory are checked, and calls to malloc/new/free/delete |
| are intercepted. As a result, it can detect problems such as: |
| |
| Use of uninitialised memory |
| Reading/writing memory after it has been free'd |
| Reading/writing off the end of malloc'd blocks |
| Reading/writing inappropriate areas on the stack |
| Memory leaks -- where pointers to malloc'd blocks are lost forever |
| Passing of uninitialised and/or unaddressible memory to system calls |
| Mismatched use of malloc/new/new [] vs free/delete/delete [] |
| Overlaps of arguments to strcpy() and related functions |
| Some abuses of the POSIX pthread API |
| |
| Problems like these can be difficult to find by other means, often |
| lying undetected for long periods, then causing occasional, |
| difficult-to-diagnose crashes. When one of these errors occurs, you can |
| attach GDB to your program, so you can poke around and see what's going |
| on. |
| |
| Valgrind is closely tied to details of the CPU, operating system and |
| to a less extent, compiler and basic C libraries. This makes it |
| difficult to make it portable, so I have chosen at the outset to |
| concentrate on what I believe to be a widely used platform: x86/Linux. |
| |
| Valgrind is licensed under the GNU General Public License, version 2. |
| Read the file COPYING in the source distribution for details. |
| |
| |
| Documentation |
| ~~~~~~~~~~~~~ |
| A comprehensive user guide is supplied. Point your browser at |
| $PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you |
| specified with --prefix= when building. |
| |
| |
| Building and installing it |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| To install from CVS : |
| |
| 0. Check out the code from CVS, following the instructions at |
| http://developer.kde.org/source/anoncvs.html. The 'modulename' is |
| "valgrind". |
| |
| 1. cd into the source directory. |
| |
| 2. Run ./autogen.sh to setup the environment (you need the standard |
| autoconf tools to do so). |
| |
| To install from a tar.bz2 distribution: |
| |
| 3. Run ./configure, with some options if you wish. The standard |
| options are documented in the INSTALL file. The only interesting |
| one is the usual --prefix=/where/you/want/it/installed. |
| |
| 4. Do "make". |
| |
| 5. Do "make install", possibly as root if the destination permissions |
| require that. |
| |
| 6. See if it works. Try "valgrind --tool-memcheck ls -l". Either |
| this works, or it bombs out with some complaint. In that case, |
| please let us know (see valgrind.kde.org/bugs.html). |
| |
| Important! Do not move the valgrind installation into a place |
| different from that specified by --prefix at build time. This will |
| cause things to break in subtle ways, mostly when Valgrind handles |
| fork/exec calls. |
| |
| |
| Julian Seward (jseward@acm.org) |
| Nick Nethercote (njn25@cam.ac.uk) |
| Jeremy Fitzhardinge (jeremy@goop.org) |