Add some info about extended value string to section 1.7.1
[obnox/wireshark/wip.git] / doc / README.plugins
1 $Id$
2
3 1. Plugins
4
5 Writing a "plugin" dissector is not very different from writing a
6 standard one.  In fact all of the functions described in
7 README.developer can be used in the plugins exactly as they are used in
8 standard dissectors.
9
10 (Note, however, that not all OSes on which Wireshark runs can support
11 plugins.)
12
13 If you've chosen "xxx" as the name of your plugin (typically, that would
14 be a short name for your protocol, in all lower case), the following
15 instructions tell you how to implement it as a plugin.  All occurrences
16 of "xxx" below should be replaced by the name of your plugin.
17
18 2. The directory for the plugin, and its files
19
20 The plugin should be placed in a new plugins/xxx directory which should
21 contain minimally the following files:
22
23 AUTHORS
24 COPYING
25 ChangeLog
26 CMakeLists.txt
27 Makefile.am
28 Makefile.common
29 Makefile.nmake
30 moduleinfo.h
31 moduleinfo.nmake
32 plugin.rc.in
33 The source files and header files for your dissector
34
35 Examples of these files can be found in plugins/gryphon.
36
37 2.1 AUTHORS, COPYING, and ChangeLog
38
39 The AUTHORS, COPYING, and ChangeLog are the standard sort of GPL project
40 files.
41
42 2.2 CMakeLists.txt
43
44 For your plugins/xxx/CMakeLists.txt file, see the corresponding file in
45 plugins/gryphon. Replace all occurrences of "gryphon" in those files
46 with "xxx" and add your source files to the DISSECTOR_SRC variable.
47
48 2.3 Makefile.am
49
50 For your plugins/xxx/Makefile.am file, see the corresponding file in
51 plugins/gryphon. Replace all occurrences of "gryphon" in those files
52 with "xxx".
53
54 2.4 Makefile.common
55
56 Your plugins/xxx/Makefile.common should only list the main source file(s),
57 which exports register_*() and handoff_*(), for your dissector in the
58 DISSECTOR_SRC variable, and all other supporting source files in the
59 DISSECTOR_SUPPORT_SRC variable.
60 The header files for your dissector, if any, must be listed in the
61 DISSECTOR_INCLUDES variable. The DISSECTOR_INCLUDES variable should not
62 include moduleinfo.h.
63
64 2.5 Makefile.nmake
65
66 For your plugins/xxx/Makefile.nmake file, see the corresponding file in
67 plugins/gryphon. No modifications are needed here.
68
69 2.6 moduleinfo.h
70
71 Your plugins/xxx/moduleinfo.h file is used to set the version information
72 for the plugin.
73
74 2.7 moduleinfo.nmake
75
76 Your plugins/xxx/moduleinfo.nmake is used to set the version information
77 for building the plugin. Its contents should match that in moduleinfo.h
78
79 2.8 plugin.rc.in
80
81 Your plugins/xxx/plugin.rc.in is the Windows resource template file
82 used to add the plugin specific information as resources to the DLL.
83 No modifications are needed here.
84
85 3. Changes to existing Wireshark files
86
87 You will also need to change the following files:
88         configure.in
89         CMakeLists.txt
90         epan/Makefile.am
91         Makefile.am
92         packaging/nsis/Makefile.nmake
93         packaging/nsis/wireshark.nsi
94         plugins/Makefile.am
95         plugins/Makefile.nmake
96
97 You might also want to search your Wireshark development directory for
98 occurrences of an existing plugin name, in case this document is out of
99 date with the current directory structure. For example,
100
101         grep -rl gryphon .
102
103 could be used from a shell prompt.
104
105 3.1  Changes to plugins/Makefile.am
106
107 The plugins directory contains a Makefile.am.  You need to change the
108 SUBDIRS directive to reflect the addition of your plugin:
109
110 SUBDIRS = $(_CUSTOM_SUBDIRS_) \
111         ...
112         gryphon \
113         irda \
114         xxx \
115
116 3.2 Changes to plugins/Makefile.nmake
117
118 In plugins/Makefile.nmake you need to add to the PLUGINS_LIST  
119 (in alphabetical order) the name of your dissector (actually:
120 the name of the plugins sub-directory which contains your dissector).
121
122 3.3 Changes to the top level Makefile.am
123
124 Add your plugin (in alphabetical order) to the plugin_ldadd:
125
126 if HAVE_PLUGINS
127
128 plugin_ldadd = \
129         ...
130         -dlopen plugins/gryphon/gryphon.la      \
131         -dlopen plugins/irda/irda.la    \
132         -dlopen plugins/xxx/xxx.la      \
133         ...
134
135 3.4  Changes to the top level configure.in
136
137 You need to add your plugins Makefile (in alphbetical order) to the AC_OUTPUT
138 rule in the configure.in
139
140 AC_OUTPUT(
141   ...
142   plugins/gryphon/Makefile
143   plugins/irda/Makefile
144   plugins/xxx/Makefile
145   ...
146   ,)
147
148 3.5  Changes to epan/Makefile.am
149
150 Add the relative path of your plugin (in alphbetical order) to plugin_src:
151
152 plugin_src = \
153         ...
154         ../plugins/gryphon/packet-gryphon.c \
155         ../plugins/irda/packet-irda.c \
156         ../plugins/xxx/packet-xxx.c \
157         ...
158
159 3.6  Changes to CMakeLists.txt
160
161 Add your plugin (in alphabetical order) to the PLUGIN_SRC_DIRS:
162
163 if(ENABLE_PLUGINS)
164         ...
165         set(PLUGIN_SRC_DIRS
166                 ...
167                 plugins/gryphon
168                 plugins/irda
169                 plugins/xxx
170                 ...
171
172 3.7  Changes to the installers
173
174 If you want to include your plugin in an installer you have to add lines
175 in the NSIS installer Makefile.nmake and wireshark.nsi files.
176
177 For the NSIS installer:
178
179         Add ../../plugins/xxx/xxx.dll to the list of plugins for the
180         PLUGINS variable in packaging/nsis/Makefile.nmake.
181
182         Add
183
184                 File "..\..\plugins\xxx\xxx.dll"
185
186         to the list of "File" statements in the "Dissector Plugins"
187         section in packaging/nsis/wireshark.nsi.
188
189 The U3 and PortableApps installers build their manifests, including plugins,
190 from packaging/nsis/wireshark.nsi via the packaging/ws-manifest.pl script.
191
192 4. Development and plugins on Unix
193
194 Plugins make some aspects of development easier and some harder.
195
196 The first thing is that you'll have to run autogen.sh and configure
197 once more to setup your build environment.
198
199 The good news is that if you are working on a single plugin
200 then you will find recompiling the plugin MUCH faster than
201 recompiling a dissector and then linking it back into Wireshark.
202
203 The bad news is that Wireshark will not use the plugins unless the
204 plugins are installed in one of the places it expects them to find.
205
206 One way of dealing with this problem is to set an environment variable
207 when running Wireshark: WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1.
208
209 Another way to deal with this problem is to set up a working root for
210 wireshark, say in $HOME/build/root and build wireshark to install
211 there
212
213 ./configure --prefix=${HOME}/build/root;make install
214
215 then subsequent rebuilds/installs of your plugin can be accomplished
216 by going to the plugins/xxx directory and running
217
218 make install
219
220 5. Update "old style" plugins
221
222 5.1 How to update an "old style" plugin (using plugin_register and
223     plugin_reg_handoff functions).
224
225 The plugin registration has changed with the extension of the build
226 scripts. These now generate the additional code needed for plugin
227 encapsulation in plugin.c. When using the new style build scripts,
228 stips the parts outlined below:
229
230     o Remove the following include statements:
231
232         #include <gmodule.h>
233         #include "moduleinfo.h"
234
235     o Removed the definition:
236
237         #ifndef ENABLE_STATIC
238         G_MODULE_EXPORT gchar version[] = VERSION;
239         #endif
240
241     o Move relevant code from the blocks and delete these functions:
242
243         #ifndef ENABLE_STATIC
244         plugin_reg_handoff()
245         ....
246         #endif
247
248         #ifndef ENABLE_STATIC
249         plugin_register()
250         ....
251         #endif
252
253 This will leave a clean dissector source file without plugin specifics.
254
255 5.2 How to update an "old style" plugin (using plugin_init function)
256
257 The plugin registering has changed between 0.10.9 and 0.10.10; everyone
258 is encouraged to update their plugins as outlined below:
259
260     o Remove following include statements from all plugin sources:
261
262         #include "plugins/plugin_api.h"
263         #include "plugins/plugin_api_defs.h"
264
265     o Remove the init function.
266
267     o Add a new Makefile.common file with the lists of source files and
268       headers.
269
270     o Change the Makefile.am and Makefile.nmake files to match those of
271       the DOCSIS plugin.
272
273 ----------------
274
275 Ed Warnicke <hagbard@physics.rutgers.edu>
276 Guy Harris <guy@alum.mit.edu>
277
278 Derived and expanded from the plugin section of README.developers
279 which was originally written by
280
281 James Coe <jammer@cin.net>
282 Gilbert Ramirez <gram@alumni.rice.edu>
283 Jeff Foster <jfoste@woodward.com>
284 Olivier Abad <oabad@cybercable.fr>
285 Laurent Deniel <laurent.deniel@free.fr>
286 Jaap Keuter <jaap.keuter@xs4all.nl>