aboutsummaryrefslogtreecommitdiffstats
path: root/docbook/wsdg_src/WSDG_chapter_sources.asciidoc
blob: 5422fcdd309153c509f5b57a47364557288ef341 (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
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
// WSDG Chapter Sources

[[ChapterSources]]

== Work with the Wireshark sources

[[ChSrcIntro]]

=== Introduction

This chapter will explain how to work with the Wireshark source code.
It will show you how to:

* Get the source

* Compile it on your machine

* Submit changes for inclusion in the official release

This chapter will not explain the source file contents in detail,
such as where to find specific functionality. This is done in
<<ChCodeOverview>>.

[[ChSrcGitRepository]]

=== The Wireshark Git repository

http://git-scm.com/[Git] is used to keep track of the changes made to the
Wireshark source code. The code is stored inside Wireshark project’s Git
repository located at a server at the wireshark.org domain.

Changes to the official repository are managed using the
https://www.gerritcodereview.com/[Gerrit] code review system. Gerrit
makes it easy to test and discuss changes before they are
pushed to the main repository. For an overview of Gerrit see the
https://code.wireshark.org/review/Documentation/intro-quick.html[Quick
Introduction].

.Why Git?

Git is a fast, flexible way of managing source code. It allows large
scale distributed development and ensures data integrity.

.Why Gerrit?

Gerrit makes it easy to contribute. You can sign in with any OpenID
provider and push your changes. It’s usable from both the web and
command line and is integrated with many popular tools.

.Git is our *third* revision control system
[NOTE]
====
Wireshark originally used http://www.nongnu.org/cvs/[Concurrent Versions System]
(CVS) and migrated to http://subversion.apache.org/[Subversion] in July 2004.
The Subversion repository was subsequently migrated to Git in January 2014.
====

Using Wireshark’s Git repository you can:

* Keep your private sources up to date with very little effort
* Get a mail notification when the official source code changes
* Get the source files from any previous release (or any other point in time)
* Have a quick look at the sources using a web interface
* See which person changed a specific piece of code
* and much more

[[ChSrcWebInterface]]

==== The web interface to the Git repository

If you need a quick look at the Wireshark source code you can
browse the most recent file versions in the master branch using Gitweb:

https://code.wireshark.org/review/gitweb?p=wireshark.git;a=tree

You can also view commit logs, branches, tags, and past revisions:

https://code.wireshark.org/review/gitweb?p=wireshark.git

Like most revision control systems, Git uses
http://en.wikipedia.org/wiki/Branching_%28revision_control%29[branching] to
manage different copies of the source code and allow parallel development.
Wireshark uses the following branches for official releases:

* _master_: Main feature development and odd-numbered "feature" releases.
* _master-x.y_: Stable release maintenance. For example, master-1.10 is used
  to manage the 1.10.x official releases.

[[ChSrcObtain]]

=== Obtain the Wireshark sources

There are several ways to obtain the sources from Wireshark’s Git
repository.

[TIP]
.Check out from the master branch using Git.
====
Using Git is much easier than synchronizing your source tree by hand using any
of the snapshot methods mentioned below. Git merges 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.
====

[NOTE]
.Keep your sources up to date
====
The following ways to retrieve the Wireshark sources are sorted in
decreasing source timeliness.  If you plan to commit changes you've
made to the sources, it’s a good idea to keep your private source
tree as current as possible.
====

The age mentioned in the following sections indicates the age of the
most recent change in that set of the sources.

[[ChSrcAnon]]
// Retain ChSrcAnon for backward compatibility
[[ChSrcGit]]

==== Git over SSH or HTTPS

Recommended for development purposes.

Age: a few minutes.

You can use a Git client to download the source code from Wireshark’s code
review system. Anyone can clone from the anonymous git URL:

* {wireshark-git-anonhttp-url}

If you create a Gerrit account you can clone from an authenticated URL:

* {wireshark-git-ssh-url}
* {wireshark-git-http-url}

