[obnox/wireshark/wip.git] / docbook / edg_src / EDG_chapter_sources.xml

<!-- EDG Chapter Sources -->
<!-- $Id$ -->

<chapter id="ChapterSources">
  <title>Work with the Wireshark sources</title>

  <section id="ChSrcIntro">
        <title>Introduction</title>
        <para>
        This chapter will explain how to work with the Wireshark source code.
        It will show you how to:
        <itemizedlist>
        <listitem><para>
        get the source
        </para></listitem>
        <listitem><para>
        compile the source
        </para></listitem>
        <listitem><para>
        submit changes
        </para></listitem>
        <listitem><para>
        ...
        </para></listitem>
        </itemizedlist>
        However, this chapter will not explain the source file contents in detail, 
        such as where to find a specific functionality. This is done in 
        <xref linkend="ChCodeOverview"/>.
        </para>
  </section>
        
  <section id="ChSrcSVNServer">
        <title>The Wireshark Subversion repository</title>
        <para>
        Subversion is used to keep track of the changes made to the Wireshark 
        source code. The Wireshark source code is stored inside Ethereal project's 
        Subversion repository located at a server at the ethereal.com domain.
        </para>
        <para>
        To qoute the Subversion book about "What is Subversion?": 
        </para>
        <para>
        <quote>Subversion is a free/open-source version control system. That is, 
        Subversion manages files and directories over time. A tree of files is 
        placed into a central repository. The repository is much like an ordinary 
        file server, except that it remembers every change ever made to your files 
        and directories. This allows you to recover older versions of your data, 
        or examine the history of how your data changed. In this regard, many 
        people think of a version control system as a sort of "time machine".
        </quote>
        </para>
        <tip><title>Tip!</title>
        <para>
        Subversion is often abbreviated as SVN, as the command-line tools are 
        abbreviated that way. You will find both terms with the same meaning in 
        this book, in mailing list discussions and elsewhere.
        </para>
        </tip>
        <para>
        Using Ethereal's Subversion repository you can:
        <itemizedlist>
        <listitem><para>
        keep your private sources uptodate with very little effort
        </para></listitem>
        <listitem><para>
        get a mail notification if someone changes the latest sources
        </para></listitem>
        <listitem><para>
        get the source files from any previous release (or any other point in time)
        </para></listitem>
        <listitem><para>
        have a quick look at the sources using a web interface
        </para></listitem>
        <listitem><para>
        see which person changed a specific piece of code
        </para></listitem>
        <listitem><para>
        ... and a lot more things related to the history of the Wireshark source 
        code development
        </para></listitem>
        </itemizedlist>
        </para>
        <para>
        The way Ethereal uses Subversion, it can be parted into a client and a 
        server part. Thanks to Gerald Combs (the maintainer of the Subversion 
        server), no user usually has to deal with the
        Subversion server. You will only need a Subversion client, which is 
        available as a command-line tool for many different platforms. GUI based 
        tools also becoming more and more available these days.
        </para>
        <para>
        For further reference about Subversion, have a look at the homepage of the 
        Subversion project: <ulink url="http://subversion.tigris.org/"/>. There 
        is a good and free book about it available at: <ulink 
        url="http://svnbook.red-bean.com/"/>.
        </para>
        <para>
        Please note that the anonymous Subversion repository is separate from 
        the main repository. It may take several minutes for committed changes to 
        appear in the anonymous repository. XXX - be more specific here.
        </para>
        <tip><title>Tip!</title>
        <para>
        As the Wireshark project has switched from CVS (Concurrent versioning 
        system) to Subversion some time ago, you may still find old references to 
        CVS in the Wireshark documentation and source files.
        </para>
        </tip>
  </section>
        
  <section id="ChSrcWebInterface">
        <title>The web interface to the Subversion repository</title>
        <para>
        If you need a quick look at the Wireshark source code, 
        you will only need a Web browser.
        </para>
        <para>
        A <command>simple view</command> on the latest developer version can be 
        found at: 
        </para>
        <para>
        <ulink url="http://anonsvn.ethereal.com/ethereal/trunk/"/>.
        </para>
        <para>
        A <command>comprehensive view</command> of all source versions 
        (e.g. including the capability to show differences between versions) 
        is available at:
        </para>
        <para>
        <ulink url="http://anonsvn.ethereal.com/viewcvs/viewcvs.py/"/>. 
        </para>
        <para>
        Of special interest might be the subdirectories:
        <itemizedlist>
        <listitem><para>
        trunk - the very latest source files
        </para></listitem>
        <listitem><para>
        releases - the source files of all released versions
        </para></listitem>
        </itemizedlist>
        </para>
  </section>    

  <section id="ChSrcObtain">
        <title>Obtain the Wireshark sources</title>
        <para>
        There are several ways to obtain the sources from Ethereal's Subversion 
        server.
        </para>
        <tip><title>Tip!</title>
        <para>
        Anonymous Subversion access can make your life much easier, compared to
        update your source tree by using any of the zip file methods mentioned 
        below.
        Subversion handles merging of changes into your personal source tree in a 
        very comfortable and quick way. So you can update your source tree several 
        times a day without much effort.
        </para>
        </tip>
        <note><title>Note!</title>
        <para>
        The following ways to retrieve the Wireshark sources are sorted in 
        decreasing 
        actuality. If you plan to commit changes you've made to the sources,
        it's a good idea to keep your private source tree as actual as possible.
        </para>
        </note>
        <para>
        The age mentioned in the following sections will indicate, how old the 
        most recent change in that sources will be. 
        </para>
        
        <section id="ChSrcAnon">
        <title>Anonymous Subversion access</title>
        <para>
        Recommended for development purposes.
        </para>
        <para>
        Age: a few minutes.
        </para>
        <para>
        You can use a Subversion client to download the source code from 
        Ethereal's anonymous Subversion repository. The URL for the repository 
        trunk is:
        <ulink url="http://anonsvn.ethereal.com/ethereal/trunk/"/>.
        </para>
        <para>
        See <xref linkend="ChToolsSubversion"/> how to install a Subversion client.
        </para>
        <para>
        For example, to check out using the command-line Subversion client, you 
        would type:
        </para>
        <para>
        <prompt>$</prompt> 
        <userinput>svn checkout http://anonsvn.ethereal.com/ethereal/trunk ethereal</userinput>
        </para>
        <para>
        The checkout has to be only done once. This will copy all the sources of 
        the latest version (including directories) from the server to your machine.
        This will take some time, depending on the speed of your internet line.
        </para>
        </section>

        <section id="ChSrcSVNWeb">
        <title>Anonymous Subversion web interface</title>
        <para>
        Recommended for development purposes, if direct Subversion access isn't 
        possible (e.g. because of a restrictive firewall).
        </para>
        <para>
        Age: a few minutes (same as anonymous Subversion access).
        </para>
        <para>
         The entire source tree of the Subversion repository is available via a 
         web interface at:
         <ulink url="http://anonsvn.ethereal.com/viewcvs/viewcvs.py/"/>. 
         You can view 
         each revision of a particular file, as well as diffs between different 
         revisions. You can also download individual files or entire directories.
        </para>
        </section>      
         
        <section id="ChSrcBuildbot">
        <title>Buildbot Snapshots</title>
        <para>
        Recommended for development purposes, if direct Subversion access isn't 
        possible (e.g. because of a restrictive firewall).
        </para>
        <para>
        Age: a few minutes (a bit older than the anonymous Subversion access).
        </para>
        <para>
        The buildbot server will automatically start to generate a snapshot of 
        Ethereal's sourcetree after a source code change committed. 
        These snapshots can be found at: <ulink
        url="http://www.ethereal.com/distribution/buildbot-builds/source/"/>.
        </para>
        <para>
        If anonymous Subversion access isn't possible, e.g. if the connection to 
        the server isn't possible because of a corporate firewall, the sources 
        can be obtained by downloading this buildbot snapshots. However, if you are
        going to maintain your sources in parallel to the "official" sources
        for some time, it's recommended to use the anonymous Subversion access if
        possible (believe it, it will save you a lot of time).
        </para>
        </section>


        <section id="ChSrcReleased">
        <title>Released sources</title>
        <para>
        Recommended for productive purposes.
        </para>
        <para>
        Age: from days to weeks.
        </para>
        <para>
        The officially released source files can be found at: <ulink
        url="http://www.ethereal.com/download.html"/>.
        You should use these sources if you want to build Ethereal on your
        platform for productive use.
        </para>
        <para>
        The differences between the released sources and the sources stored at
        the Subversion repository are keep on growing until the next release is 
        done (at the release time, the released and latest Subversion repository
        versions are then identical again :-).
        </para>
        </section>

  </section>

  <section id="ChSrcUpdating">
        <title>Update the Wireshark sources</title>
        <para>
        After you obtained the Wireshark sources for the first time, you 
        might want to keep them in sync with the sources at the Subversion 
        repository.
        </para>
        
        <section id="ChSrcAnonUpdate">
        <title>... with Anonymous Subversion access</title>
        <para>
        After the first time checkout is done, updating your 
        sources is simply done by typing (in the Wireshark source dir):
        </para>
        <para>
        <prompt>$</prompt> 
        <userinput>svn update</userinput>
        </para>
        <para>
        This will only take a few seconds, even on a slow internet line. It will 
        replace old file versions by new ones. If you and someone else have 
        changed the same file since the last update, Subversion will try to merge 
        the changes into your private file (this is working remarkably well).
        </para>
        </section>

        <section id="ChSrcZipUpdate">
        <title>... from zip files</title>
        <para>
        Independant of the way you retrieve the zip file of the Wireshark sources
        (as <xref linkend="ChSrcObtain"/> is providing several ways), the way to 
        bring the changes from the official sources into your personal source tree
        is identical.
        </para>
        <para>
        First of all, you will download the new zip file of the official sources
        the way you did it the first time.
        </para>
        <para>
        If you didn't changed anything in the sources, you could simply throw 
        away your old sources and reinstall everything just like the first time.
        But be sure, that you really didn't changed anything. It might be a good
        idea to simply rename the "old" dir to have it around, just in case you 
        remember later that you really did changed something before.
        </para>
        <para>
        Well, if you did change something in your source tree, you have to merge 
        the official changes 
        since the last update into your source tree. You will install the content 
        of the zip file into a new directory and use a good merge tool (e.g. 
        <ulink url="http://winmerge.sourceforge.net/"/> for Win32) to bring 
        your personal source tree in sync with the official sources again. 
        </para>
        </section>

  </section>

  <section id="ChSrcBuildFirstTime">
        <title>Build Ethereal for the first time</title>
        <para>
        The sources contains several documentation files, it's a good idea to
        look at these files first.
        </para>
        <para>
        So after obtaining the sources, tools and libraries, the
        first place to look at is <filename>doc/README.developer</filename>,
        here you will get the latest infos for Wireshark development for all
        supported platforms.
        </para>
        <tip><title>Tip!</title>
        <para>
        It is a very good idea, to first test your complete build environment 
        (including running and debugging Ethereal) before doing any changes 
        to the source code (unless otherwise noted).
        </para>
        </tip>
        <para>
        The following steps for the first time generation differs on the two
        major platforms.
        </para>
        
        <section>
        <title>Unix</title>
        <para>
        Run the autogen.sh script at the top-level ethereal directory to configure 
        your build directory.
        <programlisting>
