| |
| 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 an award-winning suite of tools for debugging and profiling |
| 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 speed up and reduce memory use of your |
| programs. |
| |
| The Valgrind distribution currently includes five production grade |
| tools: a memory error detector, a thread error detector, a cache |
| profiler, a call graph profiler and a heap profiler. Experimental |
| tools are also included. They are distinguished by the "exp-" prefix |
| on their names. |
| |
| To give you an idea of what Valgrind tools do, when a program is run |
| under the supervision of Memcheck, the memory error detector tool, all |
| reads and writes of memory are checked, and calls to malloc/new/free/delete |
| are intercepted. As a result, Memcheck can detect if your program: |
| |
| - Accesses memory it shouldn't (areas not yet allocated, areas that have |
| been freed, areas past the end of heap blocks, inaccessible areas of |
| the stack). |
| |
| - Uses uninitialised values in dangerous ways. |
| |
| - Leaks memory. |
| |
| - Does bad frees of heap blocks (double frees, mismatched frees). |
| |
| - Passes overlapping source and destination memory blocks to memcpy() and |
| related functions. |
| |
| 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. Nonetheless, it is available for |
| the following platforms: x86/Linux, AMD64/Linux and PPC32/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 the Subversion repository : |
| |
| 0. Check out the code from SVN, following the instructions at |
| http://www.valgrind.org/downloads/repository.html. |
| |
| 1. cd into the source directory. |
| |
| 2. Run ./autogen.sh to setup the environment (you need the standard |
| autoconf tools to do so). |
| |
| 3. Continue with the following instructions... |
| |
| To install from a tar.bz2 distribution: |
| |
| 4. 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. |
| |
| 5. Do "make". (Nb: this cannot be combined with the next step.) |
| |
| 6. Do "make install", possibly as root if the destination permissions |
| require that. |
| |
| 7. See if it works. Try "valgrind ls -l". Either this works, or it |
| bombs out with some complaint. In that case, please let us know |
| (see www.valgrind.org). |
| |
| 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. |
| |
| |
| The Valgrind Developers |