wireshark/docbook/wsdg_src/WSDG_chapter_sources.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 quote 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: Subversion and SVN is the same!</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 up to date 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>
	Subversion is divided into a client and a server part.
	Thanks to Gerald Combs (the maintainer of the Subversion server),
	no user has to deal with the maintenance of the Subversion server.
	You will only need a Subversion client, which is available as
	both a command-line and a GUI tool for many different platforms.
	</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 Wireshark's public (anonymous) Subversion repository is
	separate from the main repository.
	It may take several minutes for committed changes to appear in the
	public repository - so please be patient for a few minutes if you
	desperately need a code change that was committed to the repository
	very recently.
	</para>

  <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 <literal>simple view</literal> on the latest developer version can be
	found at:
	</para>
	<para>
	<ulink url="http://anonsvn.wireshark.org/wireshark/trunk/"/>.
	</para>
	<para>
	A <literal>comprehensive view</literal> 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>
	<filename>trunk</filename> - the very latest source files
	</para></listitem>
	<listitem><para>
	<filename>releases</filename> - the source files of all released versions
	</para></listitem>
	</itemizedlist>
	</para>
  </section>
  </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>Anonymous Subversion access is recommended!</title>
	<para>
	It can make your life much easier, compared to updating 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>Keep your sources "up to date"!</title>
	<para>
	The following ways to retrieve the Wireshark sources are sorted in
	decreasing source timeliness.
	If you plan to commit changes you've made to the sources,
	it's a good idea to keep your private source tree as current as possible.
	</para>
	</note>
	<para>
	The age mentioned in the following sections indicates the age of the
	most recent change in that set of the sources.
	</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="&WiresharkRepositorySite;/wireshark/trunk/"/>.
	</para>
	<para>
	See <xref linkend="ChToolsSubversion"/> on 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 &WiresharkRepositorySite;/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 connection.
	</para>
	</section>

	<section id="ChSrcSVNWeb">
	<title>Anonymous Subversion web interface</title>
	<para>
	Recommended for informational purposes only, as only individual files can
	be downloaded.
	</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="&WiresharkRepositorySite;/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 but not 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: some number of minutes (a bit older than the anonymous Subversion access).
	</para>
	<para>
	The buildbot server will automatically start to generate a snapshot of
	Wireshark's source tree after a source code change is committed.
	These snapshots can be found at: <ulink
	url="&WiresharkDownloadPage;automated/src/"/>.
	</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 the 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="&WiresharkDownloadPage;"/>.
	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 will 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've obtained the Wireshark sources for the first time, you
	might want to keep them in sync with the sources at the Subversion
	repository.
	</para>
	<tip><title>Take a look at the buildbot first!</title>
	<para>
	As development evolves, the Wireshark sources are compilable most of the
	time - but not always.
	You may take a look at the <xref linkend="ChIntroAutomated"/> first,
	to see if the sources are currently in a good shape.
	</para>
	</tip>

	<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 connection. 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 works remarkably well).
	</para>
	</section>

	<section id="ChSrcZipUpdate">
	<title>... from zip files</title>
	<para>
	Independent of the way you retrieve the zip file of the Wireshark sources
	(as described in <xref linkend="ChSrcObtain"/> ), 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 haven'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 haven'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 change 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</title>
	<para>
	The sources contain 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 differ 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 non-standard configuration, you can use:
	<programlisting>