./autogen.sh
./configure
make 
        </programlisting>
        </para>
        <para>
        If you need to build with a GTK 1.x version, you have to use:
        <programlisting>
./configure --disable-gtk2
        </programlisting>
        instead of just ./configure.
        </para>
        </section>
        
        <section>
        <title>Win32 native</title>
        <para>
        The place to look at is <filename>doc/README.win32</filename>, 
        you will get the latest infos for generation on the win32
        platforms.
        </para>
        <para>
        The next thing to do will be editing the file 
        <filename>config.nmake</filename> to reflect your configuration.
        The settings in this file are well documented, so please have a look at 
        that file.
        </para>
        <para>
        Then you should cleanup any intermediate files, which are shipped for 
        convenience of Unix users, by typing inside the command line (cmd.exe):
        </para>
        <para>
        <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake distclean</userinput>
        </para>
        <para>
        After doing this, typing inside the command line (cmd.exe):
        </para>
        <para>
        <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake all</userinput>
        </para>
        <para>
        will start the whole Ethereal build process.
        </para>
        <para>
        After the build process successfully finished, you should find an 
        <filename>ethereal.exe</filename> and some other files
        in the root directory.
        </para>
        </section>
        
  </section>

  <section id="ChSrcRunFirstTime">
        <title>Run generated Ethereal for the first time</title>
        <tip><title>Tip!</title>
        <para>
        An already installed Ethereal may interfere with your newly generated 
        version in various ways. If you have any problems getting your Ethereal 
        running the first time, it might be a good idea to remove the previously 
        installed version first.
        </para>
        </tip>
        <para>
        XXX - add more info here.
        </para>
  </section>
        
  <section id="ChSrcDebug">
        <title>Debug your generated Ethereal</title>
        <para>
        See the above info on running Ethereal.
        </para>
        <para>
        XXX - add more info here.
        </para>
        
        <section id="ChSrcWin32Debug">
        <title>Win32 native</title>
        <para>
        XXX - add more info here.
        </para>
        </section>
  </section>
        
  <section id="ChSrcChange">
        <title>Make changes to the Wireshark sources</title>
        <para>
        As the Wireshark developers working on many different platforms, a lot of 
        editors are used to develop Ethereal (emacs, vi, Microsoft Visual Studio
        and many many others). There's no "standard" or "default" development 
        environment.
        </para>
        <para>
        There are several reasons why you might want to change the Ethereal
        sources:
        <itemizedlist>
          <listitem><para>add your own new dissector</para></listitem>
          <listitem><para>change/extend an existing dissector</para></listitem>
          <listitem><para>fix a bug</para></listitem>
          <listitem><para>implement a new glorious feature :-)</para></listitem>
        </itemizedlist>
        The internal structure of the Wireshark sources will be described in 
        <xref linkend="PartDevelopment"/>.
        </para>
        <tip><title>Tip!</title>
        <para>
        <command>Ask the developer mailing list before you really start a new 
        development task.</command>     
        If you have an idea what you want to add/change, it's a good idea to 
        contact the developer mailing list 
        (see <xref linkend="ChIntroMailingLists"/>) 
        and explain your idea. Someone else might already be working on the same 
        topic, so double effort can be reduced, or can give you some tips what 
        should be thought about too (like side effects that are sometimes very 
        hard to see).
        </para>
        </tip>
  </section>

  <section id="ChSrcCommit">
        <title>Commit changed sources</title>
        <para>
        If you have finished changing the Wireshark sources to suit your needs,
        you might want to contribute your changes back to the Wireshark SVN
        repository.
        </para>
        <para>
        You gain the following benefits by contributing your improvements back to 
        the community:
        <itemizedlist>
        <listitem><para>
        Other people who find your contributions useful will appreciate
        them, and you will know that you have helped people in the same way
        that the developers of Ethereal have helped people
        </para></listitem>
        <listitem><para>
        The developers of Ethereal might improve your changes even more, as 
        there's always room for improvements. Or they may implement some advanced 
        things on top of your code, which can be useful for yourself too.
        </para></listitem>
        <listitem><para>
        The maintainers and developers of Ethereal will maintain your code as 
        well, fixing it when API changes or other changes are made, and generally 
        keeping it in tune with what is happening with Ethereal. So if Wireshark is 
        updated (which is done often), you can get a new Ethereal version from 
        the website and your changes will already be included without any effort 
        for you. The maintainers and developers of Ethereal will maintain your
        code as well, fixing it when API changes or other changes are made, and
        generally keeping it in tune with what is happening with Ethereal.
        </para></listitem>
        </itemizedlist>
        There's no direct way to commit changes to the SVN repository. Only a few
        people are authorised to actually
        make changes to the source code (check-in changed files). If you want
        to submit your changes, you should make a diff file (a patch) and send
        it to
        the developer mailing list.     
        </para>

        <section id="ChSrcDiffWhat">
        <title>What is a diff file (a patch)?</title>
        <para>
        A diff file is a plain text file containing the differences between a 
        pair of files (or a multiple of such file pairs). 
        <tip><title>Tip!</title>
        <para>A diff file is often also called a patch, 
        as it can be used to patch an existing source file or tree with changes
        from somewhere else.
        </para>
        </tip>
        </para>
        <para>
        The Wireshark community is using patches to transfer source code changes 
        between the authors.
        </para>
        <para>
        A patch is both readable by humans and (as it is specially formatted) by 
        some dedicated tools.
        </para>
        <para>
        Here is a small example of a patch file (XXX - generate a better example):
        <programlisting>
