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