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