add a warning, that patch and sources files must have the same line endings (CR/NL)
[obnox/wireshark/wip.git] / docbook / edg_src / EDG_chapter_sources.xml
1 <!-- EDG Chapter Sources -->
2 <!-- $Id$ -->
3
4 <chapter id="ChapterSources">
5   <title>Work with the Ethereal sources</title>
6
7   <section id="ChSrcIntro">
8         <title>Introduction</title>
9         <para>
10         This chapter will explain how to work with the Ethereal source code.
11         It will show you how to:
12         <itemizedlist>
13         <listitem><para>
14         get the source
15         </para></listitem>
16         <listitem><para>
17         compile the source
18         </para></listitem>
19         <listitem><para>
20         submit changes
21         </para></listitem>
22         <listitem><para>
23         ...
24         </para></listitem>
25         </itemizedlist>
26         However, this chapter will not explain the source file contents in detail, 
27         such as where to find a specific functionality. This is done in 
28         <xref linkend="ChCodeOverview"/>.
29         </para>
30   </section>
31         
32   <section id="ChSrcSVNServer">
33         <title>The Ethereal Subversion repository</title>
34         <para>
35         Subversion is used to keep track of the changes made to the Ethereal 
36         source code. The Ethereal source code is stored inside Ethereal project's 
37         Subversion repository located at a server at the ethereal.com domain.
38         </para>
39         <para>
40         To qoute the Subversion book about "What is Subversion?": 
41         </para>
42         <para>
43         <quote>Subversion is a free/open-source version control system. That is, 
44         Subversion manages files and directories over time. A tree of files is 
45         placed into a central repository. The repository is much like an ordinary 
46         file server, except that it remembers every change ever made to your files 
47         and directories. This allows you to recover older versions of your data, 
48         or examine the history of how your data changed. In this regard, many 
49         people think of a version control system as a sort of "time machine".
50         </quote>
51         </para>
52         <tip><title>Tip!</title>
53         <para>
54         Subversion is often abbreviated as SVN, as the command-line tools are 
55         abbreviated that way. You will find both terms with the same meaning in 
56         this book, in mailing list discussions and elsewhere.
57         </para>
58         </tip>
59         <para>
60         Using Ethereal's Subversion repository you can:
61         <itemizedlist>
62         <listitem><para>
63         keep your private sources uptodate with very little effort
64         </para></listitem>
65         <listitem><para>
66         get a mail notification if someone changes the latest sources
67         </para></listitem>
68         <listitem><para>
69         get the source files from any previous release (or any other point in time)
70         </para></listitem>
71         <listitem><para>
72         have a quick look at the sources using a web interface
73         </para></listitem>
74         <listitem><para>
75         see which person changed a specific piece of code
76         </para></listitem>
77         <listitem><para>
78         ... and a lot more things related to the history of the Ethereal source 
79         code development
80         </para></listitem>
81         </itemizedlist>
82         </para>
83         <para>
84         The way Ethereal uses Subversion, it can be parted into a client and a 
85         server part. Thanks to Gerald Combs (the maintainer of the Subversion 
86         server), no user usually has to deal with the
87         Subversion server. You will only need a Subversion client, which is 
88         available as a command-line tool for many different platforms. GUI based 
89         tools also becoming more and more available these days.
90         </para>
91         <para>
92         For further reference about Subversion, have a look at the homepage of the 
93         Subversion project: <ulink url="http://subversion.tigris.org/"/>. There 
94         is a good and free book about it available at: <ulink 
95         url="http://svnbook.red-bean.com/"/>.
96         </para>
97         <para>
98         Please note that the anonymous Subversion repository is separate from 
99         the main repository. It may take several minutes for committed changes to 
100         appear in the anonymous repository. XXX - be more specific here.
101         </para>
102         <tip><title>Tip!</title>
103         <para>
104         As the Ethereal project has switched from CVS (Concurrent versioning 
105         system) to Subversion some time ago, you may still find old references to 
106         CVS in the Ethereal documentation and source files.
107         </para>
108         </tip>
109   </section>
110         
111   <section id="ChSrcWebInterface">
112         <title>The web interface to the Subversion repository</title>
113         <para>
114         If you need a quick look at the Ethereal source code, 
115         you will only need a Web browser.
116         </para>
117         <para>
118         A <command>simple view</command> on the latest developer version can be 
119         found at: 
120         </para>
121         <para>
122         <ulink url="http://anonsvn.ethereal.com/ethereal/trunk/"/>.
123         </para>
124         <para>
125         A <command>comprehensive view</command> of all source versions 
126         (e.g. including the capability to show differences between versions) 
127         is available at:
128         </para>
129         <para>
130         <ulink url="http://anonsvn.ethereal.com/viewcvs/viewcvs.py/"/>. 
131         </para>
132         <para>
133         Of special interest might be the subdirectories:
134         <itemizedlist>
135         <listitem><para>
136         trunk - the very latest source files
137         </para></listitem>
138         <listitem><para>
139         releases - the source files of all released versions
140         </para></listitem>
141         </itemizedlist>
142         </para>
143   </section>    
144
145   <section id="ChSrcObtain">
146         <title>Obtain the Ethereal sources</title>
147         <para>
148         There are several ways to obtain the sources from Ethereal's Subversion 
149         server.
150         </para>
151         <note><title>Note!</title>
152         <para>
153         The following ways to retrieve the Ethereal sources are sorted in 
154         decreasing 
155         actuality. If you plan to commit changes you've made to the sources,
156         it's a good idea to keep your private source tree as actual as possible.
157         </para>
158         </note>
159         <para>
160         The age mentioned in the following sections will indicate, how old the 
161         most recent change in that sources will be. 
162         </para>
163         
164         <section id="ChSrcAnon">
165         <title>Anonymous Subversion access</title>
166         <para>
167         Recommended for development purposes.
168         </para>
169         <para>
170         Age: a few minutes.
171         </para>
172         <para>
173         You can use a Subversion client to download the source code from 
174         Ethereal's anonymous Subversion repository. The URL for the repository 
175         trunk is:
176         <ulink url="http://anonsvn.ethereal.com/ethereal/trunk/"/>.
177         </para>
178         <tip><title>Tip!</title>
179         <para>
180         Anonymous Subversion access can make your life much easier, compared to
181         update your source tree by using any of the zip file methods mentioned 
182         below.
183         Subversion handles merging of changes into your personal source tree in a 
184         very comfortable and quick way. So you can update your source tree several 
185         times a day without much effort.
186         </para>
187         </tip>
188         <para>
189         See <xref linkend="ChToolsSubversion"/> how to install a Subversion client.
190         </para>
191         <para>
192         For example, to check out using the command-line Subversion client, you 
193         would type:
194         </para>
195         <para>
196         <prompt>$</prompt> 
197         <userinput>svn checkout http://anonsvn.ethereal.com/ethereal/trunk ethereal</userinput>
198         </para>
199         <para>
200         The checkout has to be only done once. This will copy all the sources of 
201         the latest version (including directories) from the server to your machine.
202         This will take some time, depending on the speed of your internet line.
203         </para>
204         </section>
205
206         <section id="ChSrcSVNWeb">
207         <title>Anonymous Subversion web interface</title>
208         <para>
209         Recommended for development purposes, if direct Subversion access isn't 
210         possible (e.g. because of a restrictive firewall).
211         </para>
212         <para>
213         Age: a few minutes (same as anonymous Subversion access).
214         </para>
215         <para>
216          The entire source tree of the Subversion repository is available via a 
217          web interface at:
218          <ulink url="http://anonsvn.ethereal.com/viewcvs/viewcvs.py/"/>. 
219          You can view 
220          each revision of a particular file, as well as diffs between different 
221          revisions. You can also download individual files or entire directories.
222         </para>
223         </section>      
224          
225         <section id="ChSrcNightly">
226         <title>Nightly snapshots</title>
227         <para>
228         Well, not recommended at all.
229         </para>
230         <para>
231         Age: up to 24 hours.
232         </para>
233         <para>
234         The Subversion server will automatically generate a snapshot of Ethereal's
235         sourcetree every night. These snapshots can be found at: <ulink
236         url="http://www.ethereal.com/distribution/nightly-builds/"/>.
237         </para>
238         <para>
239         If anonymous Subversion access isn't possible, e.g. if the connection to 
240         the server isn't possible because of a corporate firewall, the sources 
241         can be obtained by downloading this nightly snapshots. However, if you are
242         going to maintain your sources in parallel to the "official" sources
243         for some time, it's recommended to use the anonymour Subversion access if
244         possible (believe it, it will save you a lot of time).
245         </para>
246         </section>
247
248
249         <section id="ChSrcReleased">
250         <title>Released sources</title>
251         <para>
252         Recommended for productive purposes.
253         </para>
254         <para>
255         Age: from days to weeks.
256         </para>
257         <para>
258         The officially released source files can be found at: <ulink
259         url="http://www.ethereal.com/download.html"/>.
260         You should use these sources if you want to build Ethereal on your
261         platform for productive use.
262         </para>
263         <para>
264         The differences between the released sources and the sources stored at
265         the Subversion repository are keep on growing until the next release is 
266         done (at the release time, the released and latest Subversion repository
267         versions are then identical again :-).
268         </para>
269         </section>
270
271   </section>
272
273   <section id="ChSrcUpdating">
274         <title>Update the Ethereal sources</title>
275         <para>
276         After you obtained the Ethereal sources for the first time, you 
277         might want to keep them in sync with the sources at the Subversion 
278         repository.
279         </para>
280         
281         <section id="ChSrcAnonUpdate">
282         <title>... with Anonymous Subversion access</title>
283         <para>
284         After the first time checkout is done, updating your 
285         sources is simply done by typing (in the Ethereal source dir):
286         </para>
287         <para>
288         <prompt>$</prompt> 
289         <userinput>svn update</userinput>
290         </para>
291         <para>
292         This will only take a few seconds, even on a slow internet line. It will 
293         replace old file versions by new ones. If you and someone else have 
294         changed the same file since the last update, Subversion will try to merge 
295         the changes into your private file (this is working remarkably well).
296         </para>
297         </section>
298
299         <section id="ChSrcZipUpdate">
300         <title>... from zip files</title>
301         <para>
302         Independant of the way you retrieve the zip file of the Ethereal sources
303         (as <xref linkend="ChSrcObtain"/> is providing several ways), the way to 
304         bring the changes from the official sources into your personal source tree
305         is identical.
306         </para>
307         <para>
308         First of all, you will download the new zip file of the official sources
309         the way you did it the first time.
310         </para>
311         <para>
312         If you didn't changed anything in the sources, you could simply throw 
313         away your old sources and reinstall everything just like the first time.
314         But be sure, that you really didn't changed anything. It might be a good
315         idea to simply rename the "old" dir to have it around, just in case you 
316         remember later that you really did changed something before.
317         </para>
318         <para>
319         Well, if you did change something in your source tree, you have to merge 
320         the official changes 
321         since the last update into your source tree. You will install the content 
322         of the zip file into a new directory and use a good merge tool (e.g. 
323         <ulink url="http://winmerge.sourceforge.net/"/> for Win32) to bring 
324         your personal source tree in sync with the official sources again. 
325         </para>
326         </section>
327
328   </section>
329
330   <section id="ChSrcBuildFirstTime">
331         <title>Build Ethereal for the first time</title>
332         <para>
333         The sources contains several documentation files, it's a good idea to
334         look at these files first.
335         </para>
336         <para>
337         So after obtaining the sources, tools and libraries, the
338         first place to look at is <filename>doc/README.developer</filename>,
339         here you will get the latest infos for Ethereal development for all
340         supported platforms.
341         </para>
342         <tip><title>Tip!</title>
343         <para>
344         It is a very good idea, to first test your complete build environment 
345         (including running and debugging Ethereal) before doing any changes 
346         to the source code (unless otherwise noted).
347         </para>
348         </tip>
349         <para>
350         The following steps for the first time generation differs on the two
351         major platforms.
352         </para>
353         
354         <section>
355         <title>Unix</title>
356         <para>
357         Run the autogen.sh script at the top-level ethereal directory to configure 
358         your build directory.
359         <programlisting>
360 ./autogen.sh
361 ./configure
362 make 
363         </programlisting>
364         </para>
365         </section>
366         
367         <section>
368         <title>Win32 native</title>
369         <para>
370         The place to look at is <filename>doc/README.win32</filename>, 
371         you will get the latest infos for generation on the win32
372         platforms.
373         </para>
374         <para>
375         The next thing to do will be editing the file 
376         <filename>config.nmake</filename> to reflect your configuration.
377         The settings in this file are well documented, so please have a look at 
378         that file.
379         </para>
380         <para>
381         After doing this, typing inside the command line (cmd.exe):
382         </para>
383         <para>
384         <prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake all</userinput>
385         </para>
386         <para>
387         will start the whole Ethereal build process.
388         </para>
389         <para>
390         After the build process successfully finished, you should find an 
391         <filename>ethereal.exe</filename> and some other files
392         in the root directory.
393         </para>
394         </section>
395         
396   </section>
397
398   <section id="ChSrcRunFirstTime">
399         <title>Run generated Ethereal for the first time</title>
400         <tip><title>Tip!</title>
401         <para>
402         An already installed Ethereal may interfere with your newly generated 
403         version in various ways. If you have any problems getting your Ethereal 
404         running the first time, it might be a good idea to remove the previously 
405         installed version first.
406         </para>
407         </tip>
408         <para>
409         XXX - add more info here.
410         </para>
411   </section>
412         
413   <section id="ChSrcDebug">
414         <title>Debug your generated Ethereal</title>
415         <para>
416         See the above info on running Ethereal.
417         </para>
418         <para>
419         XXX - add more info here.
420         </para>
421         
422         <section id="ChSrcWin32Debug">
423         <title>Win32 native</title>
424         <para>
425         XXX - add more info here.
426         </para>
427         </section>
428   </section>
429         
430   <section id="ChSrcChange">
431         <title>Make changes to the Ethereal sources</title>
432         <para>
433         As the Ethereal developers working on many different platforms, a lot of 
434         editors are used to develop Ethereal (emacs, vi, Microsoft Visual Studio
435         and many many others). There's no "standard" or "default" development 
436         environment.
437         </para>
438         <para>
439         There are several reasons why you might want to change the Ethereal
440         sources:
441         <itemizedlist>
442           <listitem><para>add your own new dissector</para></listitem>
443           <listitem><para>change/extend an existing dissector</para></listitem>
444           <listitem><para>fix a bug</para></listitem>
445           <listitem><para>implement a new glorious feature :-)</para></listitem>
446         </itemizedlist>
447         The internal structure of the Ethereal sources will be described in 
448         <xref linkend="PartDevelopment"/>.
449         </para>
450         <tip><title>Tip!</title>
451         <para>
452         <command>Ask the developer mailing list before you really start a new 
453         development task.</command>     
454         If you have an idea what you want to add/change, it's a good idea to 
455         contact the developer mailing list 
456         (see <xref linkend="ChIntroMailingLists"/>) 
457         and explain your idea. Someone else might already be working on the same 
458         topic, so double effort can be reduced, or can give you some tips what 
459         should be thought about too (like side effects that are sometimes very 
460         hard to see).
461         </para>
462         </tip>
463   </section>
464
465   <section id="ChSrcCommit">
466         <title>Commit changed sources</title>
467         <para>
468         If you have finished changing the Ethereal sources to suit your needs,
469         you might want to contribute your changes back to the Ethereal SVN
470         repository.
471         </para>
472         <para>
473         You gain the following benefits by contributing your improvements back to 
474         the community:
475         <itemizedlist>
476         <listitem><para>
477         Other people who find your contributions useful will appreciate
478         them, and you will know that you have helped people in the same way
479         that the developers of Ethereal have helped people
480         </para></listitem>
481         <listitem><para>
482         The developers of Ethereal might improve your changes even more, as 
483         there's always room for improvements. Or they may implement some advanced 
484         things on top of your code, which can be useful for yourself too.
485         </para></listitem>
486         <listitem><para>
487         The maintainers and developers of Ethereal will maintain your code as 
488         well, fixing it when API changes or other changes are made, and generally 
489         keeping it in tune with what is happening with Ethereal. So if Ethereal is 
490         updated (which is done often), you can get a new Ethereal version from 
491         the website and your changes will already be included without any effort 
492         for you. The maintainers and developers of Ethereal will maintain your
493         code as well, fixing it when API changes or other changes are made, and
494         generally keeping it in tune with what is happening with Ethereal.
495         </para></listitem>
496         </itemizedlist>
497         There's no direct way to commit changes to the SVN repository. Only a few
498         people are authorised to actually
499         make changes to the source code (check-in changed files). If you want
500         to submit your changes, you should make a diff file (a patch) and send
501         it to
502         the developer mailing list.     
503         </para>
504
505         <section id="ChSrcDiffWhat">
506         <title>What is a diff file (a patch)?</title>
507         <para>
508         A diff file is a plain text file containing the differences between a 
509         pair of files (or multiple of such pairs). 
510         <tip><title>Tip!</title>
511         <para>A diff file is often also called a patch, 
512         as it can be used to patch an existing source file or tree with changes
513         from somewhere else.
514         </para>
515         </tip>
516         </para>
517         <para>
518         The Ethereal community is using patches to transfer source code changes 
519         between the authors.
520         </para>
521         <para>
522         A patch is both readable by humans and (as it is specially formatted) by 
523         some dedicated tools.
524         </para>
525         <para>
526         Here is a small example of a patch file (XXX - generate a better example):
527         <programlisting>
528 <![CDATA[
529 diff -ur ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c ./epan/dissectors/packet-dcerpc.c
530 --- ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c  2004-08-12 15:42:26.000000000 -0700
531 +++ ./epan/dissectors/packet-dcerpc.c   2004-08-19 18:48:32.000000000 -0700
532 @@ -282,6 +282,7 @@
533  /* we need to keep track of what transport were used, ie what handle we came
534   * in through so we know what kind of pinfo->private_data was passed to us.
535   */
536 +/* Value of -1 is reserved for "not DCE packet" in packet_info.dcetransporttype. */
537  #define DCE_TRANSPORT_UNKNOWN          0
538  #define DCE_CN_TRANSPORT_SMBPIPE       1
539  
540 ]]> 
541         </programlisting>
542         The plus sign at the start of a line indicates an added line, a minus 
543         sign indicates a deleted line compared to the original sources.
544         </para>
545         <para>
546         As we always use so called "unified" diff files in Ethereal development, 
547         three unchanged lines before and after the actual changed parts are 
548         included. This will make it much easier for a merge/patch tool to find 
549         the right place(s) to change in the existing sources.
550         </para>
551         </section>
552
553
554         <section id="ChSrcGeneratePatch">
555         <title>Generate a patch</title>
556         <para>
557         There are several ways to generate such a patch.
558         </para>
559
560         <section id="ChSrcSVNDiff">
561         <title>Using the svn command-line client</title>
562         <para>
563         svn diff -u [changed_files] > svn.diff
564         </para>
565         <para>
566         XXX - add more details
567         </para>
568         </section>
569
570         <section id="ChSrcSVNGUIDiff">
571         <title>Using the diff feature of the GUI Subversion clients</title>
572         <para>
573         Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...) 
574         have a built-in "diff" feature.
575         </para>
576         <para>
577         XXX - add details at least for recommended TortoiseSVN
578         </para>
579         </section>
580
581         <section id="ChSrcDiff">
582         <title>Using the diff tool</title>
583         <para>
584         A diff file is generated, by comparing two files or directories between
585         your own working copy and the "official" source tree. So to be able to
586         do a diff, you should
587         have two source trees on your computer, one with your working copy
588         (containing your changes), and one with the "official" source tree
589         (hopefully the latest SVN files) from www.ethereal.com.
590         </para>
591         <para>
592         If you have only changed a single file, you could type something like
593         this:
594         </para>
595         <para>
596         <userinput>diff -r -u --strip-trailing-cr svn-file.c work-file.c &gt; foo.diff</userinput>
597         </para>
598         <para>
599         To get a diff file for your complete directory (including
600         subdirectories), you could type something like this:
601         </para>
602         <para>
603         <userinput>diff -r -u --strip-trailing-cr ./svn-dir ./working-dir &gt; foo.diff</userinput>
604         </para>
605         <para>
606         It's a good idea to do a <userinput>make distclean</userinput> before the 
607         actual diff call, as this will remove a lot
608         of temporary files which might be otherwise included in the diff. After
609         doing the diff, you should edit the <filename>foo.diff</filename>
610         file and remove unnecessary things, like your private changes to the
611         <filename>config.nmake</filename> file.
612         </para>
613         <para>
614         <table frame='all'><title>Some useful diff options</title>
615         <tgroup cols='2' align='left' colsep='1' rowsep='1'>
616         <colspec colname='c1'/>
617         <colspec colname='c2'/>
618         <thead>
619         <row>
620           <entry>Option</entry>
621           <entry>Purpose</entry>
622         </row>
623         </thead>
624         <tbody>
625         <row>
626           <entry>-r</entry>
627           <entry>Recursively compare any subdirectories found.</entry>
628         </row>
629         <row>
630           <entry>-u</entry>
631           <entry>Output unified context.</entry>
632         </row>
633         <row>
634           <entry>--strip-trailing-cr</entry>
635           <entry>Strip trailing carriage return on input. This is useful for Win32
636           </entry>
637         </row>
638         <row>
639           <entry>-x PAT</entry>
640           <entry>Exclude files that match PAT.
641           This could be something like -x *.obj to exclude all win32 object files.
642           </entry>
643         </row>
644         </tbody>
645         </tgroup>
646         </table>
647         </para>
648         <para>
649         The diff tool has a lot options, you will get a list with:
650         </para>
651         <para>
652         <userinput>diff --help</userinput>      
653         </para>
654         </section>
655
656         </section>
657
658         <section id="ChSrcGoodPatch">
659         <title>Some tips for a good patch</title>
660         <para>
661         Some tips that will make the merging of your changes into the 
662         SVN tree much more likely (and you want exactly that, don't you :-):
663         <itemizedlist>
664           <listitem><para>
665           <command>Use the latest SVN sources, or alike.</command>
666           It's a good idea to work with the same sources that are used by the 
667           other developer's, this makes it usually much easier to apply your 
668           patch. For information about the different ways to get the sources,
669           see <xref linkend="ChSrcObtain"/>.
670           </para></listitem>
671           <listitem><para>
672           <command>Update your SVN sources just before making a patch.
673           </command> For the same reasons as the previous point.
674           </para></listitem>
675           <listitem><para>
676           <command>Do a "make clean" before generating the patch.</command>
677           This removes a lot of unneeded intermediate files (like object files) 
678           which can confuse the diff tool generating a lot of unneeded stuff which 
679           you have to remove by hand from the patch again.
680           </para></listitem>
681           <listitem><para>
682           <command>Find a good descriptive filename for your patch.</command> 
683           Think a moment to find a proper name for your patch file. Often a 
684           filename like <filename>ethereal.diff</filename> is used, which isn't 
685           really helpful if keeping several of these files and find the right 
686           one later. For example: If you want to commit changes to the datatypes 
687           of dissector foo, a good filename might be: 
688           <filename>packet-foo-datatypes.diff</filename>.
689           </para></listitem>
690           <listitem><para>
691           <command>Follow the Ethereal source code style guide.</command> 
692           Ethereal runs on many platforms, and can be compiled with a number of 
693           different compilers. See <xref linkend="ChCodeStyle"/> for details.
694           </para>
695         <note><title>Note!</title>
696         <para>
697         Just because something compiles on your platform, that doesn't mean it'll 
698         compile on all of the other platforms for which Ethereal is built. 
699         </para>
700         </note>
701           </listitem>
702           <listitem><para>
703           <command>Don't put unrelated things into one large patch.
704           </command> A few smaller patches are usually easier to apply (but also 
705           don't put every changed line into a seperate patch :-).
706           </para></listitem>
707           <listitem><para>
708           <command>Remove any parts of the patch not related to the
709           changes you want to submit.</command> You can use a text editor for this. 
710           A common example for win32 developers are the differences in your private 
711           <filename>config.nmake</filename> file.
712           </para></listitem>
713         </itemizedlist>
714         In general: making it easier to understand and apply your patch by one
715         of the maintainers will make it much more likely (and faster) that it 
716         will actually be applied.
717         </para>
718         <para>
719         Please remember: you don't pay the person "on the
720         other side of the mail" for his/her effort applying your patch!
721         </para>
722         </section>
723         
724         <section id="ChSrcSend">
725         <title>Sending your patch to the developer mailing list</title>
726         <para>
727         After generating a patch of your changes, you might want to have your
728         changes included into the SVN server.
729         </para>
730         <para>
731         You should send an email to <ulink
732         url="mailto:ethereal-dev[AT]ethereal.com"/> containing: 
733         <itemizedlist>
734           <listitem><para>
735           subject: [PATCH] and a short description of your changes
736           </para></listitem>
737           <listitem><para>
738           body: the reasons for your changes and a short description what you 
739           changed and how you changed it
740           </para></listitem>
741           <listitem><para>
742           attachment: the patch file
743           </para></listitem>
744         </itemizedlist>
745         Don't include your patch into the mail
746         text, as this often changes the text formatting and makes it much
747         harder to apply your patch.
748         </para>
749         <para>
750         When someone from the Ethereal core maintainers finds the time to look
751         at your patch, it will be merged into the SVN repository, so
752         the latest SVN revisions and new releases will include it :-)
753         </para>
754         <para>
755         You might get one of the following responses from your mail:
756         <itemizedlist>
757           <listitem><para>
758           your patch is checked into the SVN repository :-)
759           </para></listitem>
760           <listitem><para>
761           your patch is rejected (and you get a response mail like: please
762           change xy because of ...). Possible reasons: you didn't followed the 
763           style guides, your code was buggy or insecure, your code does not 
764           compile on all of the supported platforms, ... So please fix the 
765           mentioned things and send a newly generated patch.
766           </para></listitem>
767           <listitem><para>
768           you don't get any reponse to your patch (even after a few days or so).
769           Possible reason: your patch might simply get lost, as all core 
770           maintainers were busy at that time and forgot to look at your patch. 
771           Simply send a mail asking if the patch was forgotten or if someone is 
772           still looking at it.
773           </para></listitem>
774         </itemizedlist>
775         </para>
776         </section>
777   </section>
778         
779   <section id="ChSrcPatchApply">
780         <title>Apply a patch from someone else</title>
781         <para>
782         Sometimes you need to apply a patch to your private source tree. Maybe 
783         because you want to try a patch from someone on the developer mailing 
784         list, or you want to check your own patch before submitting.
785         </para>
786         <warning><title>Warning!</title>
787         <para>
788         If you have problems applying a patch, make sure the line endings (CR/NL)
789         of the patch and your source files match.
790         </para>
791         </warning>
792         <para>
793         XXX - the following is a collection of material and needs some 
794         clarification.
795         </para>
796         <para>
797         Given the file "new.diff" containing a unified diff, the right way to 
798         call the patch tool depends on what the pathnames in "new.diff" look like.
799         If they're relative to the top-level source directory - for example, if a 
800         patch to "prefs.c" just has "prefs.c" as the file name - you'd run it as:
801         </para>
802         <para>
803     <userinput>patch -p0 &lt;new.diff</userinput>
804         </para>
805         <para>
806         If they're relative to a higher-level directory, you'd replace 0 with the 
807         number of higher-level directories in the path, e.g. if the names are 
808         "ethereal.orig/prefs.c" and "ethereal.mine/prefs.c", you'd run it with:
809         </para>
810         <para>
811     <userinput>patch -p1 &lt;new.diff</userinput>
812         </para>
813         <para>
814         If they're relative to a <command>subdirectory</command> of the top-level 
815         directory, you'd run "patch" in <command>that</command> directory and run 
816         it with "-p0".
817         </para>
818         <para>
819         If you run it without "-p" at all, the patch tool flattens path names, so 
820         that if you 
821         have a patch file with patches to "Makefile.am" and "wiretap/Makefile.am", 
822         it'll try to apply the first patch to the top-level "Makefile.am" and then 
823         apply the "wiretap/Makefile.am" patch to the top-level "Makefile.am" as 
824         well.  
825         </para>
826         <para>
827         At which position in the filesystem has the patch tool to be called?
828         </para>
829         <para>
830         If the pathnames are relative to the top-level source directory, or to a 
831         directory above that directory, you'd run it in the top-level source 
832         directory.
833         </para>
834         <para>
835         If they're relative to a <command>subdirectory</command> - for example, 
836         if somebody did a patch to "packet-ip.c" and ran "diff" or "svn diff" in 
837         the "epan/dissectors" directory - you'd run it in that subdirectory.  
838         It is preferred that people <command>NOT</command> submit patches like 
839         that - especially if they're only patching files that exist in multiple 
840         directories, such as "Makefile.am".
841         </para>
842         <para>
843         One other thing to note - "cvs diff" produces output that at least some
844         versions of "patch" can't handle; you'd get something such as
845         <programlisting>
846 <![CDATA[
847 Index: missing/dlnames.c
848 ===================================================================
849 RCS file: /tcpdump/master/tcpdump/missing/dlnames.c,v
850 retrieving revision 1.5
851 diff -c -r1.5 dlnames.c
852 *** missing/dlnames.c   18 Nov 2003 23:09:43 -0000      1.5
853 --- missing/dlnames.c   31 Aug 2004 21:45:16 -0000
854 ***************
855 ]]>
856         </programlisting>
857         from "cvs diff -c", and something similar from "cvs diff -u", and "patch",
858         unfortunately, would use the "diff -c" or "diff -u" line and try to patch
859         "dlnames.c" in the directory you're in, rather than in the "missing"
860         subdirectory.
861         </para>
862         <para>
863         For "cvs diff -c" or "cvs diff -u" diffs, there's a Python script
864         "cvsdiff-fix.py" in the "tools" directory in the Ethereal source tree; it
865         will fix up those lines in "cvs diff" output.  It reads its standard input
866         by default, or can be given a file name on the command line, and writes to
867         the standard output, so if you're typing at a command interpreter that
868         does piping, you could do something such as
869         </para>
870         <para>
871     <userinput>python tools/cvsdiff.py patchfile | patch -p0 -</userinput>
872         </para>
873         <para>
874         to use "patchfile".  (You might be able to leave the "python" out of the
875         command line on many UN*Xes.)
876         </para>
877         <para>
878         "svn diff" doesn't produce a "diff -c" or "diff -u" line, so its output
879         doesn't have that problem.  Regular "diff -c" or "diff -u" output also
880         shouldn't have that problem.
881         </para>
882         <para>
883         XXX - add some more details and do some cleanup.
884         </para>
885   </section>
886
887   <section id="ChSrcBinary">
888         <title>Binary packaging</title>
889         <para>
890         Delivering binary packages, makes it much easier for the end-users to
891         install Ethereal on their target system. This section will explain how
892         the binary packages are made.
893         </para>
894
895         <section id="ChSrcDeb">
896         <title>Debian: .deb packages</title>
897         <para>
898         XXX - don't know how to do
899         </para>
900         </section>
901
902         <section id="ChSrcRpm">
903         <title>Red Hat: .rpm packages</title>
904         <para>
905         XXX - don't know how to do
906         </para>
907         </section>
908         
909         <section id="ChSrcNSIS">
910         <title>Win32: NSIS .exe installer</title>
911         <para>
912         The "Nullsoft Install System" is a free installer generator for win32
913         based systems, instructions how to install it can be found in <xref 
914         linkend="ChToolsNSIS"/>. 
915         NSIS is script based, you will find the Ethereal installer
916         generation script at: <filename>packaging/nsis/ethereal.nsi</filename>.
917         </para>
918         <para>
919         You will probably have to modify the <filename>config.nmake</filename> 
920         file to specify where the NSIS binaries are
921         installed and wether to use the modern UI (which is recommended) or not.
922         </para>
923         <para>
924         In the ethereal directory, type:
925         </para>
926         <para>
927         <prompt>&gt;</prompt> <userinput>nmake -f makefile.nmake packaging</userinput>
928         </para>
929         <para>
930         to build the installer. 
931         </para>
932         <tip><title>Tip!</title>
933         <para>
934         Please be patient while the compression is
935         done, it will take some time (a few minutes!) even on fast machines.
936         </para>
937         </tip>
938         <para>
939         If everything went well, you will now find something like:
940         <filename>ethereal-setup-&EtherealCurrentVersion;.exe</filename> in
941         the <filename>packaging/nsis</filename> directory.
942         </para>
943         </section>
944
945   </section>
946
947 </chapter>
948 <!-- End of EUG Chapter Sources -->