--- /dev/null
+<!-- EDG Chapter Sources -->
+<!-- $Id$ -->
+
+<chapter id="ChapterSources">
+ <title>Work with the Ethereal sources</title>
+
+ <section id="ChSrcIntro">
+ <title>Introduction</title>
+ <para>
+ This chapter will explain how to work with the Ethereal 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 Ethereal Subversion repository</title>
+ <para>
+ Subversion is used to keep track of the changes made to the Ethereal
+ source code. The Ethereal 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 Ethereal 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 Ethereal project has switched from CVS (Concurrent versioning
+ system) to Subversion some time ago, you may still find old references to
+ CVS in the Ethereal 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 Ethereal 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 Ethereal sources</title>
+ <para>
+ There are several ways to obtain the sources from Ethereal's Subversion
+ server.
+ </para>
+ <note><title>Note!</title>
+ <para>
+ The following ways to retrieve the Ethereal 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>
+ <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>
+ <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="ChSrcNightly">
+ <title>Nightly snapshots</title>
+ <para>
+ Well, not recommended at all.
+ </para>
+ <para>
+ Age: up to 24 hours.
+ </para>
+ <para>
+ The Subversion server will automatically generate a snapshot of Ethereal's
+ sourcetree every night. These snapshots can be found at: <ulink
+ url="http://www.ethereal.com/distribution/nightly-builds/"/>.
+ </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 nightly 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 anonymour 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 Ethereal sources</title>
+ <para>
+ After you obtained the Ethereal 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 Ethereal 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 Ethereal 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 Ethereal 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>
+ </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>
+ After doing this, typing inside the command line (cmd.exe):
+ </para>
+ <para>
+ <prompt>></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 Ethereal sources</title>
+ <para>
+ As the Ethereal 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 Ethereal 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 Ethereal sources to suit your needs,
+ you might want to contribute your changes back to the Ethereal 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 Ethereal 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 multiple of such 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 Ethereal 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 Ethereal 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>
+ XXX - add details at least for recommended TortoiseSVN
+ </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 > 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 > 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>Follow the Ethereal source code style guide.</command>
+ Ethereal runs on many platforms, and can be compiled with a number of
+ different compilers. See <xref linkend="ChCodeStyle"/> for details.
+ </para>
+ <note><title>Note!</title>
+ <para>
+ Just because something compiles on your platform, that doesn't mean it'll
+ compile on all of the other platforms for which Ethereal is built.
+ </para>
+ </note>
+ </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="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 Ethereal 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>
+ <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 <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 <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 Ethereal 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="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 Ethereal installer
+ generation script at: <filename>packaging/nsis/ethereal.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>></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 EUG Chapter Sources -->
git.samba.org / obnox / wireshark / wip.git / blobdiff