aboutsummaryrefslogtreecommitdiffstats
path: root/docbook/edg_src/EDG_chapter_sources.xml
blob: de92b9d225b0f944390b7b15104deca3d708fc7d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
<!-- EDG Chapter Sources -->
<!-- $Id$ -->

<chapter id="ChapterSources">
  <title>Work with the Wireshark sources</title>

  <section id="ChSrcIntro">
	<title>Introduction</title>
	<para>
	This chapter will explain how to work with the Wireshark source code.
	It will show you how to:
	<itemizedlist>
	<listitem><para>
	get the source
	</para></listitem>
	<listitem><para>
	compile the source
	</para></listitem>
	<listitem><para>
	submit changes
	</para></listitem>
	<listitem><para>
	...
	</para></listitem>
	</itemizedlist>
	However, this chapter will not explain the source file contents in detail, 
	such as where to find a specific functionality. This is done in 
	<xref linkend="ChCodeOverview"/>.
	</para>
  </section>
	
  <section id="ChSrcSVNServer">
	<title>The Wireshark Subversion repository</title>
	<para>
	Subversion is used to keep track of the changes made to the Wireshark 
	source code. The Wireshark source code is stored inside Ethereal project's 
	Subversion repository located at a server at the wireshark.org domain.
	</para>
	<para>
	To qoute the Subversion book about "What is Subversion?": 
	</para>
	<para>
	<quote>Subversion is a free/open-source version control system. That is, 
	Subversion manages files and directories over time. A tree of files is 
	placed into a central repository. The repository is much like an ordinary 
	file server, except that it remembers every change ever made to your files 
	and directories. This allows you to recover older versions of your data, 
	or examine the history of how your data changed. In this regard, many 
	people think of a version control system as a sort of "time machine".
	</quote>
	</para>
	<tip><title>Tip!</title>
	<para>
	Subversion is often abbreviated as SVN, as the command-line tools are 
	abbreviated that way. You will find both terms with the same meaning in 
	this book, in mailing list discussions and elsewhere.
	</para>
	</tip>
	<para>
	Using 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 Wireshark 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 Wireshark project has switched from CVS (Concurrent versioning 
	system) to Subversion some time ago, you may still find old references to 
	CVS in the Wireshark documentation and source files.
	</para>
	</tip>
  </section>
	
  <section id="ChSrcWebInterface">
	<title>The web interface to the Subversion repository</title>
	<para>
	If you need a quick look at the Wireshark source code, 
	you will only need a Web browser.
	</para>
	<para>
	A <command>simple view</command> on the latest developer version can be 
	found at: 
	</para>
	<para>
	<ulink url="http://anonsvn.wireshark.org/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.wireshark.org/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 Wireshark sources</title>
	<para>
	There are several ways to obtain the sources from Ethereal's Subversion 
	server.
	</para>
	<tip><title>Tip!</title>
	<para>
	Anonymous Subversion access can make your life much easier, compared to
	update your source tree by using any of the zip file methods mentioned 
	below.
	Subversion handles merging of changes into your personal source tree in a 
	very comfortable and quick way. So you can update your source tree several 
	times a day without much effort.
	</para>
	</tip>
	<note><title>Note!</title>
	<para>
	The following ways to retrieve the Wireshark sources are sorted in 
	decreasing 
	actuality. If you plan to commit changes you've made to the sources,
	it's a good idea to keep your private source tree as actual as possible.
	</para>
	</note>
	<para>
	The age mentioned in the following sections will indicate, how old the 
	most recent change in that sources will be. 
	</para>
	
	<section id="ChSrcAnon">
	<title>Anonymous Subversion access</title>
	<para>
	Recommended for development purposes.
	</para>
	<para>
	Age: a few minutes.
	</para>
	<para>
	You can use a Subversion client to download the source code from 
	Ethereal's anonymous Subversion repository. The URL for the repository 
	trunk is:
	<ulink url="http://anonsvn.wireshark.org/ethereal/trunk/"/>.
	</para>
	<para>
	See <xref linkend="ChToolsSubversion"/> how to install a Subversion client.
	</para>
	<para>
	For example, to check out using the command-line Subversion client, you 
	would type:
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn checkout http://anonsvn.wireshark.org/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.wireshark.org/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="ChSrcBuildbot">
	<title>Buildbot Snapshots</title>
	<para>
	Recommended for development purposes, if direct Subversion access isn't 
	possible (e.g. because of a restrictive firewall).
	</para>
	<para>
	Age: a few minutes (a bit older than the anonymous Subversion access).
	</para>
	<para>
	The buildbot server will automatically start to generate a snapshot of 
	Ethereal's sourcetree after a source code change committed. 
	These snapshots can be found at: <ulink
	url="http://www.wireshark.org/distribution/buildbot-builds/source/"/>.
	</para>
	<para>
	If anonymous Subversion access isn't possible, e.g. if the connection to 
	the server isn't possible because of a corporate firewall, the sources 
	can be obtained by downloading this buildbot snapshots. However, if you are
	going to maintain your sources in parallel to the "official" sources
	for some time, it's recommended to use the anonymous Subversion access if
	possible (believe it, it will save you a lot of time).
	</para>
	</section>


	<section id="ChSrcReleased">
	<title>Released sources</title>
	<para>
	Recommended for productive purposes.
	</para>
	<para>
	Age: from days to weeks.
	</para>
	<para>
	The officially released source files can be found at: <ulink
	url="http://www.wireshark.org/download.html"/>.
	You should use these sources if you want to build 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 Wireshark sources</title>
	<para>
	After you obtained the Wireshark sources for the first time, you 
	might want to keep them in sync with the sources at the Subversion 
	repository.
	</para>
	
	<section id="ChSrcAnonUpdate">
	<title>... with Anonymous Subversion access</title>
	<para>
	After the first time checkout is done, updating your 
	sources is simply done by typing (in the Wireshark source dir):
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn update</userinput>
	</para>
	<para>
	This will only take a few seconds, even on a slow internet line. It will 
	replace old file versions by new ones. If you and someone else have 
	changed the same file since the last update, Subversion will try to merge 
	the changes into your private file (this is working remarkably well).
	</para>
	</section>

	<section id="ChSrcZipUpdate">
	<title>... from zip files</title>
	<para>
	Independant of the way you retrieve the zip file of the Wireshark sources
	(as <xref linkend="ChSrcObtain"/> is providing several ways), the way to 
	bring the changes from the official sources into your personal source tree
	is identical.
	</para>
	<para>
	First of all, you will download the new zip file of the official sources
	the way you did it the first time.
	</para>
	<para>
	If you didn't changed anything in the sources, you could simply throw 
	away your old sources and reinstall everything just like the first time.
	But be sure, that you really didn't changed anything. It might be a good
	idea to simply rename the "old" dir to have it around, just in case you 
	remember later that you really did changed something before.
	</para>
	<para>
	Well, if you did change something in your source tree, you have to merge 
	the official changes 
	since the last update into your source tree. You will install the content 
	of the zip file into a new directory and use a good merge tool (e.g. 
	<ulink url="http://winmerge.sourceforge.net/"/> for Win32) to bring 
	your personal source tree in sync with the official sources again. 
	</para>
	</section>

  </section>

  <section id="ChSrcBuildFirstTime">
	<title>Build 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 Wireshark development for all
	supported platforms.
	</para>
	<tip><title>Tip!</title>
	<para>
	It is a very good idea, to first test your complete build environment 
	(including running and debugging 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>
	<para>
	If you need to build with a GTK 1.x version, you have to use:
	<programlisting>
./configure --disable-gtk2
	</programlisting>
	instead of just ./configure.
	</para>
	</section>
	
	<section>
	<title>Win32 native</title>
	<para>
	The place to look at is <filename>doc/README.win32</filename>, 
	you will get the latest infos for generation on the win32
	platforms.
	</para>
	<para>
	The next thing to do will be editing the file 
	<filename>config.nmake</filename> to reflect your configuration.
	The settings in this file are well documented, so please have a look at 
	that file.
	</para>
	<para>
	Then you should cleanup any intermediate files, which are shipped for 
	convenience of Unix users, by typing inside the command line (cmd.exe):
	</para>
	<para>
	<prompt>&gt;</prompt> <userinput>nmake -f Makefile.nmake distclean</userinput>
	</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 Wireshark sources</title>
	<para>
	As the Wireshark 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 Wireshark sources will be described in 
	<xref linkend="PartDevelopment"/>.
	</para>
	<tip><title>Tip!</title>
	<para>
	<command>Ask the developer mailing list before you really start a new 
	development task.</command>	
	If you have an idea what you want to add/change, it's a good idea to 
	contact the developer mailing list 
	(see <xref linkend="ChIntroMailingLists"/>) 
	and explain your idea. Someone else might already be working on the same 
	topic, so double effort can be reduced, or can give you some tips what 
	should be thought about too (like side effects that are sometimes very 
	hard to see).
	</para>
	</tip>
  </section>

  <section id="ChSrcCommit">
	<title>Commit changed sources</title>
	<para>
	If you have finished changing the Wireshark sources to suit your needs,
	you might want to contribute your changes back to the Wireshark SVN
	repository.
	</para>
	<para>
	You gain the following benefits by contributing your improvements back to 
	the community:
	<itemizedlist>
	<listitem><para>
	Other people who find your contributions useful will appreciate
	them, and you will know that you have helped people in the same way
	that the developers of 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 Wireshark 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 a multiple of such file pairs). 
	<tip><title>Tip!</title>
	<para>A diff file is often also called a patch, 
	as it can be used to patch an existing source file or tree with changes
	from somewhere else.
	</para>
	</tip>
	</para>
	<para>
	The Wireshark community is using patches to transfer source code changes 
	between the authors.
	</para>
	<para>
	A patch is both readable by humans and (as it is specially formatted) by 
	some dedicated tools.
	</para>
	<para>
	Here is a small example of a patch file (XXX - generate a better example):
	<programlisting>