SSH lets you use Gerrit on the
https://code.wireshark.org/review/Documentation/cmd-index.html#_server[command line].
HTTP lets you access the repository in environments that block the Gerrit SSH
port (29418). At the time of this writing (early 2014) we recommend that
you use the SSH interface. However, this may change as more tools take
advantage of Gerrit’s HTTP REST API.

The following example shows how to get up and running on the command
line. See <<ChToolsGit>> for information on installing and configuring
graphical Git and Gerrit clients.

. Sign in to {wireshark-code-review-url} using OpenID (click Register or Sign
In in the upper right corner of the web page). Follow the login instructions.

. In the upper right corner of the web page, click on your account name and
select _Settings_.

. Under _Profile_ set a username. This will be the username that
you use for SSH access. For the steps below we'll assume that your
username is `henry.perry`.

. Select _SSH Public Keys_ and add one or more keys. You will typically
upload a key for each computer that you use.

. Install git-review. This is an installable package
in many Linux distributions. You can also install it as a
https://pypi.python.org/pypi/git-review[Python package]. (This step
isn't strictly necessary but it makes working with Gerrit much easier.)
To install it from Chocolatey run
+
--
----
# Make sure "Scripts" is in our path
PS$>$env:path += ";C:\tools\python2\Scripts"
PS$>choco install pip
PS$>choco install git-review -source python
----
--

. Now on to the command line. First, make sure `git` works:
+
--
----
$ git --version
----
--

. If this is your first time using Git, make sure your username and
email address are configured. This is particularly important if you
plan on uploading changes.
+
--
----
$ git config --global user.name "Henry Perry"
$ git config --global user.email henry.perry@example.com
----
--

. Next, clone the Wireshark master:
+
--
----
$ git clone ssh://henry.perry@code.wireshark.org:29418/wireshark
----
The checkout only has to be done once. This will copy all the sources
of the latest version (including directories) from the server to
your machine. This may take some time depending on the speed of your
internet connection.
--

. Then set up the git pre-commit hook and the push address:
+
--
----
$ cd wireshark
$ cp tools/pre-commit .git/hooks/
$ git config --add remote.origin.push HEAD:refs/for/master
----
This will run a few basic checks on commit to make sure that the code
does not contain trivial errors. It will also warn if it is out of sync
with its master copy in the tools/ directory.
The change in the push address is necessary: We have an asymmetric
process for pulling and pushing because of gerrit.
--

. Initialize git-review.
+
--
----
$ git review -s
----
This prepares your local repository for use with Gerrit, including
installing the `commit-msg` hook script.
--

[[ChSrcSVNWeb]]
// Retain ChSrcSVNWeb for backward compatibility
[[ChSrcGitWeb]]

==== Git web interface

Recommended for informational purposes only, as only individual files can
be downloaded.

Age: a few minutes (same as anonymous Git access).

The entire source tree of the Git repository is available via a web
interface at {wireshark-code-browse-url}. You can view each revision of
a particular file, as well as diffs between different revisions. You can
also download individual files but not entire directories.


[[ChSrcBuildbot]]

==== Buildbot Snapshots

Recommended for development purposes, if direct Git access isn't
possible (e.g. because of a restrictive firewall).

Age: some number of minutes (a bit older than the Git access).

The Buildbot server will automatically start to generate a snapshot of
Wireshark’s source tree after a source code change is committed. These
snapshots can be found at {wireshark-snapshots-url}.

If Git access isn't possible, e.g. if the connection to the server
isn't possible because of a corporate firewall, the sources can be
obtained by downloading the Buildbot snapshots. However, if you are
going to maintain your sources in parallel to the "official" sources
for some time, it’s recommended to use the anonymous (or authenticated)
Git access if possible (believe it, it will save you a lot of time).

[[ChSrcReleased]]

==== Released sources

Recommended for building pristine packages.

Age: from days to weeks.

The official source releases can be found at {wireshark-download-url}.
You should use these sources if you want to build Wireshark on your
platform for with minimal or no changes, such Linux distribution
packages.

