path: root/docbook/edg_src/EDG_chapter_sources.xml

<!-- 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>&gt;</prompt> <userinput>nmake -f Makefile.nmake all</userinput>
	</para>
	<para>
	will start the whole Ethereal build process.
	</para>
	<para>
	After the build process successfully finished, you should find an 
	<filename>ethereal.exe</filename> and some other files
	in the root directory.
	</para>
	</section>
	
  </section>

  <section id="ChSrcRunFirstTime">
	<title>Run generated Ethereal for the first time</title>
	<tip><title>Tip!</title>
	<para>
	An already installed Ethereal may interfere with your newly generated 
	version in various ways. If you have any problems getting your Ethereal 
	running the first time, it might be a good idea to remove the previously 
	installed version first.
	</para>
	</tip>
	<para>
	XXX - add more info here.
	</para>
  </section>
	
  <section id="ChSrcDebug">
	<title>Debug your generated Ethereal</title>
	<para>
	See the above info on running Ethereal.
	</para>
	<para>
	XXX - add more info here.
	</para>
	
	<section id="ChSrcWin32Debug">
	<title>Win32 native</title>
	<para>
	XXX - add more info here.
	</para>
	</section>
  </section>
	
  <section id="ChSrcChange">
	<title>Make changes to the 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 &gt; foo.diff</userinput>
	</para>
	<para>
	To get a diff file for your complete directory (including
	subdirectories), you could type something like this:
	</para>
	<para>
	<userinput>diff -r -u --strip-trailing-cr ./svn-dir ./working-dir &gt; foo.diff</userinput>
	</para>
	<para>
	It's a good idea to do a <userinput>make distclean</userinput> before the 
	actual diff call, as this will remove a lot
	of temporary files which might be otherwise included in the diff. After
	doing the diff, you should edit the <filename>foo.diff</filename>
	file and remove unnecessary things, like your private changes to the
	<filename>config.nmake</filename> file.
	</para>
	<para>
	<table frame='all'><title>Some useful diff options</title>
	<tgroup cols='2' align='left' colsep='1' rowsep='1'>
	<colspec colname='c1'/>
	<colspec colname='c2'/>
	<thead>
	<row>
	  <entry>Option</entry>
	  <entry>Purpose</entry>
	</row>
	</thead>
	<tbody>
	<row>
	  <entry>-r</entry>
	  <entry>Recursively compare any subdirectories found.</entry>
	</row>
	<row>
	  <entry>-u</entry>
	  <entry>Output unified context.</entry>
	</row>
	<row>
	  <entry>--strip-trailing-cr</entry>
	  <entry>Strip trailing carriage return on input. This is useful for Win32
	  </entry>
	</row>
	<row>
	  <entry>-x PAT</entry>
	  <entry>Exclude files that match PAT.
	  This could be something like -x *.obj to exclude all win32 object files.
	  </entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</para>
	<para>
	The diff tool has a lot options, you will get a list with:
	</para>
	<para>
	<userinput>diff --help</userinput>	
	</para>
	</section>

	</section>

	<section id="ChSrcGoodPatch">
	<title>Some tips for a good patch</title>
	<para>
	Some tips that will make the merging of your changes into the 
	SVN tree much more likely (and you want exactly that, don't you :-):
	<itemizedlist>
	  <listitem><para>
	  <command>Use the latest SVN sources, or alike.</command>
	  It's a good idea to work with the same sources that are used by the 
	  other developer's, this makes it usually much easier to apply your 
	  patch. For information about the different ways to get the sources,
	  see <xref linkend="ChSrcObtain"/>.
	  </para></listitem>
	  <listitem><para>
	  <command>Update your SVN sources just before making a patch.
	  </command> For the same reasons as the previous point.
	  </para></listitem>
	  <listitem><para>
	  <command>Do a "make clean" before generating the patch.</command>
	  This removes a lot of unneeded intermediate files (like object files) 
	  which can confuse the diff tool generating a lot of unneeded stuff which 
	  you have to remove by hand from the patch again.
	  </para></listitem>
	  <listitem><para>
	  <command>Find a good descriptive filename for your patch.</command> 
	  Think a moment to find a proper name for your patch file. Often a 
	  filename like <filename>ethereal.diff</filename> is used, which isn't 
	  really helpful if keeping several of these files and find the right 
	  one later. For example: If you want to commit changes to the datatypes 
	  of dissector foo, a good filename might be: 
	  <filename>packet-foo-datatypes.diff</filename>.
	  </para></listitem>
	  <listitem><para>
	  <command>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 &lt;new.diff</userinput>
	</para>
	<para>
	If they're relative to a higher-level directory, you'd replace 0 with the 
	number of higher-level directories in the path, e.g. if the names are 
	"ethereal.orig/prefs.c" and "ethereal.mine/prefs.c", you'd run it with:
	</para>
	<para>
    <userinput>patch -p1 &lt;new.diff</userinput>
	</para>
	<para>
	If they're relative to a <command>subdirectory</command> of the top-level 
	directory, you'd run "patch" in <command>that</command> directory and run 
	it with "-p0".
	</para>
	<para>
	If you run it without "-p" at all, the patch tool flattens path names, so 
	that if you 
	have a patch file with patches to "Makefile.am" and "wiretap/Makefile.am", 
	it'll try to apply the first patch to the top-level "Makefile.am" and then 
	apply the "wiretap/Makefile.am" patch to the top-level "Makefile.am" as 
	well.  
	</para>
	<para>
	At which position in the filesystem has the patch tool to be called?
	</para>
	<para>
	If the pathnames are relative to the top-level source directory, or to a 
	directory above that directory, you'd run it in the top-level source 
	directory.
	</para>
	<para>
	If they're relative to a <command>subdirectory</command> - for example, 
	if somebody did a patch to "packet-ip.c" and ran "diff" or "svn diff" in 
	the "epan/dissectors" directory - you'd run it in that subdirectory.  
	It is preferred that people <command>NOT</command> submit patches like 
	that - especially if they're only patching files that exist in multiple 
	directories, such as "Makefile.am".
	</para>
	<para>
	One other thing to note - "cvs diff" produces output that at least some
	versions of "patch" can't handle; you'd get something such as
	<programlisting>
<![CDATA[
Index: missing/dlnames.c
===================================================================
RCS file: /tcpdump/master/tcpdump/missing/dlnames.c,v
retrieving revision 1.5
diff -c -r1.5 dlnames.c
*** missing/dlnames.c   18 Nov 2003 23:09:43 -0000      1.5
--- missing/dlnames.c   31 Aug 2004 21:45:16 -0000
***************
]]>
	</programlisting>
	from "cvs diff -c", and something similar from "cvs diff -u", and "patch",
	unfortunately, would use the "diff -c" or "diff -u" line and try to patch
	"dlnames.c" in the directory you're in, rather than in the "missing"
	subdirectory.
	</para>
	<para>
	For "cvs diff -c" or "cvs diff -u" diffs, there's a Python script
	"cvsdiff-fix.py" in the "tools" directory in the 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>&gt;</prompt> <userinput>nmake -f makefile.nmake packaging</userinput>
	</para>
	<para>
	to build the installer. 
	</para>
	<tip><title>Tip!</title>
	<para>
	Please be patient while the compression is
	done, it will take some time (a few minutes!) even on fast machines.
	</para>
	</tip>
	<para>
	If everything went well, you will now find something like:
	<filename>ethereal-setup-&EtherealCurrentVersion;.exe</filename> in
	the <filename>packaging/nsis</filename> directory.
	</para>
	</section>

  </section>

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