<![CDATA[
diff -ur ../wireshark-0.10.6/epan/dissectors/packet-dcerpc.c ./epan/dissectors/packet-dcerpc.c
--- ../wireshark-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 Wireshark development, 
	three unchanged lines before and after the actual changed parts are 
	included. This will make it much easier for a merge/patch tool to find 
	the right place(s) to change in the existing sources.
 	</para>
	</section>


	<section id="ChSrcGeneratePatch">
	<title>Generate a patch</title>
	<para>
	There are several ways to generate such a patch.
	</para>

	<section id="ChSrcSVNDiff">
	<title>Using the svn command-line client</title>
	<para>
	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>
	If you use TortoiseSVN:
	</para>
	<para>
	TortoiseSVN (to be precise subversion) keeps track of the files you have 
	changed in the directories it controls, and will generate for you a 
	unified diff file compiling the differences. To do so - after updating 
	your sources from the SVN repository if needed - just right-click on the 
	highest level directory and choose "TortoiseSVN" -> "Create patch...". 
	You will be asked for a name and then the diff file will be created. The 
	names of the files in the patch will be relative to the directory you have 
	right-clicked on, so it will need to be applied on that level too.
	</para>
	<para>
	When you create the diff file, it will include any difference TortoiseSVN 
	finds in files in and under the directory you have right-clicked on, and 
	nothing else. This means that changes you might have made for your 
	specific configuration - like modifying "config.nmake" so that it uses 
	your lib directory - will also be included, and you will need to remove 
	these lines from the diff file. It also means that only changes will be 
	recorded, i.e. if you have created new files -say, a new packet-xxx for a 
	new protocol dissector- it will not be included in the diff, you need to 
	add it separately. And, of course, if you have been working separately in 
	two different patches, the .diff file will include both topics, which is 
	probably not a good idea.
	</para>
	</section>

	<section id="ChSrcDiff">
	<title>Using the diff tool</title>
	<para>
	A diff file is generated, by comparing two files or directories between
	your own working copy and the "official" source tree. So to be able to
	do a diff, you should
	have two source trees on your computer, one with your working copy
	(containing your changes), and one with the "official" source tree
	(hopefully the latest SVN files) from www.wireshark.org.
	</para>
	<para>
	If you have only changed a single file, you could type something like
	this:
	</para>
	<para>
	<userinput>diff -r -u --strip-trailing-cr svn-file.c work-file.c &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>Don't put unrelated things into one large patch.
	  </command> A few smaller patches are usually easier to apply (but also 
	  don't put every changed line into a seperate patch :-).
	  </para></listitem>
	  <listitem><para>
	  <command>Remove any parts of the patch not related to the
	  changes you want to submit.</command> You can use a text editor for this. 
	  A common example for win32 developers are the differences in your private 
	  <filename>config.nmake</filename> file.
	  </para></listitem>
	</itemizedlist>
	In general: making it easier to understand and apply your patch by one
	of the maintainers will make it much more likely (and faster) that it 
	will actually be applied.
	</para>
	<para>
	Please remember: you don't pay the person "on the
	other side of the mail" for his/her effort applying your patch!
	</para>
	</section>

	<section id="ChSrcCodeRequirements">
	<title>Code Requirements</title>
	<para>
	The core maintainers have a lot of work fixing bugs and making code 
	compile on the various platforms Ethereal supports.
	</para>
	<para>
	To ensure Ethereal's source code quality, and to reduce the workload of 
	the core maintainers, there are some things you should 
	think about <command>before</command> submitting a patch.
	<warning><title>Warn!</title>
	<para>
	<command>Ignoring the code requirements will make it very likely 
	that your patch will be rejected!</command>
	</para>
	</warning>
	<itemizedlist>
	  <listitem><para>
	  <command>Follow the Wireshark source code style guide.</command> 
	  Just because something compiles on your platform, that doesn't 
	  mean it'll compile on all of the other platforms for which Wireshark is 
	  built. 
	  Ethereal runs on many platforms, and can be compiled with a number of 
	  different compilers. See <xref linkend="ChCodeStyle"/> for details.
	  </para>
	  </listitem>
	  <listitem><para>
	  <command>Fuzz test your changes!</command> Fuzz testing is a very 
	  effective way to automatically find a lot of dissector related bugs. 
	  You'll take a capture file containing packets affecting your dissector 
	  and the fuzz test randomly change bytes in this file, so unconditional 
	  code paths in your dissector are passed. There are tools available to 
	  automatically do this on any number of input files, see: 
	  <ulink url="http://wiki.wireshark.org/FuzzTesting"/> for details.
	  </para>
	  </listitem>
	</itemizedlist>
	</para>
	</section>

	<section id="ChSrcSend">
	<title>Sending your patch to the developer mailing list</title>
	<para>
	After generating a patch of your changes, you might want to have your
	changes included into the SVN server.
	</para>
	<para>
	You should send an email to <ulink
	url="mailto:wireshark-dev[AT]wireshark.org"/> containing: 
	<itemizedlist>
	  <listitem><para>
	  subject: [PATCH] and a short description of your changes
	  </para></listitem>
	  <listitem><para>
	  body: the reasons for your changes and a short description what you 
	  changed and how you changed it
	  </para></listitem>
	  <listitem><para>
	  attachment: the patch file
	  </para></listitem>
	</itemizedlist>
	Don't include your patch into the mail
	text, as this often changes the text formatting and makes it much
	harder to apply your patch.
	</para>
	<para>
	When someone from the Wireshark core maintainers finds the time to look
	at your patch, it will be merged into the SVN repository, so
	the latest SVN revisions and new releases will include it :-)
	</para>
	<para>
	You might get one of the following responses from your mail:
	<itemizedlist>
	  <listitem><para>
	  your patch is checked into the SVN repository :-)
	  </para></listitem>
	  <listitem><para>
	  your patch is rejected (and you get a response mail like: please
	  change xy because of ...). Possible reasons: you didn't followed the 
	  style guides, your code was buggy or insecure, your code does not 
	  compile on all of the supported platforms, ... So please fix the 
	  mentioned things and send a newly generated patch.
	  </para></listitem>
	  <listitem><para>
	  you don't get any reponse to your patch (even after a few days or so).
	  Possible reason: your patch might simply get lost, as all core 
	  maintainers were busy at that time and forgot to look at your patch. 
	  Simply send a mail asking if the patch was forgotten or if someone is 
	  still looking at it.
	  </para></listitem>
	</itemizedlist>
	</para>
	</section>
  </section>
	
  <section id="ChSrcPatchApply">
	<title>Apply a patch from someone else</title>
	<para>
	Sometimes you need to apply a patch to your private source tree. Maybe 
	because you want to try a patch from someone on the developer mailing 
	list, or you want to check your own patch before submitting.
	</para>
	<warning><title>Warning!</title>
	<para>
	If you have problems applying a patch, make sure the line endings (CR/NL)
	of the patch and your source files match.
	</para>
	</warning>
	<para>
	XXX - the following is a collection of material and needs some 
	clarification.
	</para>
	<para>
	Given the file "new.diff" containing a unified diff, the right way to 
	call the patch tool depends on what the pathnames in "new.diff" look like.
	If they're relative to the top-level source directory - for example, if a 
	patch to "prefs.c" just has "prefs.c" as the file name - you'd run it as:
	</para>
	<para>
    <userinput>patch -p0 &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 Wireshark source tree; it
	will fix up those lines in "cvs diff" output.  It reads its standard input
	by default, or can be given a file name on the command line, and writes to
	the standard output, so if you're typing at a command interpreter that
	does piping, you could do something such as
	</para>
	<para>
    <userinput>python tools/cvsdiff.py patchfile | patch -p0 -</userinput>
	</para>
	<para>
	to use "patchfile".  (You might be able to leave the "python" out of the
	command line on many UN*Xes.)
	</para>
	<para>
	"svn diff" doesn't produce a "diff -c" or "diff -u" line, so its output
	doesn't have that problem.  Regular "diff -c" or "diff -u" output also
	shouldn't have that problem.
	</para>
	<para>
	XXX - add some more details and do some cleanup.
	</para>
  </section>

  <section id="ChSrcAdd">
	<title>Add a new file to the Subversion repository</title>
	<para>
	The "usual" way to commit new files is described in <xref 
	linkend="ChSrcCommit"/>. However, the following might be of interest for 
	the "normal" developer as well.
	</para>
	<note><title>Note!</title>
	<para>
	This action is only possible/allowed by the ethereal core developers who 
	have write access to the Subversion repository. It is put in here, to have 
	all information in one place.
	</para>
	</note>
	<para>
	If you (as a core developer) need to add a file to the SVN repository, 
	then you need to perform the following steps:
	<orderedlist>
	<listitem>
	<para>
	Add the Wireshark boilerplate to the new file(s).
	</para>
	</listitem>
	<listitem>
	<para>
	Add a line to each new file, containing the following text (case is 
	important, so don't write ID or id or iD):
<programlisting>
$Id$
</programlisting>
	</para>
	</listitem>
	<listitem>
	<para>
	Add the new file(s) to the repository:
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn add new_file</userinput>
	</para>
	</listitem>
	<listitem>
	<para>
	Set the line ending property to "native" for the new file(s):
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn propset svn:eol-style native new_file</userinput>
	</para>
	</listitem>
	<listitem>
	<para>
	Set version keyword to "Id" for the new file(s):
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn propset svn:keywords Id new_file</userinput>
	</para>
	</listitem>
	<listitem>
	<para>
	Commit your changes, including the added file(s).
	</para>
	<para>
	<prompt>$</prompt> 
	<userinput>svn commit new_file other_files_you_modified</userinput>
	</para>
	</listitem>
	</orderedlist>
	Don't forget a brief description of the reason for the commit, so other
	developers don't need to read the diff in order to know what has changed.
	</para>
  </section>
  <section id="ChSrcBinary">
	<title>Binary packaging</title>
	<para>
	Delivering binary packages, makes it much easier for the end-users to
	install 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 Wireshark installer
	generation script at: <filename>packaging/nsis/wireshark.nsi</filename>.
	</para>
	<para>
	You will probably have to modify the <filename>config.nmake</filename> 
	file to specify where the NSIS binaries are
	installed and wether to use the modern UI (which is recommended) or not.
	</para>
	<para>
	In the 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>wireshark-setup-&EtherealCurrentVersion;.exe</filename> in
	the <filename>packaging/nsis</filename> directory.
	</para>
	</section>

  </section>

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