1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4<title>5.�README_DEVELOPERS</title> 5<link rel="stylesheet" href="vg_basic.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> 7<link rel="home" href="index.html" title="Valgrind Documentation"> 8<link rel="up" href="dist.html" title="Valgrind Distribution Documents"> 9<link rel="prev" href="dist.readme-missing.html" title="4.�README_MISSING_SYSCALL_OR_IOCTL"> 10<link rel="next" href="dist.readme-packagers.html" title="6.�README_PACKAGERS"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr> 14<td width="22px" align="center" valign="middle"><a accesskey="p" href="dist.readme-missing.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td> 15<td width="25px" align="center" valign="middle"><a accesskey="u" href="dist.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td> 16<td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td> 17<th align="center" valign="middle">Valgrind Distribution Documents</th> 18<td width="22px" align="center" valign="middle"><a accesskey="n" href="dist.readme-packagers.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td> 19</tr></table></div> 20<div class="chapter" title="5.�README_DEVELOPERS"> 21<div class="titlepage"><div><div><h2 class="title"> 22<a name="dist.readme-developers"></a>5.�README_DEVELOPERS</h2></div></div></div> 23<div class="literallayout"><p><br> 24������<br> 25Building�and�not�installing�it<br> 26~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 27To�run�Valgrind�without�having�to�install�it,�run�coregrind/valgrind<br> 28with�the�VALGRIND_LIB�environment�variable�set,�where�<dir>�is�the�root<br> 29of�the�source�tree�(and�must�be�an�absolute�path).��Eg:<br> 30<br> 31��VALGRIND_LIB=~/grind/head4/.in_place�~/grind/head4/coregrind/valgrind�<br> 32<br> 33This�allows�you�to�compile�and�run�with�"make"�instead�of�"make�install",<br> 34saving�you�time.<br> 35<br> 36Or,�you�can�use�the�'vg-in-place'�script�which�does�that�for�you.<br> 37<br> 38I�recommend�compiling�with�"make�--quiet"�to�further�reduce�the�amount�of<br> 39output�spewed�out�during�compilation,�letting�you�actually�see�any�errors,<br> 40warnings,�etc.<br> 41<br> 42<br> 43Running�the�regression�tests<br> 44~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 45To�build�and�run�all�the�regression�tests,�run�"make�[--quiet]�regtest".<br> 46<br> 47To�run�a�subset�of�the�regression�tests,�execute:<br> 48<br> 49��perl�tests/vg_regtest�<name><br> 50<br> 51where�<name>�is�a�directory�(all�tests�within�will�be�run)�or�a�single<br> 52.vgtest�test�file,�or�the�name�of�a�program�which�has�a�like-named�.vgtest<br> 53file.��Eg:<br> 54<br> 55��perl�tests/vg_regtest�memcheck<br> 56��perl�tests/vg_regtest�memcheck/tests/badfree.vgtest<br> 57��perl�tests/vg_regtest�memcheck/tests/badfree<br> 58<br> 59<br> 60Running�the�performance�tests<br> 61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 62To�build�and�run�all�the�performance�tests,�run�"make�[--quiet]�perf".<br> 63<br> 64To�run�a�subset�of�the�performance�suite,�execute:<br> 65<br> 66��perl�perf/vg_perf�<name><br> 67<br> 68where�<name>�is�a�directory�(all�tests�within�will�be�run)�or�a�single<br> 69.vgperf�test�file,�or�the�name�of�a�program�which�has�a�like-named�.vgperf<br> 70file.��Eg:<br> 71<br> 72��perl�perf/vg_perf�perf/<br> 73��perl�perf/vg_perf�perf/bz2.vgperf<br> 74��perl�perf/vg_perf�perf/bz2<br> 75<br> 76To�compare�multiple�versions�of�Valgrind,�use�the�--vg=�option�multiple<br> 77times.��For�example,�if�you�have�two�Valgrinds�next�to�each�other,�one�in<br> 78trunk1/�and�one�in�trunk2/,�from�within�either�trunk1/�or�trunk2/�do�this�to<br> 79compare�them�on�all�the�performance�tests:<br> 80<br> 81��perl�perf/vg_perf�--vg=../trunk1�--vg=../trunk2�perf/<br> 82<br> 83<br> 84Debugging�Valgrind�with�GDB<br> 85~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 86To�debug�the�valgrind�launcher�program�(<prefix>/bin/valgrind)�just<br> 87run�it�under�gdb�in�the�normal�way.<br> 88<br> 89Debugging�the�main�body�of�the�valgrind�code�(and/or�the�code�for<br> 90a�particular�tool)�requires�a�bit�more�trickery�but�can�be�achieved<br> 91without�too�much�problem�by�following�these�steps:<br> 92<br> 93(1)�Set�VALGRIND_LAUNCHER�to�point�to�the�valgrind�executable.��Eg:<br> 94<br> 95������export�VALGRIND_LAUNCHER=/usr/local/bin/valgrind<br> 96<br> 97����or�for�an�uninstalled�version�in�a�source�directory�$DIR:<br> 98<br> 99������export�VALGRIND_LAUNCHER=$DIR/coregrind/valgrind<br> 100<br> 101(2)�Run�gdb�on�the�tool�executable.��Eg:<br> 102<br> 103������gdb�/usr/local/lib/valgrind/ppc32-linux/lackey<br> 104<br> 105����or<br> 106<br> 107������gdb�$DIR/.in_place/x86-linux/memcheck<br> 108<br> 109(3)�Do�"handle�SIGSEGV�SIGILL�nostop�noprint"�in�GDB�to�prevent�GDB�from<br> 110����stopping�on�a�SIGSEGV�or�SIGILL:<br> 111<br> 112����(gdb)�handle�SIGILL�SIGSEGV�nostop�noprint<br> 113<br> 114(4)�Set�any�breakpoints�you�want�and�proceed�as�normal�for�gdb.�The<br> 115����macro�VG_(FUNC)�is�expanded�to�vgPlain_FUNC,�so�If�you�want�to�set<br> 116����a�breakpoint�VG_(do_exec),�you�could�do�like�this�in�GDB:<br> 117<br> 118����(gdb)�b�vgPlain_do_exec<br> 119<br> 120(5)�Run�the�tool�with�required�options:<br> 121<br> 122����(gdb)�run�pwd<br> 123<br> 124Steps�(1)--(3)�can�be�put�in�a�.gdbinit�file,�but�any�directory�names�must<br> 125be�fully�expanded�(ie.�not�an�environment�variable).<br> 126<br> 127A�different�and�possibly�easier�way�is�as�follows:<br> 128<br> 129(1)�Run�Valgrind�as�normal,�but�add�the�flag�--wait-for-gdb=yes.��This<br> 130����puts�the�tool�executable�into�a�wait�loop�soon�after�it�gains<br> 131����control.��This�delays�startup�for�a�few�seconds.<br> 132<br> 133(2)�In�a�different�shell,�do�"gdb�/proc/<pid>/exe�<pid>",�where<br> 134����<pid>�you�read�from�the�output�printed�by�(1).��This�attaches<br> 135����GDB�to�the�tool�executable,�which�should�be�in�the�abovementioned<br> 136����wait�loop.<br> 137<br> 138(3)�Do�"cont"�to�continue.��After�the�loop�finishes�spinning,�startup<br> 139����will�continue�as�normal.��Note�that�comment�(3)�above�re�passing<br> 140����signals�applies�here�too.<br> 141<br> 142<br> 143Self-hosting<br> 144~~~~~~~~~~~~<br> 145To�run�Valgrind�under�Valgrind:<br> 146<br> 147(1)�Check�out�2�trees,�"Inner"�and�"Outer".��Inner�runs�the�app<br> 148����directly.��Outer�runs�Inner.<br> 149<br> 150(2)�Configure�inner�with�--enable-inner�and�build/install�as<br> 151����usual.<br> 152<br> 153(3)�Configure�Outer�normally�and�build/install�as�usual.<br> 154<br> 155(4)�Choose�a�very�simple�program�(date)�and�try<br> 156<br> 157����outer/.../bin/valgrind�--sim-hints=enable-outer�--trace-children=yes��\<br> 158�������--tool=cachegrind�-v�inner/.../bin/valgrind�--tool=none�-v�prog<br> 159<br> 160If�you�omit�the�--trace-children=yes,�you'll�only�monitor�Inner's�launcher<br> 161program,�not�its�stage2.<br> 162<br> 163The�whole�thing�is�fragile,�confusing�and�slow,�but�it�does�work�well�enough<br> 164for�you�to�get�some�useful�performance�data.��Inner�has�most�of<br> 165its�output�(ie.�those�lines�beginning�with�"==<pid>==")�prefixed�with�a�'>',<br> 166which�helps�a�lot.<br> 167<br> 168At�the�time�of�writing�the�allocator�is�not�annotated�with�client�requests<br> 169so�Memcheck�is�not�as�useful�as�it�could�be.��It�also�has�not�been�tested<br> 170much,�so�don't�be�surprised�if�you�hit�problems.<br> 171<br> 172When�using�self-hosting�with�an�outer�Callgrind�tool,�use�'--pop-on-jump'<br> 173(on�the�outer).�Otherwise,�Callgrind�has�much�higher�memory�requirements.�<br> 174<br> 175<br> 176Printing�out�problematic�blocks<br> 177~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br> 178If�you�want�to�print�out�a�disassembly�of�a�particular�block�that<br> 179causes�a�crash,�do�the�following.<br> 180<br> 181Try�running�with�"--vex-guest-chase-thresh=0�--trace-flags=10000000<br> 182--trace-notbelow=999999".��This�should�print�one�line�for�each�block<br> 183translated,�and�that�includes�the�address.<br> 184<br> 185Then�re-run�with�999999�changed�to�the�highest�bb�number�shown.<br> 186This�will�print�the�one�line�per�block,�and�also�will�print�a<br> 187disassembly�of�the�block�in�which�the�fault�occurred.<br> 188<br> 189����</p></div> 190</div> 191<div> 192<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 193<tr> 194<td rowspan="2" width="40%" align="left"> 195<a accesskey="p" href="dist.readme-missing.html"><<�4.�README_MISSING_SYSCALL_OR_IOCTL</a>�</td> 196<td width="20%" align="center"><a accesskey="u" href="dist.html">Up</a></td> 197<td rowspan="2" width="40%" align="right">�<a accesskey="n" href="dist.readme-packagers.html">6.�README_PACKAGERS�>></a> 198</td> 199</tr> 200<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 201</table> 202</div> 203</body> 204</html> 205
