|
From: Nicholas N. <nj...@ca...> - 2003-12-03 21:46:44
|
CVS commit by nethercote:
(Mostly) merged from HEAD:
Updated the README file. It had lots of out-of-date and incorrect information
in it, much of it from 1.0.X days. Did it in such a way that if it doesn't get
touched (and it undoubtedly won't) it won't really go out of date, eg. by
removing temporary details like version numbers, dates, details of specific
software incompatibilities. It's much better to be vague but correct, than
precise but incorrect; having incorrect info in a file as important as the
README is bad. Also removed the README_KDE3_FOLKS file because it's pretty
redundant now.
Did similar, but smaller changes to README_DEVELOPERS and README_PACKAGERS.
Also updated the valgrind.spec.in file to use the new, post-1.0.X description
in the README.
Also fixed a minor omission in Addrcheck's docs.
M +1 -1 Makefile.am 1.55.2.1
M +48 -27 README 1.11.2.2
M +15 -4 README_DEVELOPERS 1.1.2.2
M +0 -2 README_PACKAGERS 1.2.8.2
M +9 -14 valgrind.spec.in 1.8.2.2
M +2 -0 addrcheck/docs/ac_main.html 1.2.4.1
R README_KDE3_FOLKS 1.3.8.1
--- valgrind/Makefile.am #1.55:1.55.2.1
@@ -39,5 +39,5 @@
FAQ.txt \
PATCHES_APPLIED ACKNOWLEDGEMENTS \
- README_KDE3_FOLKS README_PACKAGERS \
+ README_PACKAGERS \
README_MISSING_SYSCALL_OR_IOCTL TODO \
valgrind.spec valgrind.spec.in
--- valgrind/README #1.11.2.1:1.11.2.2
@@ -1,8 +1,5 @@
-Release notes for Valgrind, version 2.0.0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-KDE3 developers: please read also README_KDE3_FOLKS for guidance
-about how to debug KDE3 applications with Valgrind.
-
+Release notes for Valgrind
+~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are building a binary package of Valgrind for distribution,
please read README_PACKAGERS. It contains some important information.
@@ -13,20 +10,31 @@
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 tool to help you find memory-management problems in your
-programs. When a program is run under Valgrind's supervision, all
-reads and writes of memory are checked, and calls to
-malloc/new/free/delete are intercepted. As a result, Valgrind 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
+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 four tools: two memory error
+detectors, a thread error detector, and a cache 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 []
+ 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
@@ -34,8 +42,12 @@
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 Valgrind detects such a problem, it can, if you like, attach GDB
-to your program, so you can poke around and see what's going on.
+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.
@@ -47,21 +59,32 @@
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.
+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:
- 1. Run ./configure, with some options if you wish. The standard
+ 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.
- 2. Do "make".
+ 4. Do "make".
- 3. Do "make install", possibly as root if the destination permissions
+ 5. Do "make install", possibly as root if the destination permissions
require that.
- 4. See if it works. Try "valgrind ls -l". Either this works,
+ 6. See if it works. Try "valgrind ls -l". Either this works,
or it bombs out complaining it can't find argc/argv/envp.
In that case, mail me a bug report.
@@ -76,4 +99,2 @@
Nick Nethercote (nj...@ca...)
Jeremy Fitzhardinge (je...@go...)
-
-5 November 2003
--- valgrind/README_DEVELOPERS #1.1.2.1:1.1.2.2
@@ -1,3 +1,18 @@
+Building and not installing it
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To run Valgrind without having to install it, run coregrind/valgrind (prefix
+with "sh" because it's not executable) with the --in-place=<dir> option, where
+<dir> is the root of the source tree (and must be an absolute path). Eg:
+
+ sh ~/grind/head4/coregrind/valgrind --in-place=/homes/njn25/grind/head4
+
+This allows you to compile and run with "make" instead of "make install",
+saving you time.
+
+I recommend compiling with "make --quiet" to further reduce the amount of
+output spewed out during compilation, letting you actually see any errors,
+warnings, etc.
+
Running the regression tests
@@ -16,7 +31,3 @@
perl tests/vg_regtest memcheck/tests/badfree.vgtest
perl tests/vg_regtest memcheck/tests/badfree
-
-
-Nick Nethercote (nj...@ca...)
-Last updated 5 November 2003
--- valgrind/README_PACKAGERS #1.2.8.1:1.2.8.2
@@ -1,5 +1,3 @@
-5 November 2003
-
Greetings, packaging person! This information is aimed at people
building binary distributions of Valgrind.
--- valgrind/valgrind.spec.in #1.8.2.1:1.8.2.2
@@ -12,18 +12,13 @@
%description
-Valgrind is a GPL'd tool to help you find memory-management problems
-in your programs. When a program is run under Valgrind's supervision,
-all reads and writes of memory are checked, and calls to
-malloc/new/free/delete are intercepted. As a result, Valgrind can
-detect problems such as:
+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.
-- 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 []
-- Some abuses of the POSIX Pthreads API
+The Valgrind distribution includes four tools: two memory error
+detectors, a thread error detector, and a cache profiler. Several other
+tools have been built with Valgrind.
%prep
--- valgrind/addrcheck/docs/ac_main.html #1.2:1.2.4.1
@@ -26,4 +26,6 @@
forever</li>
<li>Mismatched use of malloc/new/new [] vs free/delete/delete []</li>
+ <li>Overlapping <code>src</code> and <code>dst</code> pointers in
+ <code>memcpy()</code> and related functions</li>
<li>Some misuses of the POSIX pthreads API</li>
</ul>
|