1 <html> 2 <head> 3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4 <title>2.Writing a New Valgrind Tool</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="tech-docs.html" title="Valgrind Technical Documentation"> 9 <link rel="prev" href="design-impl.html" title="1.The Design and Implementation of Valgrind"> 10 <link rel="next" href="cl-format.html" title="3.Callgrind Format Specification"> 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="design-impl.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="tech-docs.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 Technical Documentation</th> 18 <td width="22px" align="center" valign="middle"><a accesskey="n" href="cl-format.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="2.Writing a New Valgrind Tool"> 21 <div class="titlepage"><div><div><h2 class="title"> 22 <a name="manual-writing-tools"></a>2.Writing a New Valgrind Tool</h2></div></div></div> 23 <div class="toc"> 24 <p><b>Table of Contents</b></p> 25 <dl> 26 <dt><span class="sect1"><a href="manual-writing-tools.html#manual-writing-tools.intro">2.1. Introduction</a></span></dt> 27 <dt><span class="sect1"><a href="manual-writing-tools.html#manual-writing-tools.writingatool">2.2. Basics</a></span></dt> 28 <dd><dl> 29 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.howtoolswork">2.2.1. How tools work</a></span></dt> 30 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.gettingcode">2.2.2. Getting the code</a></span></dt> 31 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.gettingstarted">2.2.3. Getting started</a></span></dt> 32 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.writingcode">2.2.4. Writing the code</a></span></dt> 33 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.init">2.2.5. Initialisation</a></span></dt> 34 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.instr">2.2.6. Instrumentation</a></span></dt> 35 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.fini">2.2.7. Finalisation</a></span></dt> 36 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.otherinfo">2.2.8. Other Important Information</a></span></dt> 37 </dl></dd> 38 <dt><span class="sect1"><a href="manual-writing-tools.html#manual-writing-tools.advtopics">2.3. Advanced Topics</a></span></dt> 39 <dd><dl> 40 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.advice">2.3.1. Debugging Tips</a></span></dt> 41 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.suppressions">2.3.2. Suppressions</a></span></dt> 42 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.docs">2.3.3. Documentation</a></span></dt> 43 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.regtests">2.3.4. Regression Tests</a></span></dt> 44 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.profiling">2.3.5. Profiling</a></span></dt> 45 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.mkhackery">2.3.6. Other Makefile Hackery</a></span></dt> 46 <dt><span class="sect2"><a href="manual-writing-tools.html#manual-writing-tools.ifacever">2.3.7. The Core/tool Interface</a></span></dt> 47 </dl></dd> 48 <dt><span class="sect1"><a href="manual-writing-tools.html#manual-writing-tools.finalwords">2.4. Final Words</a></span></dt> 49 </dl> 50 </div> 51 52 So you want to write a Valgrind tool? Here are some instructions that may 53 help. 54 55 <div class="sect1" title="2.1.Introduction"> 56 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 57 <a name="manual-writing-tools.intro"></a>2.1.Introduction</h2></div></div></div> 58 <p>The key idea behind Valgrind's architecture is the division 59 between its <span class="emphasis"><em>core</em></span> and <span class="emphasis"><em>tools</em></span>.</p> 60 <p>The core provides the common low-level infrastructure to 61 support program instrumentation, including the JIT 62 compiler, low-level memory manager, signal handling and a 63 thread scheduler. It also provides certain services that 64 are useful to some but not all tools, such as support for error 65 recording, and support for replacing heap allocation functions such as 66 <code class="function">malloc</code>.</p> 67 <p>But the core leaves certain operations undefined, which 68 must be filled by tools. Most notably, tools define how program 69 code should be instrumented. They can also call certain 70 functions to indicate to the core that they would like to use 71 certain services, or be notified when certain interesting events 72 occur. But the core takes care of all the hard work.</p> 73 </div> 74 <div class="sect1" title="2.2.Basics"> 75 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 76 <a name="manual-writing-tools.writingatool"></a>2.2.Basics</h2></div></div></div> 77 <div class="sect2" title="2.2.1.How tools work"> 78 <div class="titlepage"><div><div><h3 class="title"> 79 <a name="manual-writing-tools.howtoolswork"></a>2.2.1.How tools work</h3></div></div></div> 80 <p>Tools must define various functions for instrumenting programs 81 that are called by Valgrind's core. They are then linked against 82 Valgrind's core to define a complete Valgrind tool which will be used 83 when the <code class="option">--tool</code> option is used to select it.</p> 84 </div> 85 <div class="sect2" title="2.2.2.Getting the code"> 86 <div class="titlepage"><div><div><h3 class="title"> 87 <a name="manual-writing-tools.gettingcode"></a>2.2.2.Getting the code</h3></div></div></div> 88 <p>To write your own tool, you'll need the Valgrind source code. You'll 89 need a check-out of the Subversion repository for the automake/autoconf 90 build instructions to work. See the information about how to do check-out 91 from the repository at <a class="ulink" href="http://www.valgrind.org/downloads/repository.html" target="_top">the Valgrind 92 website</a>.</p> 93 </div> 94 <div class="sect2" title="2.2.3.Getting started"> 95 <div class="titlepage"><div><div><h3 class="title"> 96 <a name="manual-writing-tools.gettingstarted"></a>2.2.3.Getting started</h3></div></div></div> 97 <p>Valgrind uses GNU <code class="computeroutput">automake</code> and 98 <code class="computeroutput">autoconf</code> for the creation of Makefiles 99 and configuration. But don't worry, these instructions should be enough 100 to get you started even if you know nothing about those tools.</p> 101 <p>In what follows, all filenames are relative to Valgrind's 102 top-level directory <code class="computeroutput">valgrind/</code>.</p> 103 <div class="orderedlist"><ol class="orderedlist" type="1"> 104 <li class="listitem"><p>Choose a name for the tool, and a two-letter abbreviation that can 105 be used as a short prefix. We'll use 106 <code class="computeroutput">foobar</code> and 107 <code class="computeroutput">fb</code> as an example.</p></li> 108 <li class="listitem"><p>Make three new directories <code class="filename">foobar/</code>, 109 <code class="filename">foobar/docs/</code> and 110 <code class="filename">foobar/tests/</code>. 111 </p></li> 112 <li class="listitem"><p>Create an empty file <code class="filename">foobar/tests/Makefile.am</code>. 113 </p></li> 114 <li class="listitem"><p>Copy <code class="filename">none/Makefile.am</code> into 115 <code class="filename">foobar/</code>. Edit it by replacing all 116 occurrences of the strings 117 <code class="computeroutput">"none"</code>, 118 <code class="computeroutput">"nl_"</code> and 119 <code class="computeroutput">"nl-"</code> with 120 <code class="computeroutput">"foobar"</code>, 121 <code class="computeroutput">"fb_"</code> and 122 <code class="computeroutput">"fb-"</code> respectively.</p></li> 123 <li class="listitem"><p>Copy <code class="filename">none/nl_main.c</code> into 124 <code class="computeroutput">foobar/</code>, renaming it as 125 <code class="filename">fb_main.c</code>. Edit it by changing the 126 <code class="computeroutput">details</code> lines in 127 <code class="function">nl_pre_clo_init</code> to something appropriate for the 128 tool. These fields are used in the startup message, except for 129 <code class="computeroutput">bug_reports_to</code> which is used if a 130 tool assertion fails. Also, replace the string 131 <code class="computeroutput">"nl_"</code> throughout with 132 <code class="computeroutput">"fb_"</code> again.</p></li> 133 <li class="listitem"><p>Edit <code class="filename">Makefile.am</code>, adding the new directory 134 <code class="filename">foobar</code> to the 135 <code class="computeroutput">TOOLS</code> or 136 <code class="computeroutput">EXP_TOOLS</code> variables.</p></li> 137 <li class="listitem"><p>Edit <code class="filename">configure.in</code>, adding 138 <code class="filename">foobar/Makefile</code> and 139 <code class="filename">foobar/tests/Makefile</code> to the 140 <code class="computeroutput">AC_OUTPUT</code> list.</p></li> 141 <li class="listitem"> 142 <p>Run:</p> 143 <pre class="programlisting"> 144 autogen.sh 145 ./configure --prefix=`pwd`/inst 146 make 147 make install</pre> 148 <p>It should automake, configure and compile without errors, 149 putting copies of the tool in 150 <code class="filename">foobar/</code> and 151 <code class="filename">inst/lib/valgrind/</code>.</p> 152 </li> 153 <li class="listitem"> 154 <p>You can test it with a command like:</p> 155 <pre class="programlisting"> 156 inst/bin/valgrind --tool=foobar date</pre> 157 <p>(almost any program should work; 158 <code class="computeroutput">date</code> is just an example). 159 The output should be something like this:</p> 160 <pre class="programlisting"> 161 ==738== foobar-0.0.1, a foobarring tool. 162 ==738== Copyright (C) 2002-2009, and GNU GPL'd, by J. Programmer. 163 ==738== Using Valgrind-3.5.0.SVN and LibVEX; rerun with -h for copyright info 164 ==738== Command: date 165 ==738== 166 Tue Nov 27 12:40:49 EST 2007 167 ==738==</pre> 168 <p>The tool does nothing except run the program uninstrumented.</p> 169 </li> 170 </ol></div> 171 <p>These steps don't have to be followed exactly -- you can choose 172 different names for your source files, and use a different 173 <code class="option">--prefix</code> for 174 <code class="computeroutput">./configure</code>.</p> 175 <p>Now that we've setup, built and tested the simplest possible tool, 176 onto the interesting stuff...</p> 177 </div> 178 <div class="sect2" title="2.2.4.Writing the code"> 179 <div class="titlepage"><div><div><h3 class="title"> 180 <a name="manual-writing-tools.writingcode"></a>2.2.4.Writing the code</h3></div></div></div> 181 <p>A tool must define at least these four functions:</p> 182 <pre class="programlisting"> 183 pre_clo_init() 184 post_clo_init() 185 instrument() 186 fini()</pre> 187 <p>The names can be different to the above, but these are the usual 188 names. The first one is registered using the macro 189 <code class="computeroutput">VG_DETERMINE_INTERFACE_VERSION</code>. 190 The last three are registered using the 191 <code class="computeroutput">VG_(basic_tool_funcs)</code> function.</p> 192 <p>In addition, if a tool wants to use some of the optional services 193 provided by the core, it may have to define other functions and tell the 194 core about them.</p> 195 </div> 196 <div class="sect2" title="2.2.5.Initialisation"> 197 <div class="titlepage"><div><div><h3 class="title"> 198 <a name="manual-writing-tools.init"></a>2.2.5.Initialisation</h3></div></div></div> 199 <p>Most of the initialisation should be done in 200 <code class="function">pre_clo_init</code>. Only use 201 <code class="function">post_clo_init</code> if a tool provides command line 202 options and must do some initialisation after option processing takes 203 place (<code class="computeroutput">"clo"</code> stands for "command line 204 options").</p> 205 <p>First of all, various "details" need to be set for a tool, using 206 the functions <code class="function">VG_(details_*)</code>. Some are all 207 compulsory, some aren't. Some are used when constructing the startup 208 message, <code class="computeroutput">detail_bug_reports_to</code> is used 209 if <code class="computeroutput">VG_(tool_panic)</code> is ever called, or 210 a tool assertion fails. Others have other uses.</p> 211 <p>Second, various "needs" can be set for a tool, using the functions 212 <code class="function">VG_(needs_*)</code>. They are mostly booleans, and can 213 be left untouched (they default to <code class="varname">False</code>). They 214 determine whether a tool can do various things such as: record, report 215 and suppress errors; process command line options; wrap system calls; 216 record extra information about heap blocks; etc.</p> 217 <p>For example, if a tool wants the core's help in recording and 218 reporting errors, it must call 219 <code class="function">VG_(needs_tool_errors)</code> and provide definitions of 220 eight functions for comparing errors, printing out errors, reading 221 suppressions from a suppressions file, etc. While writing these 222 functions requires some work, it's much less than doing error handling 223 from scratch because the core is doing most of the work. 224 </p> 225 <p>Third, the tool can indicate which events in core it wants to be 226 notified about, using the functions <code class="function">VG_(track_*)</code>. 227 These include things such as heap blocks being allocated, the stack 228 pointer changing, a mutex being locked, etc. If a tool wants to know 229 about this, it should provide a pointer to a function, which will be 230 called when that event happens.</p> 231 <p>For example, if the tool want to be notified when a new heap block 232 is allocated, it should call 233 <code class="function">VG_(track_new_mem_heap)</code> with an appropriate 234 function pointer, and the assigned function will be called each time 235 this happens.</p> 236 <p>More information about "details", "needs" and "trackable events" 237 can be found in 238 <code class="filename">include/pub_tool_tooliface.h</code>.</p> 239 </div> 240 <div class="sect2" title="2.2.6.Instrumentation"> 241 <div class="titlepage"><div><div><h3 class="title"> 242 <a name="manual-writing-tools.instr"></a>2.2.6.Instrumentation</h3></div></div></div> 243 <p><code class="function">instrument</code> is the interesting one. It 244 allows you to instrument <span class="emphasis"><em>VEX IR</em></span>, which is 245 Valgrind's RISC-like intermediate language. VEX IR is described 246 in the comments of the header file 247 <code class="filename">VEX/pub/libvex_ir.h</code>.</p> 248 <p>The easiest way to instrument VEX IR is to insert calls to C 249 functions when interesting things happen. See the tool "Lackey" 250 (<code class="filename">lackey/lk_main.c</code>) for a simple example of this, or 251 Cachegrind (<code class="filename">cachegrind/cg_main.c</code>) for a more 252 complex example.</p> 253 </div> 254 <div class="sect2" title="2.2.7.Finalisation"> 255 <div class="titlepage"><div><div><h3 class="title"> 256 <a name="manual-writing-tools.fini"></a>2.2.7.Finalisation</h3></div></div></div> 257 <p>This is where you can present the final results, such as a summary 258 of the information collected. Any log files should be written out at 259 this point.</p> 260 </div> 261 <div class="sect2" title="2.2.8.Other Important Information"> 262 <div class="titlepage"><div><div><h3 class="title"> 263 <a name="manual-writing-tools.otherinfo"></a>2.2.8.Other Important Information</h3></div></div></div> 264 <p>Please note that the core/tool split infrastructure is quite 265 complex and not brilliantly documented. Here are some important points, 266 but there are undoubtedly many others that I should note but haven't 267 thought of.</p> 268 <p>The files <code class="filename">include/pub_tool_*.h</code> contain all the 269 types, macros, functions, etc. that a tool should (hopefully) need, and are 270 the only <code class="filename">.h</code> files a tool should need to 271 <code class="computeroutput">#include</code>. They have a reasonable amount of 272 documentation in it that should hopefully be enough to get you going.</p> 273 <p>Note that you can't use anything from the C library (there 274 are deep reasons for this, trust us). Valgrind provides an 275 implementation of a reasonable subset of the C library, details of which 276 are in <code class="filename">pub_tool_libc*.h</code>.</p> 277 <p>When writing a tool, in theory you shouldn't need to look at any of 278 the code in Valgrind's core, but in practice it might be useful sometimes to 279 help understand something.</p> 280 <p>The <code class="filename">include/pub_tool_basics.h</code> and 281 <code class="filename">VEX/pub/libvex_basictypes.h</code> files have some basic 282 types that are widely used.</p> 283 <p>Ultimately, the tools distributed (Memcheck, Cachegrind, Lackey, etc.) 284 are probably the best documentation of all, for the moment.</p> 285 <p>The <code class="computeroutput">VG_</code> macro is used 286 heavily. This just prepends a longer string in front of names to avoid 287 potential namespace clashes. It is defined in 288 <code class="filename">include/pub_tool_basics.h</code>.</p> 289 <p>There are some assorted notes about various aspects of the 290 implementation in <code class="filename">docs/internals/</code>. Much of it 291 isn't that relevant to tool-writers, however.</p> 292 </div> 293 </div> 294 <div class="sect1" title="2.3.Advanced Topics"> 295 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 296 <a name="manual-writing-tools.advtopics"></a>2.3.Advanced Topics</h2></div></div></div> 297 <p>Once a tool becomes more complicated, there are some extra 298 things you may want/need to do.</p> 299 <div class="sect2" title="2.3.1.Debugging Tips"> 300 <div class="titlepage"><div><div><h3 class="title"> 301 <a name="manual-writing-tools.advice"></a>2.3.1.Debugging Tips</h3></div></div></div> 302 <p>Writing and debugging tools is not trivial. Here are some 303 suggestions for solving common problems.</p> 304 <p>If you are getting segmentation faults in C functions used by your 305 tool, the usual GDB command:</p> 306 <pre class="screen"> 307 gdb <prog> core</pre> 308 <p>usually gives the location of the segmentation fault.</p> 309 <p>If you want to debug C functions used by your tool, there are 310 instructions on how to do so in the file 311 <code class="filename">README_DEVELOPERS</code>.</p> 312 <p>If you are having problems with your VEX IR instrumentation, it's 313 likely that GDB won't be able to help at all. In this case, Valgrind's 314 <code class="option">--trace-flags</code> option is invaluable for observing the 315 results of instrumentation.</p> 316 <p>If you just want to know whether a program point has been reached, 317 using the <code class="computeroutput">OINK</code> macro (in 318 <code class="filename">include/pub_tool_libcprint.h</code>) can be easier than 319 using GDB.</p> 320 <p>The other debugging command line options can be useful too (run 321 <code class="computeroutput">valgrind --help-debug</code> for the 322 list).</p> 323 </div> 324 <div class="sect2" title="2.3.2.Suppressions"> 325 <div class="titlepage"><div><div><h3 class="title"> 326 <a name="manual-writing-tools.suppressions"></a>2.3.2.Suppressions</h3></div></div></div> 327 <p>If your tool reports errors and you want to suppress some common 328 ones, you can add suppressions to the suppression files. The relevant 329 files are <code class="filename">*.supp</code>; the final suppression 330 file is aggregated from these files by combining the relevant 331 <code class="filename">.supp</code> files depending on the versions of linux, X 332 and glibc on a system.</p> 333 <p>Suppression types have the form 334 <code class="computeroutput">tool_name:suppression_name</code>. The 335 <code class="computeroutput">tool_name</code> here is the name you specify 336 for the tool during initialisation with 337 <code class="function">VG_(details_name)</code>.</p> 338 </div> 339 <div class="sect2" title="2.3.3.Documentation"> 340 <div class="titlepage"><div><div><h3 class="title"> 341 <a name="manual-writing-tools.docs"></a>2.3.3.Documentation</h3></div></div></div> 342 <p>If you are feeling conscientious and want to write some 343 documentation for your tool, please use XML as the rest of Valgrind does. 344 The file <code class="filename">docs/README</code> has more details on getting 345 the XML toolchain to work; this can be difficult, unfortunately.</p> 346 <p>To write the documentation, follow these steps (using 347 <code class="computeroutput">foobar</code> as the example tool name 348 again):</p> 349 <div class="orderedlist"><ol class="orderedlist" type="1"> 350 <li class="listitem"><p>The docs go in 351 <code class="computeroutput">foobar/docs/</code>, which you will 352 have created when you started writing the tool.</p></li> 353 <li class="listitem"> 354 <p>Copy the XML documentation file for the tool Nulgrind from 355 <code class="filename">none/docs/nl-manual.xml</code> to 356 <code class="computeroutput">foobar/docs/</code>, and rename it to 357 <code class="filename">foobar/docs/fb-manual.xml</code>.</p> 358 <p><span class="command"><strong>Note</strong></span>: there is a tetex bug 359 involving underscores in filenames, so don't use '_'.</p> 360 </li> 361 <li class="listitem"><p>Write the documentation. There are some helpful bits and 362 pieces on using XML markup in 363 <code class="filename">docs/xml/xml_help.txt</code>.</p></li> 364 <li class="listitem"><p>Include it in the User Manual by adding the relevant entry to 365 <code class="filename">docs/xml/manual.xml</code>. Copy and edit an 366 existing entry.</p></li> 367 <li class="listitem"><p>Include it in the man page by adding the relevant entry to 368 <code class="filename">docs/xml/valgrind-manpage.xml</code>. Copy and 369 edit an existing entry.</p></li> 370 <li class="listitem"> 371 <p>Validate <code class="filename">foobar/docs/fb-manual.xml</code> using 372 the following command from within <code class="filename">docs/</code>: 373 </p> 374 <pre class="screen"> 375 make valid 376 </pre> 377 <p>You may get errors that look like this:</p> 378 <pre class="screen"> 379 ./xml/index.xml:5: element chapter: validity error : No declaration for 380 attribute base of element chapter 381 </pre> 382 <p>Ignore (only) these -- they're not important.</p> 383 <p>Because the XML toolchain is fragile, it is important to ensure 384 that <code class="filename">fb-manual.xml</code> won't break the documentation 385 set build. Note that just because an XML file happily transforms to 386 html does not necessarily mean the same holds true for pdf/ps.</p> 387 </li> 388 <li class="listitem"> 389 <p>You can (re-)generate the HTML docs while you are writing 390 <code class="filename">fb-manual.xml</code> to help you see how it's looking. 391 The generated files end up in 392 <code class="filename">docs/html/</code>. Use the following 393 command, within <code class="filename">docs/</code>:</p> 394 <pre class="screen"> 395 make html-docs 396 </pre> 397 </li> 398 <li class="listitem"> 399 <p>When you have finished, try to generate PDF and PostScript output to 400 check all is well, from within <code class="filename">docs/</code>: 401 </p> 402 <pre class="screen"> 403 make print-docs 404 </pre> 405 <p>Check the output <code class="filename">.pdf</code> and 406 <code class="filename">.ps</code> files in 407 <code class="computeroutput">docs/print/</code>.</p> 408 <p>Note that the toolchain is even more fragile for the print docs, 409 so don't feel too bad if you can't get it working.</p> 410 </li> 411 </ol></div> 412 </div> 413 <div class="sect2" title="2.3.4.Regression Tests"> 414 <div class="titlepage"><div><div><h3 class="title"> 415 <a name="manual-writing-tools.regtests"></a>2.3.4.Regression Tests</h3></div></div></div> 416 <p>Valgrind has some support for regression tests. If you want to 417 write regression tests for your tool:</p> 418 <div class="orderedlist"><ol class="orderedlist" type="1"> 419 <li class="listitem"><p>The tests go in <code class="computeroutput">foobar/tests/</code>, 420 which you will have created when you started writing the tool.</p></li> 421 <li class="listitem"><p>Write <code class="filename">foobar/tests/Makefile.am</code>. Use 422 <code class="filename">memcheck/tests/Makefile.am</code> as an 423 example.</p></li> 424 <li class="listitem"><p>Write the tests, <code class="computeroutput">.vgtest</code> test 425 description files, <code class="computeroutput">.stdout.exp</code> and 426 <code class="computeroutput">.stderr.exp</code> expected output files. 427 (Note that Valgrind's output goes to stderr.) Some details on 428 writing and running tests are given in the comments at the top of 429 the testing script 430 <code class="computeroutput">tests/vg_regtest</code>.</p></li> 431 <li class="listitem"><p>Write a filter for stderr results 432 <code class="computeroutput">foobar/tests/filter_stderr</code>. It can 433 call the existing filters in 434 <code class="computeroutput">tests/</code>. See 435 <code class="computeroutput">memcheck/tests/filter_stderr</code> for an 436 example; in particular note the 437 <code class="computeroutput">$dir</code> trick that ensures the filter 438 works correctly from any directory.</p></li> 439 </ol></div> 440 </div> 441 <div class="sect2" title="2.3.5.Profiling"> 442 <div class="titlepage"><div><div><h3 class="title"> 443 <a name="manual-writing-tools.profiling"></a>2.3.5.Profiling</h3></div></div></div> 444 <p>Lots of profiling tools have trouble running Valgrind. For example, 445 trying to use gprof is hopeless.</p> 446 <p>Probably the best way to profile a tool is with OProfile on Linux.</p> 447 <p>You can also use Cachegrind on it. Read 448 <code class="filename">README_DEVELOPERS</code> for details on running Valgrind under 449 Valgrind; it's a bit fragile but can usually be made to work.</p> 450 </div> 451 <div class="sect2" title="2.3.6.Other Makefile Hackery"> 452 <div class="titlepage"><div><div><h3 class="title"> 453 <a name="manual-writing-tools.mkhackery"></a>2.3.6.Other Makefile Hackery</h3></div></div></div> 454 <p>If you add any directories under 455 <code class="computeroutput">foobar/</code>, you will need to add 456 an appropriate <code class="filename">Makefile.am</code> to it, and add a 457 corresponding entry to the <code class="computeroutput">AC_OUTPUT</code> 458 list in <code class="filename">configure.in</code>.</p> 459 <p>If you add any scripts to your tool (see Cachegrind for an 460 example) you need to add them to the 461 <code class="computeroutput">bin_SCRIPTS</code> variable in 462 <code class="filename">foobar/Makefile.am</code> and possible also to the 463 <code class="computeroutput">AC_OUTPUT</code> list in 464 <code class="filename">configure.in</code>.</p> 465 </div> 466 <div class="sect2" title="2.3.7.The Core/tool Interface"> 467 <div class="titlepage"><div><div><h3 class="title"> 468 <a name="manual-writing-tools.ifacever"></a>2.3.7.The Core/tool Interface</h3></div></div></div> 469 <p>The core/tool interface evolves over time, but it's pretty stable. 470 We deliberately do not provide backward compatibility with old interfaces, 471 because it is too difficult and too restrictive. We view this as a good 472 thing -- if we had to be backward compatible with earlier versions, many 473 improvements now in the system could not have been added.</p> 474 <p>Because tools are statically linked with the core, if a tool compiles 475 successfully then it should be compatible with the core. We would not 476 deliberately violate this property by, for example, changing the behaviour 477 of a core function without changing its prototype.</p> 478 </div> 479 </div> 480 <div class="sect1" title="2.4.Final Words"> 481 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 482 <a name="manual-writing-tools.finalwords"></a>2.4.Final Words</h2></div></div></div> 483 <p>Writing a new Valgrind tool is not easy, but the tools you can write 484 with Valgrind are among the most powerful programming tools there are. 485 Happy programming!</p> 486 </div> 487 </div> 488 <div> 489 <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 490 <tr> 491 <td rowspan="2" width="40%" align="left"> 492 <a accesskey="p" href="design-impl.html"><<1.The Design and Implementation of Valgrind</a></td> 493 <td width="20%" align="center"><a accesskey="u" href="tech-docs.html">Up</a></td> 494 <td rowspan="2" width="40%" align="right"><a accesskey="n" href="cl-format.html">3.Callgrind Format Specification>></a> 495 </td> 496 </tr> 497 <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 498 </table> 499 </div> 500 </body> 501 </html> 502