./configure --help
	</programlisting>
	to see what options you have.
	</para>
	</section>

	<section>
	<title>Win32 native</title>
	<para>
	The first thing to do will be to check the file
	<filename>config.nmake</filename> to determine if it reflects your configuration.
	The settings in this file are well documented, so please have a look at
	that file.
	However, if you've installed the libraries and tools as recommended there
	should be no need to edit things here.
	</para>
	<para>
	Many of the file and directory names used in the build process go past the
	old 8.3 naming limitations.
	As a result, you should use the <command>cmd.exe</command> command interpreter
	instead of the old <command>command.com</command>.
	</para>
	<para>
	Be sure that your command-line environment is set up to compile
	and link with MSVC++. When installing MSVC++, you can have your
	system's environment set up to always allow compiling from the
	command line, or you can invoke the vcvars32.bat script, which can
	usually be found in the <filename>VC98\Bin</filename> subdirectory of the
	directory in which Visual Studio was installed.
	</para>
	<para>
	You should then cleanup any intermediate files, which are shipped for
	convenience of Unix users, by typing at the command line prompt (cmd.exe):
	</para>
	<para>
	<prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake distclean</userinput>
	</para>
	<para>
	After doing this, typing at the command line prompt (cmd.exe):
	</para>
	<para>
	<prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake all</userinput>
	</para>
	<para>
	will start the whole Wireshark build process.
	</para>
	<para>
	After the build process has successfully finished, you should find a
	<filename>wireshark.exe</filename> and some other files
	in the root directory.
	</para>
	</section>

  </section>

  <section id="ChSrcRunFirstTime">
	<title>Run generated Wireshark</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>
	<section id="ChSrcRunFirstTimeUnix">
	<title>Unix/Linux</title>
	<para>
	After a successful build you can run Wireshark right from the build
	directory. Still the program would need to know that it's being run from
	the build directory and not from its install location. This has inpact
	on the directories where the program can find the other parts and
	relevant data files.
	</para>
	<para>
	In order to run the Wireshark from the build directory set the environment
	variable <varname>WIRESHARK_RUN_FROM_BUILD_DIRECTORY</varname> and run
	Wireshark. If your platform is properly setup, your build directory and
	current working directory are not in your <varname>PATH</varname>, so the
	commandline to launch Wireshark would be:
	<command>WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./wireshark</command>.
	</para>
	<para>
	There's no need to run Wireshark as root user, you just won't be able to
	capture. When you opt to run Wireshark this way, your terminal output can
	be informative when things don't work as expected.
	</para>
	</section>
	<section id="ChSrcRunFirstTimeWin32">
	<title>Win32 native</title>
	<para>
	During the build all relevant program files are collected in a subdirectory
	<command>wireshark-gtk2</command>. You can run the program from there by
	launching the wireshark.exe executable.
	</para>
	</section>
  </section>

  <section id="ChSrcDebug">
	<title>Debug your generated Wireshark</title>
	<section id="ChSrcUnixDebug">
	<title>Unix/Linux</title>
	<para>
	When you want to investigate a problem with Wireshark you want to load
	the program into your debugger. But loading wireshark into debugger fails
	because of the libtool build environment. You'll have to wrap loading
	wireshark into a libtool command:
	<command>libtool --mode=execute gdb wireshark</command>
	</para>
	<para>
	If you prefer a graphic debugger you can use the Data Display Debugger
	(ddd) instead of GNU debugger (gdb).
	</para>
	<para>
	Additional traps can be set on GLib by setting the <varname>G_DEBUG</varname>
	environment variable:<command>G_DEBUG=fatal_criticals libtool --mode=execute
	ddd wireshark</command>.
	See <ulink url="http://library.gnome.org/devel/glib/stable/glib-running.html"/>
	</para>
	</section>

	<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 are 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>
	<literal>Ask the developer mailing list before you really start a new
	development task.</literal>
	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 someone can give you some tips that
	should be thought about (like side effects that are sometimes very
	hard to see).
	</para>
	</tip>
  </section>

  <section id="ChSrcContribute">
	<title>Contribute your changes</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
	community. You gain the following benefits by contributing your improvements:
	<itemizedlist>
	<listitem><para>
	It's the right thing to do. 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
	you.
	</para></listitem>
	<listitem><para>
	You get free enhancements. By making your code public, other developers
	have a chance to make improvements, as there's always room for
	improvements. In addition someone may implement advanced features on top of
	your code, which can be useful for yourself too.
	</para></listitem>
	<listitem><para>
	You save time and effort. The maintainers and developers of Wireshark
	will maintain your code as well, updating 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.
	</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 upload it to the bug tracker.
	</para>

	<section id="ChSrcDiffWhat">
	<title>What is a diff file (a patch)?</title>
	<para>
	A <ulink url="http://en.wikipedia.org/wiki/Diff">diff file</ulink>
	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 for <filename>file.h</filename> that
	makes the second argument in <function>cf_continue_tail()</function>
	<type>volatile</type>.  It was created using <command>svn diff</command>,
	described below:
	<programlisting>