The differences between the released sources and the sources in the
Git repository will keep on growing until the next release is made.
(At the release time, the released and latest Git repository
versions are identical again :-).

[[ChSrcUpdating]]


=== Update the Wireshark sources

After you've obtained the Wireshark sources for the first time,
you might want to keep them in sync with the sources at the upstream
Git repository.

[TIP]
.Take a look at the Buildbot first
====
As development evolves, the Wireshark sources are compilable
most of the time -- but not always. You should take a look at
{wireshark-buildbot-url} before fetching or pulling to make
sure the builds are in good shape.
====

[[ChSrcAnonUpdate]]
// Retain ChSrcAnonUpdate for backward compatibility
[[ChSrcGitUpdate]]

==== Update Using Git

After you clone Wireshark’s Git repository you can update
by running

[source,sh]
----
$ git status
$ git pull
----

Depending on your preferences and work habits you might want to run
`git pull --rebase` or `git checkout -b my-topic-branch origin/master`
instead.

Fetching should only take a few seconds, even on a slow internet
connection. It will update your local repository history with changes
from the official repository. If you and someone else have changed
the same file since the last update, Git will try to merge the changes
into your private file (this works remarkably well).

[[ChSrcZipUpdate]]


==== Update Using Source Archives

There are several ways to download the Wireshark source code (as
described in <<ChSrcObtain>>), but bringing the changes from the
official sources into your personal source tree is identical.

First of all, you will download the new `.tar.xz` file of the official
sources the way you did it the first time.

If you haven't changed anything in the sources, you could simply throw
away your old sources and reinstall everything just like the first time.
But be sure, that you really haven't changed anything. It might be a good
idea to simply rename the "old" dir to have it around, just in case you
remember later that you really did change something before.

