1 <!-- WSDG Chapter Sources -->
4 <chapter id="ChapterSources">
5 <title>Work with the Wireshark sources</title>
7 <section id="ChSrcIntro">
8 <title>Introduction</title>
10 This chapter will explain how to work with the Wireshark source code.
11 It will show you how to:
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"/>.
32 <section id="ChSrcSVNServer">
33 <title>The Wireshark Subversion repository</title>
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.
40 To qoute the Subversion book about "What is Subversion?":
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".
52 <tip><title>Tip!</title>
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.
60 Using Wireshark's Subversion repository you can:
63 keep your private sources uptodate with very little effort
66 get a mail notification if someone changes the latest sources
69 get the source files from any previous release (or any other point in time)
72 have a quick look at the sources using a web interface
75 see which person changed a specific piece of code
78 ... and a lot more things related to the history of the Wireshark source
84 The way Wireshark uses Subversion, it can be parted into a client and a
85 server part. Thanks to Gerald Combs (the maintainer of the Subversion
86 server), no user usually has to deal with the
87 Subversion server. You will only need a Subversion client, which is
88 available as a command-line tool for many different platforms. GUI based
89 tools also becoming more and more available these days.
92 For further reference about Subversion, have a look at the homepage of the
93 Subversion project: <ulink url="http://subversion.tigris.org/"/>. There
94 is a good and free book about it available at: <ulink
95 url="http://svnbook.red-bean.com/"/>.
98 Please note that the anonymous Subversion repository is separate from
99 the main repository. It may take several minutes for committed changes to
100 appear in the anonymous repository. XXX - be more specific here.
102 <tip><title>Tip!</title>
104 As the Wireshark project has switched from CVS (Concurrent versioning
105 system) to Subversion some time ago, you may still find old references to
106 CVS in the Wireshark documentation and source files.
111 <section id="ChSrcWebInterface">
112 <title>The web interface to the Subversion repository</title>
114 If you need a quick look at the Wireshark source code,
115 you will only need a Web browser.
118 A <command>simple view</command> on the latest developer version can be
122 <ulink url="http://anonsvn.wireshark.org/wireshark/trunk/"/>.
125 A <command>comprehensive view</command> of all source versions
126 (e.g. including the capability to show differences between versions)
130 <ulink url="http://anonsvn.wireshark.org/viewvc/viewvc.cgi/"/>.
133 Of special interest might be the subdirectories:
136 trunk - the very latest source files
139 releases - the source files of all released versions
145 <section id="ChSrcObtain">
146 <title>Obtain the Wireshark sources</title>
148 There are several ways to obtain the sources from Wireshark's Subversion
151 <tip><title>Tip!</title>
153 Anonymous Subversion access can make your life much easier, compared to
154 update your source tree by using any of the zip file methods mentioned
156 Subversion handles merging of changes into your personal source tree in a
157 very comfortable and quick way. So you can update your source tree several
158 times a day without much effort.
161 <note><title>Note!</title>
163 The following ways to retrieve the Wireshark sources are sorted in
165 actuality. If you plan to commit changes you've made to the sources,
166 it's a good idea to keep your private source tree as actual as possible.
170 The age mentioned in the following sections will indicate, how old the
171 most recent change in that sources will be.
174 <section id="ChSrcAnon">
175 <title>Anonymous Subversion access</title>
177 Recommended for development purposes.
183 You can use a Subversion client to download the source code from
184 Wireshark's anonymous Subversion repository. The URL for the repository
186 <ulink url="http://anonsvn.wireshark.org/wireshark/trunk/"/>.
189 See <xref linkend="ChToolsSubversion"/> how to install a Subversion client.
192 For example, to check out using the command-line Subversion client, you
197 <userinput>svn checkout http://anonsvn.wireshark.org/wireshark/trunk wireshark</userinput>
200 The checkout has to be only done once. This will copy all the sources of
201 the latest version (including directories) from the server to your machine.
202 This will take some time, depending on the speed of your internet line.
206 <section id="ChSrcSVNWeb">
207 <title>Anonymous Subversion web interface</title>
209 Recommended for development purposes, if direct Subversion access isn't
210 possible (e.g. because of a restrictive firewall).
213 Age: a few minutes (same as anonymous Subversion access).
216 The entire source tree of the Subversion repository is available via a
218 <ulink url="http://anonsvn.wireshark.org/viewvc/viewvc.cgi/"/>.
220 each revision of a particular file, as well as diffs between different
221 revisions. You can also download individual files or entire directories.
225 <section id="ChSrcBuildbot">
226 <title>Buildbot Snapshots</title>
228 Recommended for development purposes, if direct Subversion access isn't
229 possible (e.g. because of a restrictive firewall).
232 Age: a few minutes (a bit older than the anonymous Subversion access).
235 The buildbot server will automatically start to generate a snapshot of
236 Wireshark's sourcetree after a source code change committed.
237 These snapshots can be found at: <ulink
238 url="http://www.wireshark.org/distribution/buildbot-builds/source/"/>.
241 If anonymous Subversion access isn't possible, e.g. if the connection to
242 the server isn't possible because of a corporate firewall, the sources
243 can be obtained by downloading this buildbot snapshots. However, if you are
244 going to maintain your sources in parallel to the "official" sources
245 for some time, it's recommended to use the anonymous Subversion access if
246 possible (believe it, it will save you a lot of time).
251 <section id="ChSrcReleased">
252 <title>Released sources</title>
254 Recommended for productive purposes.
257 Age: from days to weeks.
260 The officially released source files can be found at: <ulink
261 url="http://www.wireshark.org/download.html"/>.
262 You should use these sources if you want to build Wireshark on your
263 platform for productive use.
266 The differences between the released sources and the sources stored at
267 the Subversion repository are keep on growing until the next release is
268 done (at the release time, the released and latest Subversion repository
269 versions are then identical again :-).
275 <section id="ChSrcUpdating">
276 <title>Update the Wireshark sources</title>
278 After you obtained the Wireshark sources for the first time, you
279 might want to keep them in sync with the sources at the Subversion
283 <section id="ChSrcAnonUpdate">
284 <title>... with Anonymous Subversion access</title>
286 After the first time checkout is done, updating your
287 sources is simply done by typing (in the Wireshark source dir):
291 <userinput>svn update</userinput>
294 This will only take a few seconds, even on a slow internet line. It will
295 replace old file versions by new ones. If you and someone else have
296 changed the same file since the last update, Subversion will try to merge
297 the changes into your private file (this is working remarkably well).
301 <section id="ChSrcZipUpdate">
302 <title>... from zip files</title>
304 Independant of the way you retrieve the zip file of the Wireshark sources
305 (as <xref linkend="ChSrcObtain"/> is providing several ways), the way to
306 bring the changes from the official sources into your personal source tree
310 First of all, you will download the new zip file of the official sources
311 the way you did it the first time.
314 If you didn't changed anything in the sources, you could simply throw
315 away your old sources and reinstall everything just like the first time.
316 But be sure, that you really didn't changed anything. It might be a good
317 idea to simply rename the "old" dir to have it around, just in case you
318 remember later that you really did changed something before.
321 Well, if you did change something in your source tree, you have to merge
323 since the last update into your source tree. You will install the content
324 of the zip file into a new directory and use a good merge tool (e.g.
325 <ulink url="http://winmerge.sourceforge.net/"/> for Win32) to bring
326 your personal source tree in sync with the official sources again.
332 <section id="ChSrcBuildFirstTime">
333 <title>Build Wireshark for the first time</title>
335 The sources contains several documentation files, it's a good idea to
336 look at these files first.
339 So after obtaining the sources, tools and libraries, the
340 first place to look at is <filename>doc/README.developer</filename>,
341 here you will get the latest infos for Wireshark development for all
344 <tip><title>Tip!</title>
346 It is a very good idea, to first test your complete build environment
347 (including running and debugging Wireshark) before doing any changes
348 to the source code (unless otherwise noted).
352 The following steps for the first time generation differs on the two
359 Run the autogen.sh script at the top-level wireshark directory to configure
360 your build directory.
368 If you need to build with a GTK 1.x version, you have to use:
370 ./configure --disable-gtk2
372 instead of just ./configure.
377 <title>Win32 native</title>
379 The place to look at is <filename>doc/README.win32</filename>,
380 you will get the latest infos for generation on the win32
384 The next thing to do will be editing the file
385 <filename>config.nmake</filename> to reflect your configuration.
386 The settings in this file are well documented, so please have a look at
390 Then you should cleanup any intermediate files, which are shipped for
391 convenience of Unix users, by typing inside the command line (cmd.exe):
394 <prompt>></prompt> <userinput>nmake -f Makefile.nmake distclean</userinput>
397 After doing this, typing inside the command line (cmd.exe):
400 <prompt>></prompt> <userinput>nmake -f Makefile.nmake all</userinput>
403 will start the whole Wireshark build process.
406 After the build process successfully finished, you should find an
407 <filename>wireshark.exe</filename> and some other files
408 in the root directory.
414 <section id="ChSrcRunFirstTime">
415 <title>Run generated Wireshark for the first time</title>
416 <tip><title>Tip!</title>
418 An already installed Wireshark may interfere with your newly generated
419 version in various ways. If you have any problems getting your Wireshark
420 running the first time, it might be a good idea to remove the previously
421 installed version first.
425 XXX - add more info here.
429 <section id="ChSrcDebug">
430 <title>Debug your generated Wireshark</title>
432 See the above info on running Wireshark.
435 XXX - add more info here.
438 <section id="ChSrcWin32Debug">
439 <title>Win32 native</title>
441 XXX - add more info here.
446 <section id="ChSrcChange">
447 <title>Make changes to the Wireshark sources</title>
449 As the Wireshark developers working on many different platforms, a lot of
450 editors are used to develop Wireshark (emacs, vi, Microsoft Visual Studio
451 and many many others). There's no "standard" or "default" development
455 There are several reasons why you might want to change the Wireshark
458 <listitem><para>add your own new dissector</para></listitem>
459 <listitem><para>change/extend an existing dissector</para></listitem>
460 <listitem><para>fix a bug</para></listitem>
461 <listitem><para>implement a new glorious feature :-)</para></listitem>
463 The internal structure of the Wireshark sources will be described in
464 <xref linkend="PartDevelopment"/>.
466 <tip><title>Tip!</title>
468 <command>Ask the developer mailing list before you really start a new
469 development task.</command>
470 If you have an idea what you want to add/change, it's a good idea to
471 contact the developer mailing list
472 (see <xref linkend="ChIntroMailingLists"/>)
473 and explain your idea. Someone else might already be working on the same
474 topic, so double effort can be reduced, or can give you some tips what
475 should be thought about too (like side effects that are sometimes very
481 <section id="ChSrcCommit">
482 <title>Commit changed sources</title>
484 If you have finished changing the Wireshark sources to suit your needs,
485 you might want to contribute your changes back to the Wireshark SVN
489 You gain the following benefits by contributing your improvements back to
493 Other people who find your contributions useful will appreciate
494 them, and you will know that you have helped people in the same way
495 that the developers of Wireshark have helped people
498 The developers of Wireshark might improve your changes even more, as
499 there's always room for improvements. Or they may implement some advanced
500 things on top of your code, which can be useful for yourself too.
503 The maintainers and developers of Wireshark will maintain your code as
504 well, fixing it when API changes or other changes are made, and generally
505 keeping it in tune with what is happening with Wireshark. So if Wireshark is
506 updated (which is done often), you can get a new Wireshark version from
507 the website and your changes will already be included without any effort
508 for you. The maintainers and developers of Wireshark will maintain your
509 code as well, fixing it when API changes or other changes are made, and
510 generally keeping it in tune with what is happening with Wireshark.
513 There's no direct way to commit changes to the SVN repository. Only a few
514 people are authorised to actually
515 make changes to the source code (check-in changed files). If you want
516 to submit your changes, you should make a diff file (a patch) and send
518 the developer mailing list.
521 <section id="ChSrcDiffWhat">
522 <title>What is a diff file (a patch)?</title>
524 A diff file is a plain text file containing the differences between a
525 pair of files (or a multiple of such file pairs).
526 <tip><title>Tip!</title>
527 <para>A diff file is often also called a patch,
528 as it can be used to patch an existing source file or tree with changes
534 The Wireshark community is using patches to transfer source code changes
538 A patch is both readable by humans and (as it is specially formatted) by
539 some dedicated tools.
542 Here is a small example of a patch file (XXX - generate a better example):
545 diff -ur ../wireshark-0.99.0/epan/dissectors/packet-dcerpc.c ./epan/dissectors/packet-dcerpc.c
546 --- ../wireshark-0.99.0/epan/dissectors/packet-dcerpc.c 2005-08-12 15:42:26.000000000 -0700
547 +++ ./epan/dissectors/packet-dcerpc.c 2005-08-19 18:48:32.000000000 -0700
549 /* we need to keep track of what transport were used, ie what handle we came
550 * in through so we know what kind of pinfo->private_data was passed to us.
552 +/* Value of -1 is reserved for "not DCE packet" in packet_info.dcetransporttype. */
553 #define DCE_TRANSPORT_UNKNOWN 0
554 #define DCE_CN_TRANSPORT_SMBPIPE 1
558 The plus sign at the start of a line indicates an added line, a minus
559 sign indicates a deleted line compared to the original sources.
562 As we always use so called "unified" diff files in Wireshark development,
563 three unchanged lines before and after the actual changed parts are
564 included. This will make it much easier for a merge/patch tool to find
565 the right place(s) to change in the existing sources.
570 <section id="ChSrcGeneratePatch">
571 <title>Generate a patch</title>
573 There are several ways to generate such a patch.
576 <section id="ChSrcSVNDiff">
577 <title>Using the svn command-line client</title>
579 <userinput>svn diff [changed_files] > svn.diff</userinput>
582 XXX - add more details
586 <section id="ChSrcSVNGUIDiff">
587 <title>Using the diff feature of the GUI Subversion clients</title>
589 Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...)
590 have a built-in "diff" feature.
593 If you use TortoiseSVN:
596 TortoiseSVN (to be precise subversion) keeps track of the files you have
597 changed in the directories it controls, and will generate for you a
598 unified diff file compiling the differences. To do so - after updating
599 your sources from the SVN repository if needed - just right-click on the
600 highest level directory and choose "TortoiseSVN" -> "Create patch...".
601 You will be asked for a name and then the diff file will be created. The
602 names of the files in the patch will be relative to the directory you have
603 right-clicked on, so it will need to be applied on that level too.
606 When you create the diff file, it will include any difference TortoiseSVN
607 finds in files in and under the directory you have right-clicked on, and
608 nothing else. This means that changes you might have made for your
609 specific configuration - like modifying "config.nmake" so that it uses
610 your lib directory - will also be included, and you will need to remove
611 these lines from the diff file. It also means that only changes will be
612 recorded, i.e. if you have created new files -say, a new packet-xxx for a
613 new protocol dissector- it will not be included in the diff, you need to
614 add it separately. And, of course, if you have been working separately in
615 two different patches, the .diff file will include both topics, which is
616 probably not a good idea.
620 <section id="ChSrcDiff">
621 <title>Using the diff tool</title>
623 A diff file is generated, by comparing two files or directories between
624 your own working copy and the "official" source tree. So to be able to
625 do a diff, you should
626 have two source trees on your computer, one with your working copy
627 (containing your changes), and one with the "official" source tree
628 (hopefully the latest SVN files) from www.wireshark.org.
631 If you have only changed a single file, you could type something like
635 <userinput>diff -r -u --strip-trailing-cr svn-file.c work-file.c > foo.diff</userinput>
638 To get a diff file for your complete directory (including
639 subdirectories), you could type something like this:
642 <userinput>diff -r -u --strip-trailing-cr ./svn-dir ./working-dir > foo.diff</userinput>
645 It's a good idea to do a <userinput>make distclean</userinput> before the
646 actual diff call, as this will remove a lot
647 of temporary files which might be otherwise included in the diff. After
648 doing the diff, you should edit the <filename>foo.diff</filename>
649 file and remove unnecessary things, like your private changes to the
650 <filename>config.nmake</filename> file.
653 <table frame='all'><title>Some useful diff options</title>
654 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
655 <colspec colname='c1'/>
656 <colspec colname='c2'/>
659 <entry>Option</entry>
660 <entry>Purpose</entry>
666 <entry>Recursively compare any subdirectories found.</entry>
670 <entry>Output unified context.</entry>
673 <entry>--strip-trailing-cr</entry>
674 <entry>Strip trailing carriage return on input. This is useful for Win32
678 <entry>-x PAT</entry>
679 <entry>Exclude files that match PAT.
680 This could be something like -x *.obj to exclude all win32 object files.
688 The diff tool has a lot options, you will get a list with:
691 <userinput>diff --help</userinput>
697 <section id="ChSrcGoodPatch">
698 <title>Some tips for a good patch</title>
700 Some tips that will make the merging of your changes into the
701 SVN tree much more likely (and you want exactly that, don't you :-):
704 <command>Use the latest SVN sources, or alike.</command>
705 It's a good idea to work with the same sources that are used by the
706 other developer's, this makes it usually much easier to apply your
707 patch. For information about the different ways to get the sources,
708 see <xref linkend="ChSrcObtain"/>.
711 <command>Update your SVN sources just before making a patch.
712 </command> For the same reasons as the previous point.
715 <command>Do a "make clean" before generating the patch.</command>
716 This removes a lot of unneeded intermediate files (like object files)
717 which can confuse the diff tool generating a lot of unneeded stuff which
718 you have to remove by hand from the patch again.
721 <command>Find a good descriptive filename for your patch.</command>
722 Think a moment to find a proper name for your patch file. Often a
723 filename like <filename>wireshark.diff</filename> is used, which isn't
724 really helpful if keeping several of these files and find the right
725 one later. For example: If you want to commit changes to the datatypes
726 of dissector foo, a good filename might be:
727 <filename>packet-foo-datatypes.diff</filename>.
730 <command>Don't put unrelated things into one large patch.
731 </command> A few smaller patches are usually easier to apply (but also
732 don't put every changed line into a seperate patch :-).
735 <command>Remove any parts of the patch not related to the
736 changes you want to submit.</command> You can use a text editor for this.
737 A common example for win32 developers are the differences in your private
738 <filename>config.nmake</filename> file.
741 In general: making it easier to understand and apply your patch by one
742 of the maintainers will make it much more likely (and faster) that it
743 will actually be applied.
746 Please remember: you don't pay the person "on the
747 other side of the mail" for his/her effort applying your patch!
751 <section id="ChSrcCodeRequirements">
752 <title>Code Requirements</title>
754 The core maintainers have a lot of work fixing bugs and making code
755 compile on the various platforms Wireshark supports.
758 To ensure Wireshark's source code quality, and to reduce the workload of
759 the core maintainers, there are some things you should
760 think about <command>before</command> submitting a patch.
761 <warning><title>Warn!</title>
763 <command>Ignoring the code requirements will make it very likely
764 that your patch will be rejected!</command>
769 <command>Follow the Wireshark source code style guide.</command>
770 Just because something compiles on your platform, that doesn't
771 mean it'll compile on all of the other platforms for which Wireshark is
773 Wireshark runs on many platforms, and can be compiled with a number of
774 different compilers. See <xref linkend="ChCodeStyle"/> for details.
778 <command>Fuzz test your changes!</command> Fuzz testing is a very
779 effective way to automatically find a lot of dissector related bugs.
780 You'll take a capture file containing packets affecting your dissector
781 and the fuzz test randomly change bytes in this file, so unconditional
782 code paths in your dissector are passed. There are tools available to
783 automatically do this on any number of input files, see:
784 <ulink url="http://wiki.wireshark.org/FuzzTesting"/> for details.
791 <section id="ChSrcSend">
792 <title>Sending your patch to the developer mailing list</title>
794 After generating a patch of your changes, you might want to have your
795 changes included into the SVN server.
798 You should send an email to <ulink
799 url="mailto:wireshark-dev[AT]wireshark.org"/> containing:
802 subject: [PATCH] and a short description of your changes
805 body: the reasons for your changes and a short description what you
806 changed and how you changed it
809 attachment: the patch file
812 Don't include your patch into the mail
813 text, as this often changes the text formatting and makes it much
814 harder to apply your patch.
817 When someone from the Wireshark core maintainers finds the time to look
818 at your patch, it will be merged into the SVN repository, so
819 the latest SVN revisions and new releases will include it :-)
822 You might get one of the following responses from your mail:
825 your patch is checked into the SVN repository :-)
828 your patch is rejected (and you get a response mail like: please
829 change xy because of ...). Possible reasons: you didn't followed the
830 style guides, your code was buggy or insecure, your code does not
831 compile on all of the supported platforms, ... So please fix the
832 mentioned things and send a newly generated patch.
835 you don't get any reponse to your patch (even after a few days or so).
836 Possible reason: your patch might simply get lost, as all core
837 maintainers were busy at that time and forgot to look at your patch.
838 Simply send a mail asking if the patch was forgotten or if someone is
846 <section id="ChSrcPatchApply">
847 <title>Apply a patch from someone else</title>
849 Sometimes you need to apply a patch to your private source tree. Maybe
850 because you want to try a patch from someone on the developer mailing
851 list, or you want to check your own patch before submitting.
853 <warning><title>Warning!</title>
855 If you have problems applying a patch, make sure the line endings (CR/NL)
856 of the patch and your source files match.
860 XXX - the following is a collection of material and needs some
864 Given the file "new.diff" containing a unified diff, the right way to
865 call the patch tool depends on what the pathnames in "new.diff" look like.
866 If they're relative to the top-level source directory - for example, if a
867 patch to "prefs.c" just has "prefs.c" as the file name - you'd run it as:
870 <userinput>patch -p0 <new.diff</userinput>
873 If they're relative to a higher-level directory, you'd replace 0 with the
874 number of higher-level directories in the path, e.g. if the names are
875 "wireshark.orig/prefs.c" and "wireshark.mine/prefs.c", you'd run it with:
878 <userinput>patch -p1 <new.diff</userinput>
881 If they're relative to a <command>subdirectory</command> of the top-level
882 directory, you'd run "patch" in <command>that</command> directory and run
886 If you run it without "-p" at all, the patch tool flattens path names, so
888 have a patch file with patches to "Makefile.am" and "wiretap/Makefile.am",
889 it'll try to apply the first patch to the top-level "Makefile.am" and then
890 apply the "wiretap/Makefile.am" patch to the top-level "Makefile.am" as
894 At which position in the filesystem has the patch tool to be called?
897 If the pathnames are relative to the top-level source directory, or to a
898 directory above that directory, you'd run it in the top-level source
902 If they're relative to a <command>subdirectory</command> - for example,
903 if somebody did a patch to "packet-ip.c" and ran "diff" or "svn diff" in
904 the "epan/dissectors" directory - you'd run it in that subdirectory.
905 It is preferred that people <command>NOT</command> submit patches like
906 that - especially if they're only patching files that exist in multiple
907 directories, such as "Makefile.am".
910 One other thing to note - "cvs diff" produces output that at least some
911 versions of "patch" can't handle; you'd get something such as
914 Index: missing/dlnames.c
915 ===================================================================
916 RCS file: /tcpdump/master/tcpdump/missing/dlnames.c,v
917 retrieving revision 1.5
918 diff -c -r1.5 dlnames.c
919 *** missing/dlnames.c 18 Nov 2003 23:09:43 -0000 1.5
920 --- missing/dlnames.c 31 Aug 2004 21:45:16 -0000
924 from "cvs diff -c", and something similar from "cvs diff -u", and "patch",
925 unfortunately, would use the "diff -c" or "diff -u" line and try to patch
926 "dlnames.c" in the directory you're in, rather than in the "missing"
930 For "cvs diff -c" or "cvs diff -u" diffs, there's a Python script
931 "cvsdiff-fix.py" in the "tools" directory in the Wireshark source tree; it
932 will fix up those lines in "cvs diff" output. It reads its standard input
933 by default, or can be given a file name on the command line, and writes to
934 the standard output, so if you're typing at a command interpreter that
935 does piping, you could do something such as
938 <userinput>python tools/cvsdiff.py patchfile | patch -p0 -</userinput>
941 to use "patchfile". (You might be able to leave the "python" out of the
942 command line on many UN*Xes.)
945 "svn diff" doesn't produce a "diff -c" or "diff -u" line, so its output
946 doesn't have that problem. Regular "diff -c" or "diff -u" output also
947 shouldn't have that problem.
950 XXX - add some more details and do some cleanup.
954 <section id="ChSrcAdd">
955 <title>Add a new file to the Subversion repository</title>
957 The "usual" way to commit new files is described in <xref
958 linkend="ChSrcCommit"/>. However, the following might be of interest for
959 the "normal" developer as well.
961 <note><title>Note!</title>
963 This action is only possible/allowed by the Wireshark core developers who
964 have write access to the Subversion repository. It is put in here, to have
965 all information in one place.
969 If you (as a core developer) need to add a file to the SVN repository,
970 then you need to perform the following steps:
974 Add the Wireshark boilerplate to the new file(s).
979 Add a line to each new file, containing the following text (case is
980 important, so don't write ID or id or iD):
988 Add the new file(s) to the repository:
992 <userinput>svn add new_file</userinput>
997 Set the line ending property to "native" for the new file(s):
1001 <userinput>svn propset svn:eol-style native new_file</userinput>
1006 Set version keyword to "Id" for the new file(s):
1010 <userinput>svn propset svn:keywords Id new_file</userinput>
1015 Commit your changes, including the added file(s).
1019 <userinput>svn commit new_file other_files_you_modified</userinput>
1023 Don't forget a brief description of the reason for the commit, so other
1024 developers don't need to read the diff in order to know what has changed.
1027 <section id="ChSrcBinary">
1028 <title>Binary packaging</title>
1030 Delivering binary packages, makes it much easier for the end-users to
1031 install Wireshark on their target system. This section will explain how
1032 the binary packages are made.
1035 <section id="ChSrcDeb">
1036 <title>Debian: .deb packages</title>
1038 XXX - don't know how to do
1042 <section id="ChSrcRpm">
1043 <title>Red Hat: .rpm packages</title>
1045 XXX - don't know how to do
1049 <section id="ChSrcNSIS">
1050 <title>Win32: NSIS .exe installer</title>
1052 The "Nullsoft Install System" is a free installer generator for win32
1053 based systems, instructions how to install it can be found in <xref
1054 linkend="ChToolsNSIS"/>.
1055 NSIS is script based, you will find the Wireshark installer
1056 generation script at: <filename>packaging/nsis/wireshark.nsi</filename>.
1059 You will probably have to modify the <filename>config.nmake</filename>
1060 file to specify where the NSIS binaries are
1061 installed and wether to use the modern UI (which is recommended) or not.
1064 In the wireshark directory, type:
1067 <prompt>></prompt> <userinput>nmake -f makefile.nmake packaging</userinput>
1070 to build the installer.
1072 <tip><title>Tip!</title>
1074 Please be patient while the compression is
1075 done, it will take some time (a few minutes!) even on fast machines.
1079 If everything went well, you will now find something like:
1080 <filename>wireshark-setup-&WiresharkCurrentVersion;.exe</filename> in
1081 the <filename>packaging/nsis</filename> directory.
1088 <!-- End of WSDG Chapter Sources -->