Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / valgrind / refs/tags/21.01.0-rel.0 / . / docs / html / manual-writing-tools.html
blob: 04c3b36744252598a84f28239ec0ecfb23278ca3 [file] [log] [blame]
Elliott Hughesa0664b92017-04-18 17:46:52 -0700[diff] [blame]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" type="text/css" href="vg_basic.css">
Elliott Hughesed398002017-06-21 14:41:24 -0700[diff] [blame]6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
Elliott Hughesa0664b92017-04-18 17:46:52 -0700[diff] [blame]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">
21<div class="titlepage"><div><div><h1 class="title">
22<a name="manual-writing-tools"></a>2. Writing a New Valgrind Tool</h1></div></div></div>
23<div class="toc">
24<p><b>Table of Contents</b></p>
25<dl class="toc">
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
52So you want to write a Valgrind tool? Here are some instructions that may
53help.
54
55<div class="sect1">
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
59between 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
61support program instrumentation, including the JIT
62compiler, low-level memory manager, signal handling and a
63thread scheduler. It also provides certain services that
64are useful to some but not all tools, such as support for error
65recording, 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
68must be filled by tools. Most notably, tools define how program
69code should be instrumented. They can also call certain
70functions to indicate to the core that they would like to use
71certain services, or be notified when certain interesting events
72occur. But the core takes care of all the hard work.</p>
73</div>
74<div class="sect1">
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">
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
81that are called by Valgrind's core. They are then linked against
82Valgrind's core to define a complete Valgrind tool which will be used
83when the <code class="option">--tool</code> option is used to select it.</p>
84</div>
85<div class="sect2">
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
89need a check-out of the Subversion repository for the automake/autoconf
90build instructions to work. See the information about how to do check-out
91from the repository at <a class="ulink" href="http://www.valgrind.org/downloads/repository.html" target="_top">the Valgrind
92website</a>.</p>
93</div>
94<div class="sect2">
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
99and configuration. But don't worry, these instructions should be enough
100to get you started even if you know nothing about those tools.</p>
101<p>In what follows, all filenames are relative to Valgrind's
102top-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.
Elliott Hughesed398002017-06-21 14:41:24 -0700[diff] [blame]162 ==738== Copyright (C) 2002-2017, and GNU GPL'd, by J. Programmer.
163 ==738== Using Valgrind-3.13.0.SVN and LibVEX; rerun with -h for copyright info
Elliott Hughesa0664b92017-04-18 17:46:52 -0700[diff] [blame]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
172different 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,
176onto the interesting stuff...</p>
177</div>
178<div class="sect2">
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
188names. The first one is registered using the macro
189<code class="computeroutput">VG_DETERMINE_INTERFACE_VERSION</code>.
190The 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
193provided by the core, it may have to define other functions and tell the
194core about them.</p>
195</div>
196<div class="sect2">
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
202options and must do some initialisation after option processing takes
203place (<code class="computeroutput">"clo"</code> stands for "command line
204options").</p>
205<p>First of all, various "details" need to be set for a tool, using
206the functions <code class="function">VG_(details_*)</code>. Some are all
207compulsory, some aren't. Some are used when constructing the startup
208message, <code class="computeroutput">detail_bug_reports_to</code> is used
209if <code class="computeroutput">VG_(tool_panic)</code> is ever called, or
210a 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
213be left untouched (they default to <code class="varname">False</code>). They
214determine whether a tool can do various things such as: record, report
215and suppress errors; process command line options; wrap system calls;
216record extra information about heap blocks; etc.</p>
217<p>For example, if a tool wants the core's help in recording and
218reporting errors, it must call
219<code class="function">VG_(needs_tool_errors)</code> and provide definitions of
220eight functions for comparing errors, printing out errors, reading
221suppressions from a suppressions file, etc. While writing these
222functions requires some work, it's much less than doing error handling
223from 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
226notified about, using the functions <code class="function">VG_(track_*)</code>.
227These include things such as heap blocks being allocated, the stack
228pointer changing, a mutex being locked, etc. If a tool wants to know
229about this, it should provide a pointer to a function, which will be
230called when that event happens.</p>
231<p>For example, if the tool want to be notified when a new heap block
232is allocated, it should call
233<code class="function">VG_(track_new_mem_heap)</code> with an appropriate
234function pointer, and the assigned function will be called each time
235this happens.</p>
236<p>More information about "details", "needs" and "trackable events"
237can be found in
238<code class="filename">include/pub_tool_tooliface.h</code>.</p>
239</div>
240<div class="sect2">
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
244allows you to instrument <span class="emphasis"><em>VEX IR</em></span>, which is
245Valgrind's RISC-like intermediate language. VEX IR is described
246in 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
249functions when interesting things happen. See the tool "Lackey"
250(<code class="filename">lackey/lk_main.c</code>) for a simple example of this, or
251Cachegrind (<code class="filename">cachegrind/cg_main.c</code>) for a more
252complex example.</p>
253</div>
254<div class="sect2">
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
258of the information collected. Any log files should be written out at
259this point.</p>
260</div>
261<div class="sect2">
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
265complex and not brilliantly documented. Here are some important points,
266but there are undoubtedly many others that I should note but haven't
267thought of.</p>
268<p>The files <code class="filename">include/pub_tool_*.h</code> contain all the
269types, macros, functions, etc. that a tool should (hopefully) need, and are
270the only <code class="filename">.h</code> files a tool should need to
271<code class="computeroutput">#include</code>. They have a reasonable amount of
272documentation 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
274are deep reasons for this, trust us). Valgrind provides an
275implementation of a reasonable subset of the C library, details of which
276are 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
278the code in Valgrind's core, but in practice it might be useful sometimes to
279help 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
282types that are widely used.</p>
283<p>Ultimately, the tools distributed (Memcheck, Cachegrind, Lackey, etc.)
284are probably the best documentation of all, for the moment.</p>
285<p>The <code class="computeroutput">VG_</code> macro is used
286heavily. This just prepends a longer string in front of names to avoid
287potential 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
290implementation in <code class="filename">docs/internals/</code>. Much of it
291isn't that relevant to tool-writers, however.</p>
292</div>
293</div>
294<div class="sect1">
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
298things you may want/need to do.</p>
299<div class="sect2">
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
303suggestions for solving common problems.</p>
304<p>If you are getting segmentation faults in C functions used by your
305tool, the usual GDB command:</p>
306<pre class="screen">
307 gdb &lt;prog&gt; 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
310instructions 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
313likely 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
315results of instrumentation.</p>
316<p>If you just want to know whether a program point has been reached,
317using the <code class="computeroutput">OINK</code> macro (in
318<code class="filename">include/pub_tool_libcprint.h</code>) can be easier than
319using 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
322list).</p>
323</div>
324<div class="sect2">
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
328ones, you can add suppressions to the suppression files. The relevant
329files are <code class="filename">*.supp</code>; the final suppression
330file is aggregated from these files by combining the relevant
331<code class="filename">.supp</code> files depending on the versions of linux, X
332and 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
336for the tool during initialisation with
337<code class="function">VG_(details_name)</code>.</p>
338</div>
339<div class="sect2">
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
343documentation for your tool, please use XML as the rest of Valgrind does.
344The file <code class="filename">docs/README</code> has more details on getting
345the 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
348again):</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">
375make 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
380attribute 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">
395make 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">
403make 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">
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
417write 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">
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,
445trying 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
449Valgrind; it's a bit fragile but can usually be made to work.</p>
450</div>
451<div class="sect2">
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
456an appropriate <code class="filename">Makefile.am</code> to it, and add a
457corresponding entry to the <code class="computeroutput">AC_OUTPUT</code>
458list in <code class="filename">configure.in</code>.</p>
459<p>If you add any scripts to your tool (see Cachegrind for an
460example) 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">
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.
470We deliberately do not provide backward compatibility with old interfaces,
471because it is too difficult and too restrictive. We view this as a good
472thing -- if we had to be backward compatible with earlier versions, many
473improvements now in the system could not have been added.</p>
474<p>Because tools are statically linked with the core, if a tool compiles
475successfully then it should be compatible with the core. We would not
476deliberately violate this property by, for example, changing the behaviour
477of a core function without changing its prototype.</p>
478</div>
479</div>
480<div class="sect1">
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
484with Valgrind are among the most powerful programming tools there are.
485Happy 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">&lt;&lt; 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 &gt;&gt;</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>