<![CDATA[
Index: file.h
===================================================================
--- file.h      (revision 21134)
+++ file.h      (revision 22401)
@@ -142,7 +142,7 @@
  * @param err the error code, if an error had occurred
  * @return one of cf_read_status_t
  */
-cf_read_status_t cf_continue_tail(capture_file *cf, int to_read, int *err);
+cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);

 /**
  * Finish reading from "end" of a capture file.
]]>
	</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>
	We prefer to use so called "unified" diff files in Wireshark development,
	three unchanged lines before and after the actual changed parts are
	included. This makes 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 patches. The preferred way is to
	generate them from an updated Subversion tree, since it avoids
	unnecessary integration work.
	</para>

	<section id="ChSrcSVNDiff">
	<title>Using the svn command-line client</title>
	<para>
	<userinput>svn diff [changed_files] > svn.diff</userinput>
	</para>
	<para>
	Use the command line svn client to generate a patch in the required format
	from the changes you've made to your working copy. If you leave out the
	name of the changed file the svn client searches for all changes in the
	working copy and usually produces a patch containing more than just the
	change you want to send. Therefore you should always check the produced
	patch file.
	</para>
	<para>
	If you've added a new file, e.g.
	<filename>packet-myprotocol.c</filename>, you can use <command>svn
	add</command> to add it to your local tree before generating the patch.
	Similarly, you can use <command>svn rm</command> for files that should
	be removed.
	</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 <filename>config.nmake</filename>
	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
	<filename>packet-xxx.c</filename> 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 &WiresharkWebSite;.
	</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 -N -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>-N</entry>
	  <entry>Add new files when used in conjunction with -r.</entry>
	</row>
	<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; they can be listed 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 separate 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 done 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>Submit dissectors as built-in whenever possible.</command>
	  Developing a new dissector as a plugin is a good idea because compiling is
	  quicker, but it's best to convert dissectors to the built-in style before
	  submitting for checkin. This reduces the number of files that must be installed
	  with Wireshark and ensures your dissector will be available on all platforms.
	  </para><para>
	  This is no hard-n-fast rule though. Many dissectors are straightforward so they
	  can easily be put into 'the big pile', while some are ASN.1 based which takes a
	  different approach, and some multiple sourcefile dissectors are more suitable to
	  be placed separate as plugin.
	  </para>
	  </listitem>
	  <listitem><para>
	  <command>Verify that your dissector code does not use prohibited or deprecated APIs</command>
	  This can be done as follows:
	  </para>
	  <para>
	  <userinput>perl &lt;wireshark_root&gt;/tools/checkAPIs.pl &lt;source-filename(s)&gt;</userinput>
	  </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 will randomly change bytes in this file, so that unusual
	  code paths in your dissector are checked. There are tools available to
	  automatically do this on any number of input files, see:
	  <ulink url="&WiresharkWikiSite;/FuzzTesting"/> for details.
	  </para>
	  </listitem>
	</itemizedlist>
	</para>
	</section>

	<section id="ChSrcSend">
	<title>Sending your patch for inclusion</title>
	<para>
	After generating a patch of your changes, you might want to have your
	changes included into the SVN repository.
	</para>
	<para>
	To submit a patch, open a new ticket in the Wireshark bug database at <ulink
	url="&WiresharkBugsSite;/bugzilla/enter_bug.cgi?product=Wireshark"/>.
	You must first create a bug, then attach your patch or patches.
	<itemizedlist>
	  <listitem><para>
	  Set the Product, Priority, and Severity as needed.
	  </para></listitem>
	  <listitem><para>
	  Add a Summary and Description, and create a bug using the
	  <guibutton>Commit</guibutton> button. If your code has passed fuzz
	  testing, please say so in the description.
	  </para></listitem>
	  <listitem><para>
	  Once the bug has been created, select <guibutton>Create a New Attachment</guibutton>
	  and upload your patch or patches.  Set the <command>review_for_checkin</command>
	  flag to <command>?</command>.  If you skip this step, your patch won't show up in the
	  patch request queue.
	  </para></listitem>
	  <listitem><para>
	  If possible and applicable, attach a capture file that demonstrates
	  your new feature or protocol.
	  </para></listitem>
	  <listitem><para>
	  Don't set the bug's status to ASSIGNED and don't assign the bug to
	  yourself--if you do the latter, the core developers won't see the
	  updates made to the bug.
	  </para></listitem>
	</itemizedlist>
	</para>
	<!--
	<tip><title>Tip!</title>
	<para>
	Setting the <command>review_for_checkin</command> is important.
	Without it, your patch won't show up in the <ulink url="http://bugs.wireshark.org/bugzilla/request.cgi?action=queue&amp;requester=&amp;product=&amp;type=review_for_checkin&amp;requestee=&amp;component=&amp;group=type">pending
	patch request queue</ulink>.
	</para>
	</tip>
	-->
	<para>
	You might get one of the following responses to your patch request:
	<itemizedlist>
	  <listitem><para>
	  Your patch is checked into the SVN repository. Congratulations!
	  </para></listitem>
	  <listitem><para>
	  You are asked to provide additional information, capture files, or
	  other material. If you haven't fuzzed your code, you may be asked
	  to do so.
	  </para></listitem>
	  <listitem><para>
	  Your patch is rejected. You should get a response with the reason
	  for rejection.  Common reasons include not following the style
	  guide, buggy or insecure code, and code that won't compile on other
	  platforms. In each case you'll have to fix each problem and upload
	  another patch.
	  </para></listitem>
	  <listitem><para>
	  You don't get any response to your patch.
	  Possible reason: Don't worry, if your patch is in the bug tracker, it
	  won't get lost.  But it may be that all the core developers are busy
	  (e.g., with their day jobs or family or...) and haven't had time to
	  look at your patch.  If you're concerned, feel free to add a comment
	  to the patch or send an email to the developer's list asking for
	  status.  But please be patient: most if not all of us do this in our
	  "spare" time.
	  </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>
	<section id="ChSrcPatchUse">
	<title>Using patch</title>
	<para>
	Given the file <filename>new.diff</filename> containing a unified diff,
	the right way to call the patch tool depends on what the pathnames in
	<filename>new.diff</filename> look like.
	If they're relative to the top-level source directory - for example, if a
	patch to <filename>prefs.c</filename> just has <filename>prefs.c</filename>
	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
	<filename>wireshark.orig/prefs.c</filename> and
	<filename>wireshark.mine/prefs.c</filename>, you'd run it with:
	</para>
	<para>
    <userinput>patch -p1 &lt;new.diff</userinput>
	</para>
	<para>
	If they're relative to a <literal>subdirectory</literal> of the top-level
	directory, you'd run <command>patch</command> in <literal>that</literal>
	directory and run it with <parameter>-p0</parameter>.
	</para>
	<para>
	If you run it without <parameter>-p</parameter> at all, the patch tool
	flattens path names, so that if you
	have a patch file with patches to <filename>Makefile.am</filename> and
	<filename>wiretap/Makefile.am</filename>,
	it'll try to apply the first patch to the top-level
	<filename>Makefile.am</filename> and then apply the
	<filename>wiretap/Makefile.am</filename> patch to the top-level
	<filename>Makefile.am</filename> as well.
	</para>
	<para>
	At which position in the filesystem should the patch tool 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 <literal>subdirectory</literal> - 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 <literal>NOT</literal> submit patches like
	that - especially if they're only patching files that exist in multiple
	directories, such as <filename>Makefile.am</filename>.
	</para>
	</section>
  </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="ChSrcContribute"/>. 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&#36;
</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>
	The Debian Package is built using dpkg-buildpackage, based on information
	found in the source tree under <filename>debian</filename>. See
	<ulink url="http://www.debian-administration.org/articles/336"/> for a
	more in-depth discussion of the build process.
	</para>
	<para>
	In the wireshark directory, type:
	</para>
	<para>
	<prompt>$</prompt> <userinput>make debian-package</userinput>
	</para>
	<para>
	to build the Debian Package.
	</para>
	</section>

	<section id="ChSrcRpm">
	<title>Red Hat: .rpm packages</title>
	<para>
	The RPM is built using rpmbuild (http://www.rpm.org/), which comes as standard on many flavours of Linux, including
	Red Hat and Fedora. The process creates a clean build environment in <filename>packaging/rpm/BUILD</filename> every
	time the RPM is built. The settings controlling the build are in <filename>packaging/rpm/SPECS/wireshark.spec.in</filename>. After editing the settings in this file, <filename>./configure</filename> must be run again in the wireshark directory to generate the actual specification script.
	</para>
	<warning><title>Warn!</title><para>
	The SPEC file contains settings for the <filename>configure</filename> used to set the RPM build environment. These are
	completely independent of any settings passed to the usual Wireshark <filename>./configure</filename>.</para></warning>
	<para>
	In the wireshark directory, type:
	</para>
	<para>
	<prompt>$</prompt> <userinput>make rpm-package</userinput>
	</para>
	<para>
	to build the RPM. Once it is done, there will be a message stating where the built RPM can be found.
	</para>
	<tip><title>Tip!</title>
	<para>
	Because this does a clean build, as well as constructing the package, this can take quite a long time.
	</para>
	</tip>
	</section>

	<section id="ChSrcOSX">
	<title>MAC OS X: .dmg packages</title>
	<para>
	The MAC OS X Package is built using OS X packaging tools, based on information
	found in the source tree under <filename>packaging/macosx</filename>.
	</para>
	<para>
	In the wireshark directory, type:
	</para>
	<para>
	<prompt>$</prompt> <userinput>make osx-package</userinput>
	</para>
	<para>
	to build the MAC OS X Package.
	</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 MAKENSIS setting in the
	<filename>config.nmake</filename> file to specify where the NSIS binaries
	are installed.
	</para>
	<para>
	In the wireshark 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>wireshark-setup-&WiresharkCurrentVersion;.exe</filename> in
	the <filename>packaging/nsis</filename> directory.
	</para>
	</section>

  </section>

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