1089 lines
36 KiB
XML
1089 lines
36 KiB
XML
<!-- WSDG 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 Wireshark project's
|
|
Subversion repository located at a server at the wireshark.org 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 Wireshark'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 Wireshark 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.wireshark.org/wireshark/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.wireshark.org/viewvc/viewvc.cgi/"/>.
|
|
</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 Wireshark'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
|
|
Wireshark's anonymous Subversion repository. The URL for the repository
|
|
trunk is:
|
|
<ulink url="http://anonsvn.wireshark.org/wireshark/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.wireshark.org/wireshark/trunk wireshark</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.wireshark.org/viewvc/viewvc.cgi/"/>.
|
|
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
|
|
Wireshark's sourcetree after a source code change committed.
|
|
These snapshots can be found at: <ulink
|
|
url="http://www.wireshark.org/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.wireshark.org/download.html"/>.
|
|
You should use these sources if you want to build Wireshark 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 Wireshark 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 Wireshark) 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 wireshark 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>></prompt> <userinput>nmake -f Makefile.nmake distclean</userinput>
|
|
</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 Wireshark build process.
|
|
</para>
|
|
<para>
|
|
After the build process successfully finished, you should find an
|
|
<filename>wireshark.exe</filename> and some other files
|
|
in the root directory.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="ChSrcRunFirstTime">
|
|
<title>Run generated Wireshark for the first time</title>
|
|
<tip><title>Tip!</title>
|
|
<para>
|
|
An already installed Wireshark may interfere with your newly generated
|
|
version in various ways. If you have any problems getting your Wireshark
|
|
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 Wireshark</title>
|
|
<para>
|
|
See the above info on running Wireshark.
|
|
</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 Wireshark (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 Wireshark
|
|
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 Wireshark have helped people
|
|
</para></listitem>
|
|
<listitem><para>
|
|
The developers of Wireshark 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 Wireshark 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 Wireshark. So if Wireshark is
|
|
updated (which is done often), you can get a new Wireshark version from
|
|
the website and your changes will already be included without any effort
|
|
for you. The maintainers and developers of Wireshark 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 Wireshark.
|
|
</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 ../wireshark-0.99.0/epan/dissectors/packet-dcerpc.c ./epan/dissectors/packet-dcerpc.c
|
|
--- ../wireshark-0.99.0/epan/dissectors/packet-dcerpc.c 2005-08-12 15:42:26.000000000 -0700
|
|
+++ ./epan/dissectors/packet-dcerpc.c 2005-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>
|
|
<userinput>svn diff [changed_files] > svn.diff</userinput>
|
|
</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.wireshark.org.
|
|
</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>wireshark.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 Wireshark supports.
|
|
</para>
|
|
<para>
|
|
To ensure Wireshark'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.
|
|
Wireshark 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.wireshark.org/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:wireshark-dev[AT]wireshark.org"/> 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 <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
|
|
"wireshark.orig/prefs.c" and "wireshark.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 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 Wireshark 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 Wireshark 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 wireshark 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>wireshark-setup-&WiresharkCurrentVersion;.exe</filename> in
|
|
the <filename>packaging/nsis</filename> directory.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
<!-- End of WSDG Chapter Sources -->
|