<![CDATA[
diff -ur ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c ./epan/dissectors/packet-dcerpc.c
--- ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c  2004-08-12 15:42:26.000000000 -0700
+++ ./epan/dissectors/packet-dcerpc.c   2004-08-19 18:48:32.000000000 -0700
@@ -282,6 +282,7 @@
 /* we need to keep track of what transport were used, ie what handle we came
  * in through so we know what kind of pinfo->private_data was passed to us.
  */
+/* Value of -1 is reserved for "not DCE packet" in packet_info.dcetransporttype. */
 #define DCE_TRANSPORT_UNKNOWN          0
 #define DCE_CN_TRANSPORT_SMBPIPE       1
 
]]> 
        </programlisting>
        The plus sign at the start of a line indicates an added line, a minus 
        sign indicates a deleted line compared to the original sources.
        </para>
        <para>
        As we always use so called "unified" diff files in Wireshark development, 
        three unchanged lines before and after the actual changed parts are 
        included. This will make it much easier for a merge/patch tool to find 
        the right place(s) to change in the existing sources.
        </para>
        </section>


        <section id="ChSrcGeneratePatch">
        <title>Generate a patch</title>
        <para>
        There are several ways to generate such a patch.
        </para>

        <section id="ChSrcSVNDiff">
        <title>Using the svn command-line client</title>
        <para>
        svn diff -u [changed_files] > svn.diff
        </para>
        <para>
        XXX - add more details
        </para>
        </section>

        <section id="ChSrcSVNGUIDiff">
        <title>Using the diff feature of the GUI Subversion clients</title>
        <para>
        Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...) 
        have a built-in "diff" feature.
        </para>
        <para>
        If you use TortoiseSVN:
        </para>
        <para>
        TortoiseSVN (to be precise subversion) keeps track of the files you have 
        changed in the directories it controls, and will generate for you a 
        unified diff file compiling the differences. To do so - after updating 
        your sources from the SVN repository if needed - just right-click on the 
        highest level directory and choose "TortoiseSVN" -> "Create patch...". 
        You will be asked for a name and then the diff file will be created. The 
        names of the files in the patch will be relative to the directory you have 
        right-clicked on, so it will need to be applied on that level too.
        </para>
        <para>
        When you create the diff file, it will include any difference TortoiseSVN 
        finds in files in and under the directory you have right-clicked on, and 
        nothing else. This means that changes you might have made for your 
        specific configuration - like modifying "config.nmake" so that it uses 
        your lib directory - will also be included, and you will need to remove 
        these lines from the diff file. It also means that only changes will be 
        recorded, i.e. if you have created new files -say, a new packet-xxx for a 
        new protocol dissector- it will not be included in the diff, you need to 
        add it separately. And, of course, if you have been working separately in 
        two different patches, the .diff file will include both topics, which is 
        probably not a good idea.
        </para>
        </section>

        <section id="ChSrcDiff">
        <title>Using the diff tool</title>
        <para>
        A diff file is generated, by comparing two files or directories between
        your own working copy and the "official" source tree. So to be able to
        do a diff, you should
        have two source trees on your computer, one with your working copy
        (containing your changes), and one with the "official" source tree
        (hopefully the latest SVN files) from www.ethereal.com.
        </para>
        <para>
        If you have only changed a single file, you could type something like
        this:
        </para>
        <para>
        <userinput>diff -r -u --strip-trailing-cr svn-file.c work-file.c &gt; foo.diff</userinput>
        </para>
        <para>
        To get a diff file for your complete directory (including
        subdirectories), you could type something like this:
        </para>
        <para>
        <userinput>diff -r -u --strip-trailing-cr ./svn-dir ./working-dir &gt; foo.diff</userinput>
        </para>
        <para>
        It's a good idea to do a <userinput>make distclean</userinput> before the 
        actual diff call, as this will remove a lot
        of temporary files which might be otherwise included in the diff. After
        doing the diff, you should edit the <filename>foo.diff</filename>
        file and remove unnecessary things, like your private changes to the
        <filename>config.nmake</filename> file.
        </para>
        <para>
        <table frame='all'><title>Some useful diff options</title>
        <tgroup cols='2' align='left' colsep='1' rowsep='1'>
        <colspec colname='c1'/>
        <colspec colname='c2'/>
        <thead>
        <row>
          <entry>Option</entry>
          <entry>Purpose</entry>
        </row>
        </thead>
        <tbody>
        <row>
          <entry>-r</entry>
          <entry>Recursively compare any subdirectories found.</entry>
        </row>
        <row>
          <entry>-u</entry>
          <entry>Output unified context.</entry>
        </row>
        <row>
          <entry>--strip-trailing-cr</entry>
          <entry>Strip trailing carriage return on input. This is useful for Win32
          </entry>
        </row>
        <row>
          <entry>-x PAT</entry>
          <entry>Exclude files that match PAT.
          This could be something like -x *.obj to exclude all win32 object files.
          </entry>
        </row>
        </tbody>
        </tgroup>
        </table>
        </para>
        <para>
        The diff tool has a lot options, you will get a list with:
        </para>
        <para>
        <userinput>diff --help</userinput>      
        </para>
        </section>

        </section>

        <section id="ChSrcGoodPatch">
        <title>Some tips for a good patch</title>
        <para>
        Some tips that will make the merging of your changes into the 
        SVN tree much more likely (and you want exactly that, don't you :-):
        <itemizedlist>
          <listitem><para>
          <command>Use the latest SVN sources, or alike.</command>
          It's a good idea to work with the same sources that are used by the 
          other developer's, this makes it usually much easier to apply your 
          patch. For information about the different ways to get the sources,
          see <xref linkend="ChSrcObtain"/>.
          </para></listitem>
          <listitem><para>
          <command>Update your SVN sources just before making a patch.
          </command> For the same reasons as the previous point.
          </para></listitem>
          <listitem><para>
          <command>Do a "make clean" before generating the patch.</command>
          This removes a lot of unneeded intermediate files (like object files) 
          which can confuse the diff tool generating a lot of unneeded stuff which 
          you have to remove by hand from the patch again.
          </para></listitem>
          <listitem><para>
          <command>Find a good descriptive filename for your patch.</command> 
          Think a moment to find a proper name for your patch file. Often a 
          filename like <filename>ethereal.diff</filename> is used, which isn't 
          really helpful if keeping several of these files and find the right 
          one later. For example: If you want to commit changes to the datatypes 
          of dissector foo, a good filename might be: 
          <filename>packet-foo-datatypes.diff</filename>.
          </para></listitem>
          <listitem><para>
          <command>Don't put unrelated things into one large patch.
          </command> A few smaller patches are usually easier to apply (but also 
          don't put every changed line into a seperate patch :-).
          </para></listitem>
          <listitem><para>
          <command>Remove any parts of the patch not related to the
          changes you want to submit.</command> You can use a text editor for this. 
          A common example for win32 developers are the differences in your private 
          <filename>config.nmake</filename> file.
          </para></listitem>
        </itemizedlist>
        In general: making it easier to understand and apply your patch by one
        of the maintainers will make it much more likely (and faster) that it 
        will actually be applied.
        </para>
        <para>
        Please remember: you don't pay the person "on the
        other side of the mail" for his/her effort applying your patch!
        </para>
        </section>

        <section id="ChSrcCodeRequirements">
        <title>Code Requirements</title>
        <para>
        The core maintainers have a lot of work fixing bugs and making code 
        compile on the various platforms Ethereal supports.
        </para>
        <para>
        To ensure Ethereal's source code quality, and to reduce the workload of 
        the core maintainers, there are some things you should 
        think about <command>before</command> submitting a patch.
        <warning><title>Warn!</title>
        <para>
        <command>Ignoring the code requirements will make it very likely 
        that your patch will be rejected!</command>
        </para>
        </warning>
        <itemizedlist>
          <listitem><para>
          <command>Follow the Wireshark source code style guide.</command> 
          Just because something compiles on your platform, that doesn't 
          mean it'll compile on all of the other platforms for which Wireshark is 
          built. 
          Ethereal runs on many platforms, and can be compiled with a number of 
          different compilers. See <xref linkend="ChCodeStyle"/> for details.
          </para>
          </listitem>
          <listitem><para>
          <command>Fuzz test your changes!</command> Fuzz testing is a very 
          effective way to automatically find a lot of dissector related bugs. 
          You'll take a capture file containing packets affecting your dissector 
          and the fuzz test randomly change bytes in this file, so unconditional 
          code paths in your dissector are passed. There are tools available to 
          automatically do this on any number of input files, see: 
          <ulink url="http://wiki.ethereal.com/FuzzTesting"/> for details.
          </para>
          </listitem>
        </itemizedlist>
        </para>
        </section>

        <section id="ChSrcSend">
        <title>Sending your patch to the developer mailing list</title>
        <para>
        After generating a patch of your changes, you might want to have your
        changes included into the SVN server.
        </para>
        <para>
        You should send an email to <ulink
        url="mailto:ethereal-dev[AT]ethereal.com"/> containing: 
        <itemizedlist>
          <listitem><para>
          subject: [PATCH] and a short description of your changes
          </para></listitem>
          <listitem><para>
          body: the reasons for your changes and a short description what you 
          changed and how you changed it
          </para></listitem>
          <listitem><para>
          attachment: the patch file
          </para></listitem>
        </itemizedlist>
        Don't include your patch into the mail
        text, as this often changes the text formatting and makes it much
        harder to apply your patch.
        </para>
        <para>
        When someone from the Wireshark core maintainers finds the time to look
        at your patch, it will be merged into the SVN repository, so
        the latest SVN revisions and new releases will include it :-)
        </para>
        <para>
        You might get one of the following responses from your mail:
        <itemizedlist>
          <listitem><para>
          your patch is checked into the SVN repository :-)
          </para></listitem>
          <listitem><para>
          your patch is rejected (and you get a response mail like: please
          change xy because of ...). Possible reasons: you didn't followed the 
          style guides, your code was buggy or insecure, your code does not 
          compile on all of the supported platforms, ... So please fix the 
          mentioned things and send a newly generated patch.
          </para></listitem>
          <listitem><para>
          you don't get any reponse to your patch (even after a few days or so).
          Possible reason: your patch might simply get lost, as all core 
          maintainers were busy at that time and forgot to look at your patch. 
          Simply send a mail asking if the patch was forgotten or if someone is 
          still looking at it.
          </para></listitem>
        </itemizedlist>
        </para>
        </section>
  </section>
        
  <section id="ChSrcPatchApply">
        <title>Apply a patch from someone else</title>
        <para>
        Sometimes you need to apply a patch to your private source tree. Maybe 
        because you want to try a patch from someone on the developer mailing 
        list, or you want to check your own patch before submitting.
        </para>
        <warning><title>Warning!</title>
        <para>
        If you have problems applying a patch, make sure the line endings (CR/NL)
        of the patch and your source files match.
        </para>
        </warning>
        <para>
        XXX - the following is a collection of material and needs some 
        clarification.
        </para>
        <para>
        Given the file "new.diff" containing a unified diff, the right way to 
        call the patch tool depends on what the pathnames in "new.diff" look like.
        If they're relative to the top-level source directory - for example, if a 
        patch to "prefs.c" just has "prefs.c" as the file name - you'd run it as:
        </para>
        <para>
    <userinput>patch -p0 &lt;new.diff</userinput>
        </para>
        <para>
        If they're relative to a higher-level directory, you'd replace 0 with the 
        number of higher-level directories in the path, e.g. if the names are 
        "ethereal.orig/prefs.c" and "ethereal.mine/prefs.c", you'd run it with:
        </para>
        <para>
    <userinput>patch -p1 &lt;new.diff</userinput>
        </para>
        <para>
        If they're relative to a <command>subdirectory</command> of the top-level 
        directory, you'd run "patch" in <command>that</command> directory and run 
        it with "-p0".
        </para>
        <para>
        If you run it without "-p" at all, the patch tool flattens path names, so 
        that if you 
        have a patch file with patches to "Makefile.am" and "wiretap/Makefile.am", 
        it'll try to apply the first patch to the top-level "Makefile.am" and then 
        apply the "wiretap/Makefile.am" patch to the top-level "Makefile.am" as 
        well.  
        </para>
        <para>
        At which position in the filesystem has the patch tool to be called?
        </para>
        <para>
        If the pathnames are relative to the top-level source directory, or to a 
        directory above that directory, you'd run it in the top-level source 
        directory.
        </para>
        <para>
        If they're relative to a <command>subdirectory</command> - for example, 
        if somebody did a patch to "packet-ip.c" and ran "diff" or "svn diff" in 
        the "epan/dissectors" directory - you'd run it in that subdirectory.  
        It is preferred that people <command>NOT</command> submit patches like 
        that - especially if they're only patching files that exist in multiple 
        directories, such as "Makefile.am".
        </para>
        <para>
        One other thing to note - "cvs diff" produces output that at least some
        versions of "patch" can't handle; you'd get something such as
        <programlisting>
