sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 1 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 2 | Release notes for Valgrind |
| 3 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 4 | If you are building a binary package of Valgrind for distribution, |
| 5 | please read README_PACKAGERS. It contains some important information. |
sewardj | 365a851 | 2002-07-01 08:30:05 +0000 | [diff] [blame] | 6 | |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 7 | If you are developing Valgrind, please read README_DEVELOPERS. It contains |
| 8 | some useful information. |
| 9 | |
| 10 | For instructions on how to build/install, see the end of this file. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 11 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 12 | Valgrind works on most, reasonably recent Linux setups. If you have |
| 13 | problems, consult FAQ.txt to see if there are workarounds. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 14 | |
| 15 | Executive Summary |
| 16 | ~~~~~~~~~~~~~~~~~ |
njn | a248875 | 2005-07-26 22:33:26 +0000 | [diff] [blame] | 17 | Valgrind is an award-winning suite of tools for debugging and profiling |
| 18 | Linux programs. With the tools that come with Valgrind, you can |
| 19 | automatically detect many memory management and threading bugs, avoiding |
| 20 | hours of frustrating bug-hunting, making your programs more stable. You can |
| 21 | also perform detailed profiling, to speed up and reduce memory use of your |
| 22 | programs. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 23 | |
sewardj | bc39ad2 | 2007-12-09 02:24:02 +0000 | [diff] [blame] | 24 | The Valgrind distribution currently includes five production grade |
| 25 | tools: a memory error detector, a thread error detector, a cache |
| 26 | profiler, a call graph profiler and a heap profiler. Experimental |
| 27 | tools are also included. They are distinguished by the "exp-" prefix |
| 28 | on their names. |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 29 | |
| 30 | To give you an idea of what Valgrind tools do, when a program is run |
njn | 567c014 | 2006-03-31 12:24:37 +0000 | [diff] [blame] | 31 | under the supervision of Memcheck, the memory error detector tool, all |
| 32 | reads and writes of memory are checked, and calls to malloc/new/free/delete |
| 33 | are intercepted. As a result, Memcheck can detect if your program: |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 34 | |
njn | 567c014 | 2006-03-31 12:24:37 +0000 | [diff] [blame] | 35 | - 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. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 47 | |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 48 | Problems like these can be difficult to find by other means, often |
| 49 | lying undetected for long periods, then causing occasional, |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 50 | difficult-to-diagnose crashes. When one of these errors occurs, you can |
| 51 | attach GDB to your program, so you can poke around and see what's going |
| 52 | on. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 53 | |
| 54 | Valgrind is closely tied to details of the CPU, operating system and |
| 55 | to a less extent, compiler and basic C libraries. This makes it |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 56 | difficult to make it portable. Nonetheless, it is available for |
| 57 | the following platforms: x86/Linux, AMD64/Linux and PPC32/Linux. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 58 | |
| 59 | Valgrind is licensed under the GNU General Public License, version 2. |
njn25 | e49d8e7 | 2002-09-23 09:36:25 +0000 | [diff] [blame] | 60 | Read the file COPYING in the source distribution for details. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 61 | |
| 62 | |
| 63 | Documentation |
| 64 | ~~~~~~~~~~~~~ |
| 65 | A comprehensive user guide is supplied. Point your browser at |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 66 | $PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you |
| 67 | specified with --prefix= when building. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 68 | |
| 69 | |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 70 | Building and installing it |
| 71 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 72 | To install from the Subversion repository : |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 73 | |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 74 | 0. Check out the code from SVN, following the instructions at |
njn | 1b70e82 | 2005-11-08 19:38:58 +0000 | [diff] [blame] | 75 | http://www.valgrind.org/downloads/repository.html. |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 76 | |
| 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 | |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 82 | 3. Continue with the following instructions... |
| 83 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 84 | To install from a tar.bz2 distribution: |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 85 | |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 86 | 4. Run ./configure, with some options if you wish. The standard |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 87 | options are documented in the INSTALL file. The only interesting |
| 88 | one is the usual --prefix=/where/you/want/it/installed. |
| 89 | |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 90 | 5. Do "make". |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 91 | |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 92 | 6. Do "make install", possibly as root if the destination permissions |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 93 | require that. |
| 94 | |
njn | 0d733b8 | 2005-07-26 22:01:04 +0000 | [diff] [blame] | 95 | 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). |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 98 | |
| 99 | Important! Do not move the valgrind installation into a place |
| 100 | different from that specified by --prefix at build time. This will |
| 101 | cause things to break in subtle ways, mostly when Valgrind handles |
| 102 | fork/exec calls. |
| 103 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 104 | |
njn | 1b70e82 | 2005-11-08 19:38:58 +0000 | [diff] [blame] | 105 | The Valgrind Developers |