wireshark/docbook/dg-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 how to:
	<itemizedlist>
	<listitem><para>
	look at the source
	</para></listitem>
	<listitem><para>
	get the source
	</para></listitem>
	<listitem><para>
	compile the source
	</para></listitem>
	<listitem><para>
	...
	</para></listitem>
	</itemizedlist>
	However, it will not explain the source file contents in detail, such as 
	where to find a specific functionality. This is done in 
	<xref linkend="PartDevelopment"/>.
	</para>
  </section>
	
  <section id="ChSrcSVNServer">
	<title>The Ethereal subversion (SVN) server</title>
	<para>
	The Ethereal source code is stored inside Ethereal project's Subversion 
	(SVN) server at svn.ethereal.com. SVN is used to keep track of the changes 
	made to the source code. There is a book on subversion available at:
	<ulink url="http://svnbook.red-bean.com/"/>
	</para>
	<para>
	The svn server makes it possible to get the source files from any previous 
	release, see which person changed a specific piece of code, or a lot more 
	things related to the history of the source code development.
	</para>
	<para>
	There are several ways to have a look at and obtain the sources from this 
	server. Please note that the anonymous SVN repository is separate from 
	the main repository. It may take several minutes for committed changes to 
	appear in the anonymous repository. 
	</para>
	<tip><title>Tip!</title>
	<para>
	The Ethereal project has switched from CVS (Concurrent versioning system) 
	to SVN some time ago. You may still find old references to CVS in the 
	Ethereal documentation and source files.
	</para>
	</tip>
  </section>
	
  <section id="ChSrcQuickLook">
	<title>A quick look at the Ethereal sources</title>
	<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="ChSrcObtaining">
	<title>Obtaining the Ethereal sources</title>
	<para>
	There are several ways to obtain the sources from the SVN 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 (SVN) access</title>
	<para>
	Recommended for development purposes.
	</para>
	<para>
	Age: a few minutes.
	</para>
	<para>
	You can use a a Subversion client to download the source code from 
	Ethereal's anonymous SVN repository. The URL for the repository trunk is:
	<ulink url="http://anonsvn.ethereal.com/ethereal/trunk"/>.
	</para>
	<para>
	Even
	"Read-Only" SVN access can make your life much easier, compared to
	merge sources by hand everytime you do an update using a zip file. SVN
	handles merging
	of changes into your personal sourcetree in a very comfortable way. So
	you can update your sourcetree several times a day without much
	effort, compared to use the zipped sources.
	</para>
	<para>
	See <xref linkend="ChToolsSubversion"/> how to install a subversion client.
	</para>
	<para>
	For example, to check out using the command-line Subversion client, you 
	would type:
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn checkout http://anonsvn.ethereal.com/ethereal/trunk ethereal</userinput>
	</para>
	<para>
	The checkout has to be only done once. This will copy all the sources of 
	the latest version (including directories) from the server to your machine.
	This will take some time, depending on the speed of your internet line.
	</para>
	<para>
	After this first time checkout is done, you only need to update your 
	sources 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, svn will try to merge the changes from outside into 
	your private file (this is working remarkably well).
	</para>
	</section>

	<section id="ChSrcSVNWeb">
	<title>Subversion web interface</title>
	<para>
	Age: a few minutes (same as anonymous subversion access).
	</para>
	<para>
	 The entire source tree 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>
	Age: up to 24 hours.
	</para>
	<para>
	The SVN server will automatically generate a snapshot of the SVN
	sourcetree every night. These snapshots can be found at: <ulink
	url="http://www.ethereal.com/distribution/nightly-builds/"/>.
	</para>
	<para>
	If anonymous SVN 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 latest SVN 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 SVN server are keep on growing until the next release is done (at
	the release time, the released and latest SVN versions are then
	identical 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>
	<para>
	The following steps for the first time generation differs on the two
	major platforms.
	</para>
	
	<section>
	<title>Unix platforms</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 platforms</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. XXX - add the settings everyone typical has to change 
	(only very few).
	</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="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 one
	of the following chapters.
	</para>
	<para>
	If you have an idea what and how you want to add/change something, it
	might be a good idea to ask the developer mailing list before
	you really start implementing it. Someone else might already working on
	the same topic,
	or can give you some tips what should be thought about too (like side
	effects that are sometimes very hard to see).
	</para>
  </section>

  <section id="ChSrcCommit">
	<title>Committing 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
	server.
	</para>
	<para>
	You gain two 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 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 server. 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>
	<para>
	Before submitting your changes, please read the "Portability" section of 
	doc/README.developer - as that section notes:
	</para>
	<para>
    Ethereal runs on many platforms, and can be compiled with a number of 
	different compilers; here are some rules for writing code that will work 
	on multiple platforms. 
	</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>

	<section id="ChSrcSVN">
	<title>Generate a diff file (a patch)</title>
	<para>
	There are several ways to generate such a patch.

	<tip><title>Tip!</title>
	<para>The diff file containing all changes is often also called a patch.
	</para>
	</tip>
	</para>

	<section id="ChSrcSVNDiff">
	<title>Using the svn command-line client</title>
	<para>
	svn diff > your-changes.patch
	XXX - add more details
	</para>
	</section>

	<section id="ChSrcSVNGUIDiff">
	<title>Using the diff feature of the GUI subverion clients</title>
	<para>
	Most (if not all) of the GUI subversion clients (RapidSVN, TortoiseSVN, ...) 
	have a built-in "diff" feature.
	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
	config.nmake file.
	</para>
	<para>
	The diff tool has several options, you will get a complete list with:
	</para>
	<para>
	<userinput>diff --help</userinput>

	<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>
	</section>

	</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>
	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 could be: <filename>packet-foo-datatypes.diff</filename>.
	</para>
	<para>
	You should send an email to <ulink
	url="mailto:ethereal-dev[AT]ethereal.com"/>
	with a description of your changes and the reasons for it and with your
	diff file as an attachment. Don't include your diff file 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 server sources, so
	the latest SVN versions and
	the 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 :-)
	  </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 
	  compilable 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 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>
	  ask the developer mailing list before starting a new task, as
	  someone might already be working on your desired topic (this might
	  reduce double effort)
	  </para></listitem>
	  <listitem><para>
	  explain why your change is needed (don't worry if your change
	  seems to be needed only by yourself, other's might find it helpful too)
	  </para></listitem>
	  <listitem><para>
	  keep your own sources up to date (use the latest SVN sources)
	  before making a patch, as this makes it usually much easier to apply
	  your patch
	  </para></listitem>
	  <listitem><para>
	  find a good descriptive filename for your diff file as described
	  above
	  </para></listitem>
	  <listitem><para>
	  follow the source code style guide and other documented tips
	  </para></listitem>
	  <listitem><para>
	  don't put a lot of unrelated things into one large patch, as a few 
	  smaller patches are usually easier to apply (but don't put every 
	  changed line into a seperate patch :-)
	  </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>

  <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
	</para>
	</section>

	<section id="ChSrcRpm">
	<title>Red Hat: .rpm packages</title>
	<para>
	XXX
	</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. It 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 config.nmake 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. Please be patient while the compression is
	done, it will take some time (a few minutes!) even on fast machines.
	</para>
	<para>
	You will hopefully now see something like:
	<filename>ethereal-setup-&EtherealCurrentVersion;.exe</filename> in
	the <filename>packaging/nsis</filename> directory.
	</para>
	</section>

  </section>

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