<![CDATA[
Index: missing/dlnames.c
===================================================================
RCS file: /tcpdump/master/tcpdump/missing/dlnames.c,v
retrieving revision 1.5
diff -c -r1.5 dlnames.c
*** missing/dlnames.c   18 Nov 2003 23:09:43 -0000      1.5
--- missing/dlnames.c   31 Aug 2004 21:45:16 -0000
***************
]]>
        </programlisting>
        from "cvs diff -c", and something similar from "cvs diff -u", and "patch",
        unfortunately, would use the "diff -c" or "diff -u" line and try to patch
        "dlnames.c" in the directory you're in, rather than in the "missing"
        subdirectory.
        </para>
        <para>
        For "cvs diff -c" or "cvs diff -u" diffs, there's a Python script
        "cvsdiff-fix.py" in the "tools" directory in the Wireshark source tree; it
        will fix up those lines in "cvs diff" output.  It reads its standard input
        by default, or can be given a file name on the command line, and writes to
        the standard output, so if you're typing at a command interpreter that
        does piping, you could do something such as
        </para>
        <para>
    <userinput>python tools/cvsdiff.py patchfile | patch -p0 -</userinput>
        </para>
        <para>
        to use "patchfile".  (You might be able to leave the "python" out of the
        command line on many UN*Xes.)
        </para>
        <para>
        "svn diff" doesn't produce a "diff -c" or "diff -u" line, so its output
        doesn't have that problem.  Regular "diff -c" or "diff -u" output also
        shouldn't have that problem.
        </para>
        <para>
        XXX - add some more details and do some cleanup.
        </para>
  </section>

  <section id="ChSrcAdd">
        <title>Add a new file to the Subversion repository</title>
        <para>
        The "usual" way to commit new files is described in <xref 
        linkend="ChSrcCommit"/>. However, the following might be of interest for 
        the "normal" developer as well.
        </para>
        <note><title>Note!</title>
        <para>
        This action is only possible/allowed by the ethereal core developers who 
        have write access to the Subversion repository. It is put in here, to have 
        all information in one place.
        </para>
        </note>
        <para>
        If you (as a core developer) need to add a file to the SVN repository, 
        then you need to perform the following steps:
        <orderedlist>
        <listitem>
        <para>
        Add the Wireshark boilerplate to the new file(s).
        </para>
        </listitem>
        <listitem>
        <para>
        Add a line to each new file, containing the following text (case is 
        important, so don't write ID or id or iD):
<programlisting>
$Id$
</programlisting>
        </para>
        </listitem>
        <listitem>
        <para>
        Add the new file(s) to the repository:
        </para>
        <para>
        <prompt>$</prompt> 
        <userinput>svn add new_file</userinput>
        </para>
        </listitem>
        <listitem>
        <para>
        Set the line ending property to "native" for the new file(s):
        </para>
        <para>
        <prompt>$</prompt> 
        <userinput>svn propset svn:eol-style native new_file</userinput>
        </para>
        </listitem>
        <listitem>
        <para>
        Set version keyword to "Id" for the new file(s):
        </para>
        <para>
        <prompt>$</prompt> 
        <userinput>svn propset svn:keywords Id new_file</userinput>
        </para>
        </listitem>
        <listitem>
        <para>
        Commit your changes, including the added file(s).
        </para>
        <para>
        <prompt>$</prompt> 
        <userinput>svn commit new_file other_files_you_modified</userinput>
        </para>
        </listitem>
        </orderedlist>
        Don't forget a brief description of the reason for the commit, so other
        developers don't need to read the diff in order to know what has changed.
        </para>
  </section>
  <section id="ChSrcBinary">
        <title>Binary packaging</title>
        <para>
        Delivering binary packages, makes it much easier for the end-users to
        install Ethereal on their target system. This section will explain how
        the binary packages are made.
        </para>

        <section id="ChSrcDeb">
        <title>Debian: .deb packages</title>
        <para>
        XXX - don't know how to do
        </para>
        </section>

        <section id="ChSrcRpm">
        <title>Red Hat: .rpm packages</title>
        <para>
        XXX - don't know how to do
        </para>
        </section>
        
        <section id="ChSrcNSIS">
        <title>Win32: NSIS .exe installer</title>
        <para>
        The "Nullsoft Install System" is a free installer generator for win32
        based systems, instructions how to install it can be found in <xref 
        linkend="ChToolsNSIS"/>. 
        NSIS is script based, you will find the Wireshark installer
        generation script at: <filename>packaging/nsis/wireshark.nsi</filename>.
        </para>
        <para>
        You will probably have to modify the <filename>config.nmake</filename> 
        file to specify where the NSIS binaries are
        installed and wether to use the modern UI (which is recommended) or not.
        </para>
        <para>
        In the ethereal directory, type:
        </para>
        <para>
        <prompt>&gt;</prompt> <userinput>nmake -f makefile.nmake packaging</userinput>
        </para>
        <para>
        to build the installer. 
        </para>
        <tip><title>Tip!</title>
        <para>
        Please be patient while the compression is
        done, it will take some time (a few minutes!) even on fast machines.
        </para>
        </tip>
        <para>
        If everything went well, you will now find something like:
        <filename>ethereal-setup-&EtherealCurrentVersion;.exe</filename> in
        the <filename>packaging/nsis</filename> directory.
        </para>
        </section>

  </section>

</chapter>
<!-- End of EDG Chapter Sources -->