If you have changed 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 `.tar.xz` file into a new directory and use a good
merge tool (e.g. http://winmerge.sourceforge.net/[]for Win32) to bring
your personal source tree in sync with the official sources again.

This method can be problematic and can be much more difficult and
error-prone than using Git.

[[ChSrcBuildFirstTime]]

=== Build Wireshark

The sources contain several documentation files. It’s a good idea to read these
files first. After obtaining the sources, tools and libraries, the first place
to look at is _doc/README.developer_. Inside you will find the latest
information for Wireshark development for all supported platforms.

.Build Wireshark before changing anything
[TIP]
====
It is a very good idea to first test your complete build environment
(including running and debugging Wireshark) before making any changes
to the source code (unless otherwise noted).
====

Building Wireshark for the first time depends on your platform.

==== Building on Unix

The recommended (and fastest) way to build Wireshark is with CMake and
Ninja:

[source,sh]
----
# Starting from your Wireshark source directory, create a build directory
# alongside it.
$ cd ..
$ mkdir wireshark-ninja
$ cd wireshark-ninja
# Assumes your source directory is named "wireshark".
$ cmake -G Ninja ../wireshark
$ ninja (or cmake --build .)
----

If you need to build with a non-standard configuration, you can run

[source,sh]
----
$ cmake -LH ../wireshark
----

to see what options you have.

==== Win32 native

Follow the build procedure in <<ChWin32Build>> to build Wireshark.

After the build process has successfully finished, you should find a
`Wireshark.exe` and some other files in the `run\RelWithDebInfo` directory.

[[ChSrcRunFirstTime]]


=== Run generated Wireshark


[TIP]
.Tip!
====
An already installed Wireshark may interfere with your newly generated
version in various ways. If you have any problems getting your Wireshark
running the first time, it might be a good idea to remove the previously
installed version first.
====

[[ChSrcRunFirstTimeUnix]]

==== Unix/Linux

After a successful build you can run Wireshark right from the build
directory. Still the program would need to know that it’s being run from
the build directory and not from its install location. This has an impact
on the directories where the program can find the other parts and
relevant data files.


In order to run the Wireshark from the build directory set the environment
variable `WIRESHARK_RUN_FROM_BUILD_DIRECTORY` and run
Wireshark. If your platform is properly setup, your build directory and
current working directory are not in your PATH, so the
command line to launch Wireshark would be:

[source,sh]
----
$ WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./wireshark
----

There’s no need to run Wireshark as root user, you just won't be able to
capture. When you opt to run Wireshark this way, your terminal output can
be informative when things don't work as expected.


[[ChSrcRunFirstTimeWin32]]


==== Win32 Native

During the build all relevant program files are collected in a
subdirectory `run\RelWithDebInfo`. You can run the program from there by
launching the Wireshark.exe executable.

[[ChSrcDebug]]

=== Debug Your Generated Wireshark

[[ChSrcUnixDebug]]


==== Unix/Linux

When you want to investigate a problem with Wireshark you want to load
the program into your debugger. But loading wireshark into debugger fails
because of the libtool build environment. You'll have to wrap loading
wireshark into a libtool command:

[source,sh]
----
$ libtool --mode=execute gdb wireshark
----

If you prefer a graphic debugger you can use the Data Display Debugger
(ddd) instead of GNU debugger (gdb).


Additional traps can be set on GLib by setting the `G_DEBUG` environment variable:

[source,sh]
----
$ G_DEBUG=fatal_criticals libtool --mode=execute ddd wireshark
----

See http://library.gnome.org/devel/glib/stable/glib-running.html[]

[[ChSrcWin32Debug]]


==== Win32 native

You can debug using the Visual Studio Debugger or WinDbg.  See the section
on using the <<ChToolsDebugger, Debugger Tools>>.

[[ChSrcChange]]


=== Make changes to the Wireshark sources

As the Wireshark developers are working on many different platforms, a lot of
editors are used to develop Wireshark (emacs, vi, Microsoft Visual Studio
and many, many others). There’s no "standard" or "default" development
environment.

There are several reasons why you might want to change the Wireshark
sources:

* Add support for a new protocol (a new dissector)

* Change or extend an existing dissector

* Fix a bug

* Implement a glorious new feature

The internal structure of the Wireshark sources will be described in
<<PartDevelopment>>.

.Ask the _wireshark-dev_ mailing list before you start a new development task.
[TIP]
====
If you have an idea what you want to add or change it’s a good idea to
contact the developer mailing list
(see <<ChIntroMailingLists>>)
and explain your idea. Someone else might already be working on the same
topic, so a duplicated effort can be reduced. Someone might also give you tips that
should be thought about (like side effects that are sometimes very
hard to see).
====

// XXX - Add a section on branching.

[[ChSrcContribute]]


=== Contribute your changes

If you have finished changing the Wireshark sources to suit your needs, you
might want to contribute your changes back to the Wireshark community. You gain
the following benefits by contributing your improvements:

* _It’s the right thing to do._ Other people who find your contributions useful
  will appreciate them, and you will know that you have helped people in the
  same way that the developers of Wireshark have helped you.

* _You get free enhancements._ By making your code public, other developers have
  a chance to make improvements, as there’s always room for improvements. In
  addition someone may implement advanced features on top of your code, which
  can be useful for yourself too.

* _You save time and effort._ The maintainers and developers of Wireshark will
  maintain your code as well, updating it when API changes or other changes are
  made, and generally keeping it in tune with what is happening with Wireshark.
  So if Wireshark is updated (which is done often), you can get a new Wireshark
  version from the website and your changes will already be included without any
  effort for you.

There’s no direct way to push changes to the Git 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 upload them to the code
review system at {wireshark-code-review-url}. This requires you to set up git
as described at <<ChSrcGit>>.

[[ChSrcDiffWhat]]

// ==== What is a diff file (a patch)?
//
// A http://en.wikipedia.org/wiki/Diff[diff file]is a plain text file containing the differences between a pair of files
// (or a multiple of such file pairs).
//
// .A diff file is often also called a patch.
// [TIP]
// ====
// No matter what the name it can be used to patch an existing source file or tree with changes
// from somewhere else.
// ====
//
// The Wireshark community is using patches to transfer source code changes
// between the authors.
//
// A patch is both readable by humans and (as it is specially formatted) by
// some dedicated tools.
//
// Here is a small example of a patch for _file.h_that
// makes the second argument in cf_continue_tail()volatile.  It was created using _svn diff _,
// described below:
//
// [source,Diff]
// ----
// Index: file.h
// ===================================================================
// --- file.h      (revision 21134)
// +++ file.h      (revision 22401)
// @@ -142,7 +142,7 @@
//   * @param err the error code, if an error had occurred
//   * @return one of cf_read_status_t
//   */
// -cf_read_status_t cf_continue_tail(capture_file *cf, int to_read, int *err);
// +cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
//
//  /**
//   * Finish reading from "end" of a capture file.
// ----
//
// 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.
//
// We prefer to use so called "unified" diff files in Wireshark development,
// three unchanged lines before and after the actual changed parts are
// included. This makes it much easier for a merge/patch tool to find
// the right place(s) to change in the existing sources.

[[ChSrcGeneratePatch]]

// ==== Generate a patch
//
// There are several ways to generate patches. The preferred way is to
// generate them from an updated Subversion tree, since it avoids
// unnecessary integration work.

[[ChSrcSVNDiff]]

//
// ===== Using the svn command-line client
//
// ----
// $ svn diff [changed_files] > svn.diff
// ----
//
// Use the command line svn client to generate a patch in the required format
// from the changes you've made to your working copy. If you leave out the
// name of the changed file the svn client searches for all changes in the
// working copy and usually produces a patch containing more than just the
// change you want to send. Therefore you should always check the produced
// patch file.
//
// If you've added a new file, e.g.
// 'packet-myprotocol.c', you can use `svn add` to add it to your local tree before generating the patch.
// Similarly, you can use `svn rm` for files that should be removed.

[[ChSrcSVNGUIDiff]]

// ===== Using the diff feature of the GUI Subversion clients
//
// Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...)
// have a built-in "diff" feature.
//
// If you use TortoiseSVN:
//
// 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.
//
// 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.c' 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.

[[ChSrcDiff]]

// ===== Using the diff tool
//
// 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 {wireshark-main-url}.
//
// If you have only changed a single file, you could type something like
// this:
//
// ----
// $ diff -r -u --strip-trailing-cr svn-file.c work-file.c > foo.diff
// ----
//
// To get a diff file for your complete directory (including
// subdirectories), you could type something like this:
//
// ----
// $ diff -N -r -u --strip-trailing-cr ./svn-dir ./working-dir > foo.diff
// ----
//
// It’s a good idea to run `make distclean` 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 _foo.diff_ file and remove unnecessary
// things, like your private changes to the
// 'config.nmake' file.
//
//
// .Some useful diff options
// [options="header"]
// |===============
// |Option|Purpose
// |-N|Add new files when used in conjunction with -r.
// |-r|Recursively compare any subdirectories found.
// |-u|Output unified context.
// |--strip-trailing-cr|Strip trailing carriage return on input. This is useful for Win32
//
// |-x PAT|Exclude files that match PAT.
//       This could be something like -x *.obj to exclude all win32 object files.
// |===============
//
//
// The diff tool has a lot options; they can be listed with:
//
// ----
// diff --help
// ----

[[ChSrcGoodPatch]]

==== Some tips for a good patch

Some tips that will make the merging of your changes into Git much more likely
(and you want exactly that, don't you?):

* _Use the latest Git sources._ It’s a good idea to work with the same
  sources that are used by the other developers. This usually makes it much
  easier to apply your patch. For information about the different ways to get
  the sources, see <<ChSrcObtain>>.

* _Update your sources just before making a patch._ For the same reasons as the
  previous point.

* _Inspect your patch carefully._ Run `git diff` and make sure you aren't
  adding, removing, or omitting anything you shouldn't.

// * 'Do a "make clean" before generating the patch.' 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.

// XXX - What *are* good topic names?
* _Find a good descriptive topic name for your patch._ Short, specific
  names are preferred. _snowcone-machine-protocol_ is good, your name or
  your company name isn't.

* _Don't put unrelated things into one large patch._ A few smaller patches are
  usually easier to apply (but also don't put every changed line into a separate
  patch.

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.

.Please remember
[NOTE]
====
Wireshark is a volunteer effort. You aren't paying to have your code reviewed
and integrated.
====

[[ChSrcCodeRequirements]]

==== Code Requirements

The core maintainers have done a lot of work fixing bugs and making code
compile on the various platforms Wireshark supports.

To ensure Wireshark’s source code quality, and to reduce the workload of the
core maintainers, there are some things you should think about _before_
submitting a patch.

.Pay attention to the coding guidelines
[WARNING]
====
Ignoring the code requirements will make it very likely that your patch will
be rejected.
====

* _Follow the Wireshark source code style guide._ Just because something
  compiles on your platform, that doesn't mean it'll compile on all of the other
  platforms for which Wireshark is built. Wireshark runs on many platforms, and
  can be compiled with a number of different compilers. See <<ChCodeStyle>>for
  details.

* _Submit dissectors as built-in whenever possible._ Developing a new dissector
as a plugin is a good idea because compiling and testing is quicker, but it’s
best to convert dissectors to the built-in style before submitting for check in.
This reduces the number of files that must be installed with Wireshark and
ensures your dissector will be available on all platforms.
+
This is no hard-and-fast rule though. Many dissectors are straightforward so they
can easily be put into "the big pile", while some are ASN.1 based which takes a
different approach, and some multiple source file dissectors are more suitable to
be placed separately as plugins.

* _Ensure Wireshark Git Pre-Commit Hook is in the repository._  In your local
repository directory, there will be a .git/hooks/ directory, with sample git hooks
for running automatic actions before and after git commands. You can also
optionally install other hooks that you find useful.
+
In particular, the pre-commit hook will run every time you commit a change and can
be used to automatically check for various errors in your code. The sample git
pre-commit hook simply detects whitespace errors such as mixed tabs and spaces;
to install it just remove the .sample suffice from the existing pre-commit.sample file.
+
Wireshark provides a custom pre-commit hook which does additional Wireshark-specific API
and formatting checks, but it might return false positives. If you want to install it,
copy the pre-commit file from the tools directory (cp ./tools/pre-commit .git/hooks/)
and make sure it is executable or it will not be run.
+
If the pre-commit hook is preventing you from committing what you believe is a valid
change, you can run git commit --no-verify to skip running the hooks. Warning: using
--no-verify avoids the commit-msg hook, and thus will not automatically add the required
Change-ID to your commit. In case you are not updating an existing patch you may generate
a Change-ID by running git review -i (or git commit --amend if don't use git review).

* _Fuzz test your changes!_ Fuzz testing is a very
effective way to automatically find a lot of dissector related bugs.
You'll take a capture file containing packets affecting your dissector
and the fuzz test will randomly change bytes in this file, so that unusual
code paths in your dissector are checked. There are tools available to
automatically do this on any number of input files, see:
{wireshark-wiki-url}FuzzTesting for details.

[[ChSrcUpload]]

==== Uploading your changes

When you're satisfied with your changes (and obtained any necessary
approval from your organization) you can upload them for review at
{wireshark-code-review-url}. This requires a Gerrit Code Review account
as described at <<ChSrcGitRepository>>.

Changes should be pushed to a
https://code.wireshark.org/review/Documentation/user-upload.html#push_create[magical "refs/for" branch]
in Gerrit. For example, to upload your new Snowcone Machine Protocol dissector
you could push to refs/for/master with the topic "snowcone-machine":

[source,sh]
----
$ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master/snowcone-machine
----

The username `my.username` is the one which was given during registration with
the review system.

If you have `git-review` installed you can upload the change with a lot less typing:

[source,sh]
----
# Note: The "-f" flag deletes your current branch.
$ git review -f
----

You can push using any Git client. Many clients have support for Gerrit, either
built in or via an additional module.

// XXX - Talk about Gerrit change IDs

You might get one of the following responses to your patch request:

* Your patch is checked into the repository. Congratulations!

* You are asked to provide additional information, capture files, or other
  material. If you haven't fuzzed your code, you may be asked to do so.

* Your patch is rejected. You should get a response with the reason for
  rejection. Common reasons include not following the style guide, buggy or
  insecure code, and code that won't compile on other platforms. In each case
  you'll have to fix each problem and upload another patch.

* You don't get any response to your patch. Possible reason: All
  the core developers are busy (e.g., with their day jobs or family or other commitments) and
  haven't had time to look at your patch. Don't worry, if
  your patch is in the review system it won't get lost.

If you're concerned, feel free to add a comment to the patch or send an email
to the developer’s list asking for status. But please be patient: most if not
all of us do this in our spare time.

[[ChSrcBackport]]

==== Backporting a change

When a bug is fixed in the master branch it might be desirable or
necessary to backport the fix to a stable branch. You can do this
in Git by cherry-picking the change from one branch to another.
Suppose you want to backport change 1ab2c3d4 from the master branch to
master-1.10. Using "pure Git" commands you would do the following:

[source,sh]
----
# Create a new topic branch for the backport.
$ git checkout -b backport-g1ab2c3d4 origin/master-1.10

# Cherry-pick the change. Include a "cherry picked from..." line.
$ git cherry-pick -x 1ab2c3d4

# If there are conflicts, fix them.

# Compile and test the change.
$ make
$ ...

# OPTIONAL: Add entries to docbook/release-notes.asciidoc.
$ $EDITOR docbook/release-notes.asciidoc

# If you made any changes, update your commit:
$ git commit --amend -a

# Upload the change to Gerrit
$ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master-1.10/backport-g1ab2c3d4
----

If you want to cherry-pick a Gerrit change ID (e.g. I5e6f7890) you can use
`git review -X I5e6f7890` instead of `git cherry-pick` and `git review`
instead of `git push` as described in the previous chapter.

[[ChSrcPatchApply]]

=== Apply a patch from someone else

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.


.Beware line endings
[WARNING]
====
If you have problems applying a patch, make sure the line endings (CR/LF)
of the patch and your source files match.
====

[[ChSrcPatchUse]]


==== Using patch

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:

[source,sh]
----
$ patch -p0 < new.diff
----

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
_wireshark.orig/prefs.c_ and
_wireshark.mine/prefs.c_, you’d run it with:

[source,sh]
----
$ patch -p1 < new.diff
----

If they're relative to a _subdirectory_ of the top-level
directory, you’d run `patch` in _that_ directory and run it with `-p0`.

If you run it without `-pat` 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.

At which position in the filesystem should the patch tool be called?

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.

If they're relative to a *subdirectory* -- for example,
if somebody did a patch to _packet-ip.c_ and ran `diff` or `git diff` in
the _epan/dissectors_ directory -- you’d run it in that subdirectory.
It is preferred that people *not* submit patches like
that, especially if they're only patching files that exist in multiple
directories such as _Makefile.am_.

[[ChSrcBinary]]

=== Binary packaging

Delivering binary packages makes it much easier for the end-users to
install Wireshark on their target system. This section will explain how
the binary packages are made.


[[ChSrcDeb]]

==== Debian: .deb packages

The Debian Package is built using dpkg-buildpackage, based on information
found in the source tree under _debian_. See
http://www.debian-administration.org/articles/336 for a
more in-depth discussion of the build process.


In the wireshark directory, type:

[source,sh]
----
$ dpkg-buildpackage -rfakeroot -us -uc
----

to build the Debian Package.

[[ChSrcRpm]]

==== Red Hat: .rpm packages

You can build an RPM package using the `rpm-package` target. The package
version is derived from the current git HEAD, so you must build from a
git checkout.

The package is built using http://www.rpm.org/[rpmbuild], which comes as
standard on many flavours of Linux, including Red Hat, Fedora, and
openSUSE. The process creates a clean build environment in
_$\{CMAKE_BINARY_DIR}/packaging/rpm/BUILD_ each time the RPM is built.
The settings that control the build are in
_$\{CMAKE_SOURCE_DIR}/packaging/rpm/wireshark.spec.in_. The generated
SPEC file contains CMake flags and other settings for the RPM build
environment. Many of these come from the parent CMake environment.
Notable ones are:

* _\_prefix_ is set to _CMAKE_INSTALL_PREFIX_. By default this is
  _/usr/local_. Pass `-DCMAKE_INSTALL_PREFIX=/usr` to create a package
  that installs into _/usr_.

* Whether or not to create the “wireshark-qt” package
  (`-DBUILD_wireshark`).

* Lua, c-ares, nghttp2, and other library support (`-DENABLE_...`).

* Building with Ninja (`-G Ninja`).

In your build directory, type:

[source,sh]
----
$ ninja rpm-package
# ...or, if you're using GNU make...
$ make rpm-package
----

to build the binary and source RPMs. When it is finished there will be a
message stating where the built RPM can be found.

.This might take a while
[TIP]
====
This creates a tarball, extracts it, compiles Wireshark, and constructs
a package. This can take quite a long time. You can speed up the process
by using Ninja. If you're using GNU make you can add the following to
your `~/.rpmmacros` file to enable parallel builds:

----
%_smp_mflags -j %(grep -c processor /proc/cpuinfo)
----
====

Building the RPM package requires quite a few packages and libraries
including GLib, `gcc`, `bison`, `flex`, Asciidoctor, and Qt development
tools such as `uic` and `moc`. The required Qt packages can usually be
obtained by installing the _qt5-devel_ package. For a complete list of
build requirements, look for the “BuildRequires” lines in
_packaging/rpm/wireshark.spec.in_.

[[ChSrcOSX]]

==== macOS: .dmg packages

The macOS Package is built using macOS packaging tools, based on information
found in the source tree under _packaging/macosx_. It must be built using
CMake. In your build directory, type:

[source,sh]
----
$ make dmg_package
----

to build the macOS Package.

[[ChSrcNSIS]]

==== Win32: NSIS .exe installer

The _Nullsoft Install System_ is a free installer generator for Windows
systems. Instructions on installing it can be found in <<ChToolsNSIS>>.
NSIS is script based. You can find the main Wireshark installer
generation script at _packaging/nsis/wireshark.nsi_.

When building with CMake you must first build the _nsis_package_prep_ target,
followed by the _nsis_package_ target, e.g.

[source,cmd]
----
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
----

Splitting the packaging projects in this way allows for code signing.

[TIP]
.This might take a while
====
Please be patient while the package is compressed.
It might take some time, even on fast machines.
====

If everything went well, you will now find something like:
_wireshark-setup-{wireshark-version}.exe_ in
the _packaging/nsis_ directory in your build directory.

[[ChSrcPortableApps]]

==== Win32: PortableApps .paf.exe package

_PortableApps.com_ is an environment that lets users run popular applications
from portable media such as flash drives and cloud drive services.

Install the _PortableApps.com Platform_. Install for “all users”, which
will place it in `C:\PortableApps`. Add the following apps:

- NSIS Portable (Unicode)
- PortableApps.com Installer
- PortableApps.com Launcher
- PortableApps.com AppCompactor

When building with CMake you must first build the _nsis_package_prep_ target
(which takes care of general packaging dependencies), followed by the
_portableapps_package_ target, e.g.

[source,cmd]
----
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo portableapps_package.vcxproj
----

[TIP]
.This might take a while
====
Please be patient while the package is compressed.
It might take some time, even on fast machines.
====

If everything went well, you will now find something like:
_WiresharkPortable_{wireshark-version}.paf.exe_ in
the _packaging/portableapps_ directory.

// End of WSDG Chapter Sources

// vim: set syntax=asciidoc: