| blob | e6a1bf48294d7c2f43f0ce6cb02a853ceef5245d |
1 <!-- WSDG Chapter Sources -->
2 <!-- $Id$ -->
4 <chapter id="ChapterSources">
5 <title>Work with the Wireshark sources</title>
7 <section id="ChSrcIntro">
8 <title>Introduction</title>
9 <para>
10 This chapter will explain how to work with the Wireshark source code.
11 It will show you how to:
12 <itemizedlist>
13 <listitem><para>
14 get the source
15 </para></listitem>
16 <listitem><para>
17 compile the source
18 </para></listitem>
19 <listitem><para>
20 submit changes
21 </para></listitem>
22 <listitem><para>
23 ...
24 </para></listitem>
25 </itemizedlist>
26 However, this chapter will not explain the source file contents in detail,
27 such as where to find a specific functionality. This is done in
28 <xref linkend="ChCodeOverview"/>.
29 </para>
30 </section>
32 <section id="ChSrcSVNServer">
33 <title>The Wireshark Subversion repository</title>
34 <para>
35 Subversion is used to keep track of the changes made to the Wireshark
36 source code. The Wireshark source code is stored inside Wireshark project's
37 Subversion repository located at a server at the wireshark.org domain.
38 </para>
39 <para>
40 To quote the Subversion book about "What is Subversion?":
41 </para>
42 <para>
43 <quote>Subversion is a free/open-source version control system. That is,
44 Subversion manages files and directories over time. A tree of files is
45 placed into a central repository. The repository is much like an ordinary
46 file server, except that it remembers every change ever made to your files
47 and directories. This allows you to recover older versions of your data,
48 or examine the history of how your data changed. In this regard, many
49 people think of a version control system as a sort of "time machine".
50 </quote>
51 </para>
52 <tip><title>Tip: Subversion and SVN is the same!</title>
53 <para>
54 Subversion is often abbreviated as SVN, as the command-line tools are
55 abbreviated that way. You will find both terms with the same meaning in
56 this book, in mailing list discussions and elsewhere.
57 </para>
58 </tip>
59 <para>
60 Using Wireshark's Subversion repository you can:
61 <itemizedlist>
62 <listitem><para>
63 keep your private sources up to date with very little effort
64 </para></listitem>
65 <listitem><para>
66 get a mail notification if someone changes the latest sources
67 </para></listitem>
68 <listitem><para>
69 get the source files from any previous release (or any other point in time)
70 </para></listitem>
71 <listitem><para>
72 have a quick look at the sources using a web interface
73 </para></listitem>
74 <listitem><para>
75 see which person changed a specific piece of code
76 </para></listitem>
77 <listitem><para>
78 ... and a lot more things related to the history of the Wireshark source
79 code development
80 </para></listitem>
81 </itemizedlist>
82 </para>
83 <para>
84 Subversion is divided into a client and a server part.
85 Thanks to Gerald Combs (the maintainer of the Subversion server),
86 no user has to deal with the maintenance of the Subversion server.
87 You will only need a Subversion client, which is available as
88 both a command-line and a GUI tool for many different platforms.
89 </para>
90 <para>
91 For further reference about Subversion, have a look at the homepage of the
92 Subversion project: <ulink url="http://subversion.apache.org/"/>. There
93 is a good and free book about it available at: <ulink
94 url="http://svnbook.red-bean.com/"/>.
95 </para>
96 <para>
97 Please note that Wireshark's public (anonymous) Subversion repository is
98 separate from the main repository.
99 It may take several minutes for committed changes to appear in the
100 public repository - so please be patient for a few minutes if you
101 desperately need a code change that was committed to the repository
102 very recently.
103 </para>
105 <section id="ChSrcWebInterface">
106 <title>The web interface to the Subversion repository</title>
107 <para>
108 If you need a quick look at the Wireshark source code,
109 you will only need a Web browser.
110 </para>
111 <para>
112 A <literal>simple view</literal> on the latest developer version can be
113 found at:
114 </para>
115 <para>
116 <ulink url="http://anonsvn.wireshark.org/wireshark/trunk/"/>.
117 </para>
118 <para>
119 A <literal>comprehensive view</literal> of all source versions
120 (e.g. including the capability to show differences between versions)
121 is available at:
122 </para>
123 <para>
124 <ulink url="http://anonsvn.wireshark.org/viewvc/viewvc.cgi/"/>.
125 </para>
126 <para>
127 Of special interest might be the subdirectories:
128 <itemizedlist>
129 <listitem><para>
130 <filename>trunk</filename> - the very latest source files
131 </para></listitem>
132 <listitem><para>
133 <filename>releases</filename> - the source files of all released versions
134 </para></listitem>
135 </itemizedlist>
136 </para>
137 </section>
138 </section>
140 <section id="ChSrcObtain">
141 <title>Obtain the Wireshark sources</title>
142 <para>
143 There are several ways to obtain the sources from Wireshark's Subversion
144 server.
145 </para>
146 <tip><title>Anonymous Subversion access is recommended!</title>
147 <para>
148 It can make your life much easier, compared to updating your source tree by
149 using any of the zip file methods mentioned below.
150 Subversion handles merging of changes into your personal source tree in a
151 very comfortable and quick way. So you can update your source tree several
152 times a day without much effort.
153 </para>
154 </tip>
155 <note><title>Keep your sources "up to date"!</title>
156 <para>
157 The following ways to retrieve the Wireshark sources are sorted in
158 decreasing source timeliness.
159 If you plan to commit changes you've made to the sources,
160 it's a good idea to keep your private source tree as current as possible.
161 </para>
162 </note>
163 <para>
164 The age mentioned in the following sections indicates the age of the
165 most recent change in that set of the sources.
166 </para>
168 <section id="ChSrcAnon">
169 <title>Anonymous Subversion access</title>
170 <para>
171 Recommended for development purposes.
172 </para>
173 <para>
174 Age: a few minutes.
175 </para>
176 <para>
177 You can use a Subversion client to download the source code from
178 Wireshark's anonymous Subversion repository. The URL for the repository
179 trunk is:
180 <ulink url="&WiresharkRepositorySite;/wireshark/trunk/"/>.
181 </para>
182 <para>
183 See <xref linkend="ChToolsSubversion"/> on how to install a Subversion client.
184 </para>
185 <para>
186 For example, to check out using the command-line Subversion client, you
187 would type:
188 </para>
189 <para>
190 <prompt>$</prompt>
191 <userinput>svn checkout &WiresharkRepositorySite;/wireshark/trunk wireshark</userinput>
192 </para>
193 <para>
194 The checkout has to be only done once. This will copy all the sources of
195 the latest version (including directories) from the server to your machine.
196 This will take some time, depending on the speed of your internet connection.
197 </para>
198 </section>
200 <section id="ChSrcSVNWeb">
201 <title>Anonymous Subversion web interface</title>
202 <para>
203 Recommended for informational purposes only, as only individual files can
204 be downloaded.
205 </para>
206 <para>
207 Age: a few minutes (same as anonymous Subversion access).
208 </para>
209 <para>
210 The entire source tree of the Subversion repository is available via a
211 web interface at:
212 <ulink url="&WiresharkRepositorySite;/viewvc/viewvc.cgi/"/>.
213 You can view each revision of a particular file, as well as diffs between
214 different revisions.
215 You can also download individual files but not entire directories.
216 </para>
217 </section>
219 <section id="ChSrcBuildbot">
220 <title>Buildbot Snapshots</title>
221 <para>
222 Recommended for development purposes, if direct Subversion access isn't
223 possible (e.g. because of a restrictive firewall).
224 </para>
225 <para>
226 Age: some number of minutes (a bit older than the anonymous Subversion access).
227 </para>
228 <para>
229 The buildbot server will automatically start to generate a snapshot of
230 Wireshark's source tree after a source code change is committed.
231 These snapshots can be found at: <ulink
232 url="&WiresharkDownloadPage;automated/src/"/>.
233 </para>
234 <para>
235 If anonymous Subversion access isn't possible, e.g. if the connection to
236 the server isn't possible because of a corporate firewall, the sources
237 can be obtained by downloading the buildbot snapshots. However, if you are
238 going to maintain your sources in parallel to the "official" sources
239 for some time, it's recommended to use the anonymous Subversion access if
240 possible (believe it, it will save you a lot of time).
241 </para>
242 </section>
245 <section id="ChSrcReleased">
246 <title>Released sources</title>
247 <para>
248 Recommended for productive purposes.
249 </para>
250 <para>
251 Age: from days to weeks.
252 </para>
253 <para>
254 The officially released source files can be found at: <ulink
255 url="&WiresharkDownloadPage;"/>.
256 You should use these sources if you want to build Wireshark on your
257 platform for productive use.
258 </para>
259 <para>
260 The differences between the released sources and the sources stored at
261 the Subversion repository will keep on growing until the next release is
262 done (at the release time, the released and latest Subversion repository
263 versions are then identical again :-).
264 </para>
265 </section>
267 </section>
269 <section id="ChSrcUpdating">
270 <title>Update the Wireshark sources</title>
271 <para>
272 After you've obtained the Wireshark sources for the first time, you
273 might want to keep them in sync with the sources at the Subversion
274 repository.
275 </para>
276 <tip><title>Take a look at the buildbot first!</title>
277 <para>
278 As development evolves, the Wireshark sources are compilable most of the
279 time - but not always.
280 You may take a look at the <xref linkend="ChIntroAutomated"/> first,
281 to see if the sources are currently in a good shape.
282 </para>
283 </tip>
285 <section id="ChSrcAnonUpdate">
286 <title>... with Anonymous Subversion access</title>
287 <para>
288 After the first time checkout is done, updating your
289 sources is simply done by typing (in the Wireshark source dir):
290 </para>
291 <para>
292 <prompt>$</prompt>
293 <userinput>svn update</userinput>
294 </para>
295 <para>
296 This will only take a few seconds, even on a slow internet connection. It will
297 replace old file versions by new ones. If you and someone else have
298 changed the same file since the last update, Subversion will try to merge
299 the changes into your private file (this works remarkably well).
300 </para>
301 </section>
303 <section id="ChSrcZipUpdate">
304 <title>... from zip files</title>
305 <para>
306 Independent of the way you retrieve the zip file of the Wireshark sources
307 (as described in <xref linkend="ChSrcObtain"/> ), the way to
308 bring the changes from the official sources into your personal source tree
309 is identical.
310 </para>
311 <para>
312 First of all, you will download the new zip file of the official sources
313 the way you did it the first time.
314 </para>
315 <para>
316 If you haven't changed anything in the sources, you could simply throw
317 away your old sources and reinstall everything just like the first time.
318 But be sure, that you really haven't changed anything. It might be a good
319 idea to simply rename the "old" dir to have it around, just in case you
320 remember later that you really did change something before.
321 </para>
322 <para>
323 Well, if you did change something in your source tree, you have to merge
324 the official changes
325 since the last update into your source tree. You will install the content
326 of the zip file into a new directory and use a good merge tool (e.g.
327 <ulink url="http://winmerge.sourceforge.net/"/> for Win32) to bring
328 your personal source tree in sync with the official sources again.
329 </para>
330 </section>
332 </section>
334 <section id="ChSrcBuildFirstTime">
335 <title>Build Wireshark</title>
336 <para>
337 The sources contain several documentation files, it's a good idea to
338 look at these files first.
339 </para>
340 <para>
341 So after obtaining the sources, tools and libraries, the
342 first place to look at is <filename>doc/README.developer</filename>,
343 here you will get the latest infos for Wireshark development for all
344 supported platforms.
345 </para>
346 <tip><title>Tip!</title>
347 <para>
348 It is a very good idea, to first test your complete build environment
349 (including running and debugging Wireshark) before doing any changes
350 to the source code (unless otherwise noted).
351 </para>
352 </tip>
353 <para>
354 The following steps for the first time generation differ on the two
355 major platforms.
356 </para>
358 <section>
359 <title>Unix</title>
360 <para>
361 Run the autogen.sh script at the top-level wireshark directory to configure
362 your build directory.
363 <programlisting>
364 ./autogen.sh
365 ./configure
366 make
367 </programlisting>
368 </para>
369 <para>
370 If you need to build with a non-standard configuration, you can use:
371 <programlisting>
372 ./configure --help
373 </programlisting>
374 to see what options you have.
375 </para>
376 </section>
378 <section>
379 <title>Win32 native</title>
380 <para>
381 The first thing to do will be to check the file
382 <filename>config.nmake</filename> to determine if it reflects your configuration.
383 The settings in this file are well documented, so please have a look at
384 that file.
385 However, if you've installed the libraries and tools as recommended there
386 should be no need to edit things here.
387 </para>
388 <para>
389 Many of the file and directory names used in the build process go past the
390 old 8.3 naming limitations.
391 As a result, you should use the <command>cmd.exe</command> command interpreter
392 instead of the old <command>command.com</command>.
393 </para>
394 <para>
395 Be sure that your command-line environment is set up to compile
396 and link with MSVC++. When installing MSVC++, you can have your
397 system's environment set up to always allow compiling from the
398 command line, or you can invoke the vcvars32.bat script, which can
399 usually be found in the <filename>VC98\Bin</filename> subdirectory of the
400 directory in which Visual Studio was installed.
401 </para>
402 <para>
403 You should then cleanup any intermediate files, which are shipped for
404 convenience of Unix users, by typing at the command line prompt (cmd.exe):
405 </para>
406 <para>
407 <prompt>></prompt> <userinput>nmake -f Makefile.nmake distclean</userinput>
408 </para>
409 <para>
410 After doing this, typing at the command line prompt (cmd.exe):
411 </para>
412 <para>
413 <prompt>></prompt> <userinput>nmake -f Makefile.nmake all</userinput>
414 </para>
415 <para>
416 will start the whole Wireshark build process.
417 </para>
418 <para>
419 After the build process has successfully finished, you should find a
420 <filename>wireshark.exe</filename> and some other files
421 in the root directory.
422 </para>
423 </section>
425 </section>
427 <section id="ChSrcRunFirstTime">
428 <title>Run generated Wireshark</title>
429 <tip><title>Tip!</title>
430 <para>
431 An already installed Wireshark may interfere with your newly generated
432 version in various ways. If you have any problems getting your Wireshark
433 running the first time, it might be a good idea to remove the previously
434 installed version first.
435 </para>
436 </tip>
437 <section id="ChSrcRunFirstTimeUnix">
438 <title>Unix/Linux</title>
439 <para>
440 After a successful build you can run Wireshark right from the build
441 directory. Still the program would need to know that it's being run from
442 the build directory and not from its install location. This has inpact
443 on the directories where the program can find the other parts and
444 relevant data files.
445 </para>
446 <para>
447 In order to run the Wireshark from the build directory set the environment
448 variable <varname>WIRESHARK_RUN_FROM_BUILD_DIRECTORY</varname> and run
449 Wireshark. If your platform is properly setup, your build directory and
450 current working directory are not in your <varname>PATH</varname>, so the
451 commandline to launch Wireshark would be:
452 <command>WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./wireshark</command>.
453 </para>
454 <para>
455 There's no need to run Wireshark as root user, you just won't be able to
456 capture. When you opt to run Wireshark this way, your terminal output can
457 be informative when things don't work as expected.
458 </para>
459 </section>
460 <section id="ChSrcRunFirstTimeWin32">
461 <title>Win32 native</title>
462 <para>
463 During the build all relevant program files are collected in a subdirectory
464 <command>wireshark-gtk2</command>. You can run the program from there by
465 launching the wireshark.exe executable.
466 </para>
467 </section>
468 </section>
470 <section id="ChSrcDebug">
471 <title>Debug your generated Wireshark</title>
472 <section id="ChSrcUnixDebug">
473 <title>Unix/Linux</title>
474 <para>
475 When you want to investigate a problem with Wireshark you want to load
476 the program into your debugger. But loading wireshark into debugger fails
477 because of the libtool build environment. You'll have to wrap loading
478 wireshark into a libtool command:
479 <command>libtool --mode=execute gdb wireshark</command>
480 </para>
481 <para>
482 If you prefer a graphic debugger you can use the Data Display Debugger
483 (ddd) instead of GNU debugger (gdb).
484 </para>
485 <para>
486 Additional traps can be set on GLib by setting the <varname>G_DEBUG</varname>
487 environment variable:<command>G_DEBUG=fatal_criticals libtool --mode=execute
488 ddd wireshark</command>.
489 See <ulink url="http://library.gnome.org/devel/glib/stable/glib-running.html"/>
490 </para>
491 </section>
493 <section id="ChSrcWin32Debug">
494 <title>Win32 native</title>
495 <para>
496 XXX - add more info here.
497 </para>
498 </section>
499 </section>
501 <section id="ChSrcChange">
502 <title>Make changes to the Wireshark sources</title>
503 <para>
504 As the Wireshark developers are working on many different platforms, a lot of
505 editors are used to develop Wireshark (emacs, vi, Microsoft Visual Studio
506 and many many others). There's no "standard" or "default" development
507 environment.
508 </para>
509 <para>
510 There are several reasons why you might want to change the Wireshark
511 sources:
512 <itemizedlist>
513 <listitem><para>add your own new dissector</para></listitem>
514 <listitem><para>change/extend an existing dissector</para></listitem>
515 <listitem><para>fix a bug</para></listitem>
516 <listitem><para>implement a new glorious feature :-)</para></listitem>
517 </itemizedlist>
518 The internal structure of the Wireshark sources will be described in
519 <xref linkend="PartDevelopment"/>.
520 </para>
521 <tip><title>Tip!</title>
522 <para>
523 <literal>Ask the developer mailing list before you really start a new
524 development task.</literal>
525 If you have an idea what you want to add/change, it's a good idea to
526 contact the developer mailing list
527 (see <xref linkend="ChIntroMailingLists"/>)
528 and explain your idea. Someone else might already be working on the same
529 topic, so double effort can be reduced, or someone can give you some tips that
530 should be thought about (like side effects that are sometimes very
531 hard to see).
532 </para>
533 </tip>
534 </section>
536 <section id="ChSrcContribute">
537 <title>Contribute your changes</title>
538 <para>
539 If you have finished changing the Wireshark sources to suit your needs,
540 you might want to contribute your changes back to the Wireshark
541 community. You gain the following benefits by contributing your improvements:
542 <itemizedlist>
543 <listitem><para>
544 It's the right thing to do. Other people who find your contributions
545 useful will appreciate them, and you will know that you have helped
546 people in the same way that the developers of Wireshark have helped
547 you.
548 </para></listitem>
549 <listitem><para>
550 You get free enhancements. By making your code public, other developers
551 have a chance to make improvements, as there's always room for
552 improvements. In addition someone may implement advanced features on top of
553 your code, which can be useful for yourself too.
554 </para></listitem>
555 <listitem><para>
556 You save time and effort. The maintainers and developers of Wireshark
557 will maintain your code as well, updating it when API changes or other
558 changes are made, and generally keeping it in tune with what is
559 happening with Wireshark. So if Wireshark is updated (which is done
560 often), you can get a new Wireshark version from the website and your
561 changes will already be included without any effort for you.
562 </para></listitem>
563 </itemizedlist>
564 There's no direct way to commit changes to the SVN repository. Only a few
565 people are authorised to actually
566 make changes to the source code (check-in changed files). If you want
567 to submit your changes, you should make a diff file (a patch) and upload it to the bug tracker.
568 </para>
570 <section id="ChSrcDiffWhat">
571 <title>What is a diff file (a patch)?</title>
572 <para>
573 A <ulink url="http://en.wikipedia.org/wiki/Diff">diff file</ulink>
574 is a plain text file containing the differences between a pair of files
575 (or a multiple of such file pairs).
576 <tip><title>Tip!</title>
577 <para>A diff file is often also called a patch,
578 as it can be used to patch an existing source file or tree with changes
579 from somewhere else.
580 </para>
581 </tip>
582 </para>
583 <para>
584 The Wireshark community is using patches to transfer source code changes
585 between the authors.
586 </para>
587 <para>
588 A patch is both readable by humans and (as it is specially formatted) by
589 some dedicated tools.
590 </para>
591 <para>
592 Here is a small example of a patch for <filename>file.h</filename> that
593 makes the second argument in <function>cf_continue_tail()</function>
594 <type>volatile</type>. It was created using <command>svn diff</command>,
595 described below:
596 <programlisting>
597 <![CDATA[
598 Index: file.h
599 ===================================================================
600 --- file.h (revision 21134)
601 +++ file.h (revision 22401)
602 @@ -142,7 +142,7 @@
603 * @param err the error code, if an error had occurred
604 * @return one of cf_read_status_t
605 */
606 -cf_read_status_t cf_continue_tail(capture_file *cf, int to_read, int *err);
607 +cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
609 /**
610 * Finish reading from "end" of a capture file.
611 ]]>
612 </programlisting>
613 The plus sign at the start of a line indicates an added line, a minus
614 sign indicates a deleted line compared to the original sources.
615 </para>
616 <para>
617 We prefer to use so called "unified" diff files in Wireshark development,
618 three unchanged lines before and after the actual changed parts are
619 included. This makes it much easier for a merge/patch tool to find
620 the right place(s) to change in the existing sources.
621 </para>
622 </section>
625 <section id="ChSrcGeneratePatch">
626 <title>Generate a patch</title>
627 <para>
628 There are several ways to generate patches. The preferred way is to
629 generate them from an updated Subversion tree, since it avoids
630 unnecessary integration work.
631 </para>
633 <section id="ChSrcSVNDiff">
634 <title>Using the svn command-line client</title>
635 <para>
636 <userinput>svn diff [changed_files] > svn.diff</userinput>
637 </para>
638 <para>
639 Use the command line svn client to generate a patch in the required format
640 from the changes you've made to your working copy. If you leave out the
641 name of the changed file the svn client searches for all changes in the
642 working copy and usually produces a patch containing more than just the
643 change you want to send. Therefore you should always check the produced
644 patch file.
645 </para>
646 <para>
647 If you've added a new file, e.g.
648 <filename>packet-myprotocol.c</filename>, you can use <command>svn
649 add</command> to add it to your local tree before generating the patch.
650 Similarly, you can use <command>svn rm</command> for files that should
651 be removed.
652 </para>
653 </section>
655 <section id="ChSrcSVNGUIDiff">
656 <title>Using the diff feature of the GUI Subversion clients</title>
657 <para>
658 Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...)
659 have a built-in "diff" feature.
660 </para>
661 <para>
662 If you use TortoiseSVN:
663 </para>
664 <para>
665 TortoiseSVN (to be precise Subversion) keeps track of the files you have
666 changed in the directories it controls, and will generate for you a
667 unified diff file compiling the differences. To do so - after updating
668 your sources from the SVN repository if needed - just right-click on the
669 highest level directory and choose "TortoiseSVN" -> "Create patch...".
670 You will be asked for a name and then the diff file will be created. The
671 names of the files in the patch will be relative to the directory you have
672 right-clicked on, so it will need to be applied on that level too.
673 </para>
674 <para>
675 When you create the diff file, it will include any difference TortoiseSVN
676 finds in files in and under the directory you have right-clicked on, and
677 nothing else. This means that changes you might have made for your
678 specific configuration - like modifying <filename>config.nmake</filename>
679 so that it uses
680 your lib directory - will also be included, and you will need to remove
681 these lines from the diff file. It also means that only changes will be
682 recorded, i.e. if you have created new files -say, a new
683 <filename>packet-xxx.c</filename> for a
684 new protocol dissector- it will not be included in the diff, you need to
685 add it separately. And, of course, if you have been working separately in
686 two different patches, the .diff file will include both topics, which is
687 probably not a good idea.
688 </para>
689 </section>
691 <section id="ChSrcDiff">
692 <title>Using the diff tool</title>
693 <para>
694 A diff file is generated, by comparing two files or directories between
695 your own working copy and the "official" source tree. So to be able to
696 do a diff, you should
697 have two source trees on your computer, one with your working copy
698 (containing your changes), and one with the "official" source tree
699 (hopefully the latest SVN files) from &WiresharkWebSite;.
700 </para>
701 <para>
702 If you have only changed a single file, you could type something like
703 this:
704 </para>
705 <para>
706 <userinput>diff -r -u --strip-trailing-cr svn-file.c work-file.c > foo.diff</userinput>
707 </para>
708 <para>
709 To get a diff file for your complete directory (including
710 subdirectories), you could type something like this:
711 </para>
712 <para>
713 <userinput>diff -N -r -u --strip-trailing-cr ./svn-dir ./working-dir > foo.diff</userinput>
714 </para>
715 <para>
716 It's a good idea to do a <userinput>make distclean</userinput> before the
717 actual diff call, as this will remove a lot
718 of temporary files which might be otherwise included in the diff. After
719 doing the diff, you should edit the <filename>foo.diff</filename>
720 file and remove unnecessary things, like your private changes to the
721 <filename>config.nmake</filename> file.
722 </para>
723 <para>
724 <table frame='all'><title>Some useful diff options</title>
725 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
726 <colspec colname='c1'/>
727 <colspec colname='c2'/>
728 <thead>
729 <row>
730 <entry>Option</entry>
731 <entry>Purpose</entry>
732 </row>
733 </thead>
734 <tbody>
735 <row>
736 <entry>-N</entry>
737 <entry>Add new files when used in conjunction with -r.</entry>
738 </row>
739 <row>
740 <entry>-r</entry>
741 <entry>Recursively compare any subdirectories found.</entry>
742 </row>
743 <row>
744 <entry>-u</entry>
745 <entry>Output unified context.</entry>
746 </row>
747 <row>
748 <entry>--strip-trailing-cr</entry>
749 <entry>Strip trailing carriage return on input. This is useful for Win32
750 </entry>
751 </row>
752 <row>
753 <entry>-x PAT</entry>
754 <entry>Exclude files that match PAT.
755 This could be something like -x *.obj to exclude all win32 object files.
756 </entry>
757 </row>
758 </tbody>
759 </tgroup>
760 </table>
761 </para>
762 <para>
763 The diff tool has a lot options; they can be listed with:
764 </para>
765 <para>
766 <userinput>diff --help</userinput>
767 </para>
768 </section>
770 </section>
772 <section id="ChSrcGoodPatch">
773 <title>Some tips for a good patch</title>
774 <para>
775 Some tips that will make the merging of your changes into the
776 SVN tree much more likely (and you want exactly that, don't you :-):
777 <itemizedlist>
778 <listitem><para>
779 <command>Use the latest SVN sources, or alike.</command>
780 It's a good idea to work with the same sources that are used by the
781 other developer's, this makes it usually much easier to apply your
782 patch. For information about the different ways to get the sources,
783 see <xref linkend="ChSrcObtain"/>.
784 </para></listitem>
785 <listitem><para>
786 <command>Update your SVN sources just before making a patch.
787 </command> For the same reasons as the previous point.
788 </para></listitem>
789 <listitem><para>
790 <command>Do a "make clean" before generating the patch.</command>
791 This removes a lot of unneeded intermediate files (like object files)
792 which can confuse the diff tool generating a lot of unneeded stuff which
793 you have to remove by hand from the patch again.
794 </para></listitem>
795 <listitem><para>
796 <command>Find a good descriptive filename for your patch.</command>
797 Think a moment to find a proper name for your patch file. Often a
798 filename like <filename>wireshark.diff</filename> is used, which isn't
799 really helpful if keeping several of these files and find the right
800 one later. For example: If you want to commit changes to the datatypes
801 of dissector foo, a good filename might be:
802 <filename>packet-foo-datatypes.diff</filename>.
803 </para></listitem>
804 <listitem><para>
805 <command>Don't put unrelated things into one large patch.
806 </command> A few smaller patches are usually easier to apply (but also
807 don't put every changed line into a separate patch :-).
808 </para></listitem>
809 <listitem><para>
810 <command>Remove any parts of the patch not related to the
811 changes you want to submit.</command> You can use a text editor for this.
812 A common example for win32 developers are the differences in your private
813 <filename>config.nmake</filename> file.
814 </para></listitem>
815 </itemizedlist>
816 In general: making it easier to understand and apply your patch by one
817 of the maintainers will make it much more likely (and faster) that it
818 will actually be applied.
819 </para>
820 <para>
821 Please remember: you don't pay the person "on the
822 other side of the mail" for his/her effort applying your patch!
823 </para>
824 </section>
826 <section id="ChSrcCodeRequirements">
827 <title>Code Requirements</title>
828 <para>
829 The core maintainers have done a lot of work fixing bugs and making code
830 compile on the various platforms Wireshark supports.
831 </para>
832 <para>
833 To ensure Wireshark's source code quality, and to reduce the workload of
834 the core maintainers, there are some things you should
835 think about <command>before</command> submitting a patch.
836 <warning><title>Warning!</title>
837 <para>
838 <command>Ignoring the code requirements will make it very likely
839 that your patch will be rejected!</command>
840 </para>
841 </warning>
842 <itemizedlist>
843 <listitem><para>
844 <command>Follow the Wireshark source code style guide.</command>
845 Just because something compiles on your platform, that doesn't
846 mean it'll compile on all of the other platforms for which Wireshark is
847 built.
848 Wireshark runs on many platforms, and can be compiled with a number of
849 different compilers. See <xref linkend="ChCodeStyle"/> for details.
850 </para>
851 </listitem>
852 <listitem><para>
853 <command>Submit dissectors as built-in whenever possible.</command>
854 Developing a new dissector as a plugin is a good idea because compiling is
855 quicker, but it's best to convert dissectors to the built-in style before
856 submitting for checkin. This reduces the number of files that must be installed
857 with Wireshark and ensures your dissector will be available on all platforms.
858 </para><para>
859 This is no hard-n-fast rule though. Many dissectors are straightforward so they
860 can easily be put into 'the big pile', while some are ASN.1 based which takes a
861 different approach, and some multiple sourcefile dissectors are more suitable to
862 be placed separate as plugin.
863 </para>
864 </listitem>
865 <listitem><para>
866 <command>Verify that your dissector code does not use prohibited or deprecated APIs</command>
867 This can be done as follows:
868 </para>
869 <para>
870 <userinput>perl <wireshark_root>/tools/checkAPIs.pl <source-filename(s)></userinput>
871 </para>
872 </listitem>
873 <listitem><para>
874 <command>Fuzz test your changes!</command> Fuzz testing is a very
875 effective way to automatically find a lot of dissector related bugs.
876 You'll take a capture file containing packets affecting your dissector
877 and the fuzz test will randomly change bytes in this file, so that unusual
878 code paths in your dissector are checked. There are tools available to
879 automatically do this on any number of input files, see:
880 <ulink url="&WiresharkWikiSite;/FuzzTesting"/> for details.
881 </para>
882 </listitem>
883 </itemizedlist>
884 </para>
885 </section>
887 <section id="ChSrcSend">
888 <title>Sending your patch for inclusion</title>
889 <para>
890 After generating a patch of your changes, you might want to have your
891 changes included into the SVN repository.
892 </para>
893 <para>
894 To submit a patch, open a new ticket in the Wireshark bug database at <ulink
895 url="&WiresharkBugsSite;/bugzilla/enter_bug.cgi?product=Wireshark"/>.
896 You must first create a bug, then attach your patch or patches.
897 <itemizedlist>
898 <listitem><para>
899 Set the Product, Priority, and Severity as needed.
900 </para></listitem>
901 <listitem><para>
902 Add a Summary and Description, and create a bug using the
903 <guibutton>Commit</guibutton> button. If your code has passed fuzz
904 testing, please say so in the description.
905 </para></listitem>
906 <listitem><para>
907 Once the bug has been created, select <guibutton>Create a New Attachment</guibutton>
908 and upload your patch or patches. Set the <command>review_for_checkin</command>
909 flag to <command>?</command>. If you skip this step, your patch won't show up in the
910 patch request queue.
911 </para></listitem>
912 <listitem><para>
913 If possible and applicable, attach a capture file that demonstrates
914 your new feature or protocol.
915 </para></listitem>
916 <listitem><para>
917 Don't set the bug's status to ASSIGNED and don't assign the bug to
918 yourself--if you do the latter, the core developers won't see the
919 updates made to the bug.
920 </para></listitem>
921 </itemizedlist>
922 </para>
923 <!--
924 <tip><title>Tip!</title>
925 <para>
926 Setting the <command>review_for_checkin</command> is important.
927 Without it, your patch won't show up in the <ulink url="http://bugs.wireshark.org/bugzilla/request.cgi?action=queue&requester=&product=&type=review_for_checkin&requestee=&component=&group=type">pending
928 patch request queue</ulink>.
929 </para>
930 </tip>
931 -->
932 <para>
933 You might get one of the following responses to your patch request:
934 <itemizedlist>
935 <listitem><para>
936 Your patch is checked into the SVN repository. Congratulations!
937 </para></listitem>
938 <listitem><para>
939 You are asked to provide additional information, capture files, or
940 other material. If you haven't fuzzed your code, you may be asked
941 to do so.
942 </para></listitem>
943 <listitem><para>
944 Your patch is rejected. You should get a response with the reason
945 for rejection. Common reasons include not following the style
946 guide, buggy or insecure code, and code that won't compile on other
947 platforms. In each case you'll have to fix each problem and upload
948 another patch.
949 </para></listitem>
950 <listitem><para>
951 You don't get any response to your patch.
952 Possible reason: Don't worry, if your patch is in the bug tracker, it
953 won't get lost. But it may be that all the core developers are busy
954 (e.g., with their day jobs or family or...) and haven't had time to
955 look at your patch. If you're concerned, feel free to add a comment
956 to the patch or send an email to the developer's list asking for
957 status. But please be patient: most if not all of us do this in our
958 "spare" time.
959 </para></listitem>
960 </itemizedlist>
961 </para>
962 </section>
963 </section>
965 <section id="ChSrcPatchApply">
966 <title>Apply a patch from someone else</title>
967 <para>
968 Sometimes you need to apply a patch to your private source tree. Maybe
969 because you want to try a patch from someone on the developer mailing
970 list, or you want to check your own patch before submitting.
971 </para>
972 <warning><title>Warning!</title>
973 <para>
974 If you have problems applying a patch, make sure the line endings (CR/NL)
975 of the patch and your source files match.
976 </para>
977 </warning>
978 <section id="ChSrcPatchUse">
979 <title>Using patch</title>
980 <para>
981 Given the file <filename>new.diff</filename> containing a unified diff,
982 the right way to call the patch tool depends on what the pathnames in
983 <filename>new.diff</filename> look like.
984 If they're relative to the top-level source directory - for example, if a
985 patch to <filename>prefs.c</filename> just has <filename>prefs.c</filename>
986 as the file name - you'd run it as:
987 </para>
988 <para>
989 <userinput>patch -p0 <new.diff</userinput>
990 </para>
991 <para>
992 If they're relative to a higher-level directory, you'd replace 0 with the
993 number of higher-level directories in the path, e.g. if the names are
994 <filename>wireshark.orig/prefs.c</filename> and
995 <filename>wireshark.mine/prefs.c</filename>, you'd run it with:
996 </para>
997 <para>
998 <userinput>patch -p1 <new.diff</userinput>
999 </para>
1000 <para>
1001 If they're relative to a <literal>subdirectory</literal> of the top-level
1002 directory, you'd run <command>patch</command> in <literal>that</literal>
1003 directory and run it with <parameter>-p0</parameter>.
1004 </para>
1005 <para>
1006 If you run it without <parameter>-p</parameter> at all, the patch tool
1007 flattens path names, so that if you
1008 have a patch file with patches to <filename>Makefile.am</filename> and
1009 <filename>wiretap/Makefile.am</filename>,
1010 it'll try to apply the first patch to the top-level
1011 <filename>Makefile.am</filename> and then apply the
1012 <filename>wiretap/Makefile.am</filename> patch to the top-level
1013 <filename>Makefile.am</filename> as well.
1014 </para>
1015 <para>
1016 At which position in the filesystem should the patch tool be called?
1017 </para>
1018 <para>
1019 If the pathnames are relative to the top-level source directory, or to a
1020 directory above that directory, you'd run it in the top-level source
1021 directory.
1022 </para>
1023 <para>
1024 If they're relative to a <literal>subdirectory</literal> - for example,
1025 if somebody did a patch to "packet-ip.c" and ran "diff" or "svn diff" in
1026 the "epan/dissectors" directory - you'd run it in that subdirectory.
1027 It is preferred that people <literal>NOT</literal> submit patches like
1028 that - especially if they're only patching files that exist in multiple
1029 directories, such as <filename>Makefile.am</filename>.
1030 </para>
1031 </section>
1032 </section>
1034 <section id="ChSrcAdd">
1035 <title>Add a new file to the Subversion repository</title>
1036 <para>
1037 The "usual" way to commit new files is described in <xref
1038 linkend="ChSrcContribute"/>. However, the following might be of
1039 interest for the "normal" developer as well.
1040 </para>
1041 <note><title>Note!</title>
1042 <para>
1043 This action is only possible/allowed by the Wireshark core developers who
1044 have write access to the Subversion repository. It is put in here to have
1045 all information in one place.
1046 </para>
1047 </note>
1048 <para>
1049 If you (as a core developer) need to add a file to the SVN repository,
1050 then you need to perform the following steps:
1051 <orderedlist>
1052 <listitem>
1053 <para>
1054 Verify that that file is complete (has Wireshark boilerplate, $Id$, etc).
1055 </para>
1056 </listitem>
1057 <listitem>
1058 <para>
1059 Add the new file(s) to the repository:
1060 </para>
1061 <para>
1062 <prompt>$</prompt>
1063 <userinput>svn add new_file</userinput>
1064 </para>
1065 </listitem>
1066 <listitem>
1067 <para>
1068 Set the line ending property to "native" for the new file(s):
1069 </para>
1070 <para>
1071 <prompt>$</prompt>
1072 <userinput>svn propset svn:eol-style native new_file</userinput>
1073 </para>
1074 </listitem>
1075 <listitem>
1076 <para>
1077 Set version keyword to "Id" for the new file(s):
1078 </para>
1079 <para>
1080 <prompt>$</prompt>
1081 <userinput>svn propset svn:keywords Id new_file</userinput>
1082 </para>
1083 </listitem>
1084 <listitem>
1085 <para>
1086 Commit your changes, including the added file(s).
1087 </para>
1088 <para>
1089 <prompt>$</prompt>
1090 <userinput>svn commit new_file other_files_you_modified</userinput>
1091 </para>
1092 </listitem>
1093 </orderedlist>
1094 Don't forget a brief description of the reason for the commit so other
1095 developers don't need to read the diff in order to know what has changed.
1096 </para>
1097 </section>
1098 <section id="ChSrcBinary">
1099 <title>Binary packaging</title>
1100 <para>
1101 Delivering binary packages makes it much easier for the end-users to
1102 install Wireshark on their target system. This section will explain how
1103 the binary packages are made.
1104 </para>
1106 <section id="ChSrcDeb">
1107 <title>Debian: .deb packages</title>
1108 <para>
1109 The Debian Package is built using dpkg-buildpackage, based on information
1110 found in the source tree under <filename>debian</filename>. See
1111 <ulink url="http://www.debian-administration.org/articles/336"/> for a
1112 more in-depth discussion of the build process.
1113 </para>
1114 <para>
1115 In the wireshark directory, type:
1116 </para>
1117 <para>
1118 <prompt>$</prompt> <userinput>make debian-package</userinput>
1119 </para>
1120 <para>
1121 to build the Debian Package.
1122 </para>
1123 </section>
1125 <section id="ChSrcRpm">
1126 <title>Red Hat: .rpm packages</title>
1127 <para>
1128 The RPM is built using rpmbuild (http://www.rpm.org/), which comes as standard on many flavours of Linux, including
1129 Red Hat and Fedora. The process creates a clean build environment in <filename>packaging/rpm/BUILD</filename> every
1130 time the RPM is built. The settings controlling the build are in <filename>packaging/rpm/SPECS/wireshark.spec.in</filename>.
1131 After editing the settings in this file, <filename>./configure</filename> must be run again in the wireshark directory to
1132 generate the actual specification script.
1133 </para>
1134 <warning><title>Warning!</title><para>
1135 The SPEC file contains settings for the <filename>configure</filename> used to set the RPM build environment. These are
1136 completely independent of any settings passed to the usual Wireshark <filename>./configure</filename>. The exception to
1137 this rule is that the prefix given to <filename>configure</filename> (<userinput>--prefix</userinput>) is passed to
1138 rpmbuild.</para></warning>
1139 <para>
1140 In the wireshark directory, type:
1141 </para>
1142 <para>
1143 <prompt>$</prompt> <userinput>make rpm-package</userinput>
1144 </para>
1145 <para>
1146 to build the RPM and source RPM. Once it is done, there will be a message stating where the built RPM can be found.
1147 </para>
1148 <tip><title>Tip!</title>
1149 <para>Because this does a clean build, as well as constructing the package, this can take quite a long time.</para>
1150 </tip>
1151 <tip><title>Tip!</title>
1152 <para>Building the RPM requires building a source distribution which itself requires the Qt development tools
1153 <filename>uic</filename> and <filename>moc</filename>. These can usually be obtained by installing the
1154 <filename>qt-devel</filename> package.</para>
1155 </tip>
1156 </section>
1158 <section id="ChSrcOSX">
1159 <title>MAC OS X: .dmg packages</title>
1160 <para>
1161 The MAC OS X Package is built using OS X packaging tools, based on information
1162 found in the source tree under <filename>packaging/macosx</filename>.
1163 </para>
1164 <para>
1165 In the wireshark directory, type:
1166 </para>
1167 <para>
1168 <prompt>$</prompt> <userinput>make osx-package</userinput>
1169 </para>
1170 <para>
1171 to build the MAC OS X Package.
1172 </para>
1173 </section>
1175 <section id="ChSrcNSIS">
1176 <title>Win32: NSIS .exe installer</title>
1177 <para>
1178 The "Nullsoft Install System" is a free installer generator for Win32
1179 based systems; instructions how to install it can be found in <xref
1180 linkend="ChToolsNSIS"/>.
1181 NSIS is script based, you will find the Wireshark installer
1182 generation script at: <filename>packaging/nsis/wireshark.nsi</filename>.
1183 </para>
1184 <para>
1185 You will probably have to modify the MAKENSIS setting in the
1186 <filename>config.nmake</filename> file to specify where the NSIS binaries
1187 are installed.
1188 </para>
1189 <para>
1190 In the wireshark directory, type:
1191 </para>
1192 <para>
1193 <prompt>></prompt> <userinput>nmake -f makefile.nmake packaging</userinput>
1194 </para>
1195 <para>
1196 to build the installer.
1197 </para>
1198 <tip><title>Tip!</title>
1199 <para>
1200 Please be patient while the compression is
1201 done, it will take some time (a few minutes!) even on fast machines.
1202 </para>
1203 </tip>
1204 <para>
1205 If everything went well, you will now find something like:
1206 <filename>wireshark-setup-&WiresharkCurrentVersion;.exe</filename> in
1207 the <filename>packaging/nsis</filename> directory.
1208 </para>
1209 </section>
1211 </section>
1213 </chapter>
1214 <!-- End of WSDG Chapter Sources -->