1 ++++++++++++++++++++++++++++++++++++++
2 <!-- WSDG Chapter Sources -->
3 ++++++++++++++++++++++++++++++++++++++
7 == Work with the Wireshark sources
13 This chapter will explain how to work with the Wireshark source code.
14 It will show you how to:
18 * Compile it on your machine
20 * Submit changes for inclusion in the official release
22 This chapter will not explain the source file contents in detail,
23 such as where to find specific functionality. This is done in
26 [[ChSrcGitRepository]]
28 === The Wireshark Git repository
30 http://git-scm.com/[Git] is used to keep track of the changes made to the
31 Wireshark source code. The code is stored inside Wireshark project's Git
32 repository located at a server at the wireshark.org domain.
34 Changes to the official repository are managed using the
35 https://code.google.com/p/gerrit/[Gerrit] code review system. Gerrit
36 makes it easy to test and discuss changes before they are
37 pushed to the main repository. For an overview of Gerrit see the
38 https://code.wireshark.org/review/Documentation/intro-quick.html[Quick
43 Git is a fast, flexible way of managing source code. It allows large
44 scale distributed development and ensures data integrity.
48 Gerrit makes it easy to contribute. You can sign in with any OpenID
49 provider and push your changes. It's usable from both the web and
50 command line and is integrated with many popular tools.
52 .Git is our *third* revision control system
55 Wireshark originally used http://www.nongnu.org/cvs/[Concurrent Versions System]
56 (CVS) and migrated to http://subversion.apache.org/[Subversion] in July 2004.
57 The Subversion repository was subsequently migrated to Git in January 2014.
60 Using Wireshark's Git repository you can:
62 * Keep your private sources up to date with very little effort
63 * Get a mail notification when the official source code changes
64 * Get the source files from any previous release (or any other point in time)
65 * Have a quick look at the sources using a web interface
66 * See which person changed a specific piece of code
71 ==== The web interface to the Git repository
73 If you need a quick look at the Wireshark source code you can
74 browse the most recent file versions in the master branch using Gitweb:
76 https://code.wireshark.org/review/gitweb?p=wireshark.git;a=tree
78 You can also view commit logs, branches, tags, and past revisions:
80 https://code.wireshark.org/review/gitweb?p=wireshark.git
82 Like most revision control systems, Git uses
83 http://en.wikipedia.org/wiki/Branching_%28revision_control%29[branching] to
84 manage different copies of the source code and allow parallel development.
85 Wireshark uses the following branches for official releases:
87 * 'master': Main feature development and odd-numbered "feature" releases.
88 * 'master-x.y': Stable release maintenance. For example, master-1.10 is used
89 to manage the 1.10.x official releases.
93 === Obtain the Wireshark sources
95 There are several ways to obtain the sources from Wireshark's Git
99 .Check out from the master branch using Git.
101 Using Git is much easier than synchronizing your source tree by hand using any
102 of the snapshot methods mentioned below. Git merges changes into your
103 personal source tree in a very comfortable and quick way. So you can update your
104 source tree several times a day without much effort.
108 .Keep your sources up to date
110 The following ways to retrieve the Wireshark sources are sorted in
111 decreasing source timeliness. If you plan to commit changes you've
112 made to the sources, it's a good idea to keep your private source
113 tree as current as possible.
116 The age mentioned in the following sections indicates the age of the
117 most recent change in that set of the sources.
120 // Retain ChSrcAnon for backward compatibility
123 ==== Git over SSH or HTTPS
125 Recommended for development purposes.
129 You can use a Git client to download the source code from Wireshark's code
130 review system. Anyone can clone from the anonymous git URL:
132 * wireshark-git-anonhttp-url:[]
134 If you create a Gerrit account you can clone from an authenticated URL:
136 * wireshark-git-ssh-url:[]
137 * wireshark-git-http-url:[]
139 SSH lets you use Gerrit on the
140 https://code.wireshark.org/review/Documentation/cmd-index.html#_server[command line].
141 HTTP lets you access the repository in environments that block the Gerrit SSH
142 port (29418). At the time of this writing (early 2014) we recommend that
143 you use the SSH interface. However, this may change as more tools take
144 advantage of Gerrit's HTTP REST API.
146 The following example shows how to get up and running on the command
147 line. See <<ChToolsGit>> for information on installing and configuring
148 graphical Git and Gerrit clients.
150 . Sign in to wireshark-code-review-url:[] using OpenID (click Register or Sign
151 In in the upper right corner of the web page). Follow the login instructions.
153 . In the upper right corner of the web page, click on your account name and
156 . Under _Profile_ set a username. This will be the username that
157 you use for SSH access. For the steps below we'll assume that your
158 username is +henry.perry+.
160 . Select _SSH Public Keys_ and add one or more keys. You will typically
161 upload a key for each computer that you use.
163 . Install git-review. This is an installable package
164 in many Linux distributions. You can also install it as a
165 https://pypi.python.org/pypi/git-review[Python package]. (This step
166 isn't strictly necessary but it makes working with Gerrit much easier.)
167 To install it from Chocolatey run
171 # Make sure "Scripts" is in our path
172 PS$>$env:path += ";C:\tools\python2\Scripts"
173 PS$>choco install pip
174 PS$>choco install git-review -source python
178 . Now on to the command line. First, make sure `git` works:
186 . If this is your first time using Git, make sure your username and
187 email address are configured. This is particularly important if you
188 plan on uploading changes.
192 $ git config --global user.name "Henry Perry"
193 $ git config --global user.email henry.perry@example.com
197 . Next, clone the Wireshark master:
201 $ git clone ssh://henry.perry@code.wireshark.org:29418/wireshark
203 The checkout only has to be done once. This will copy all the sources
204 of the latest version (including directories) from the server to
205 your machine. This may take some time depending on the speed of your
209 . Then set up the git pre-commit hook and the push address:
214 $ cp tools/pre-commit .git/hooks/
215 $ git config --add remote.origin.push HEAD:refs/for/master
217 This will run a few basic checks on commit to make sure that the code
218 does not contain trivial errors. It will also warn if it is out of sync
219 with its master copy in the tools/ directory.
220 The change in the push address is necessary: We have an asymmetric
221 process for pulling and pushing because of gerrit.
224 . Initialize git-review.
230 This prepares your local repository for use with Gerrit, including
231 installing the `commit-msg` hook script.
235 // Retain ChSrcSVNWeb for backward compatibility
238 ==== Git web interface
240 Recommended for informational purposes only, as only individual files can
243 Age: a few minutes (same as anonymous Git access).
245 The entire source tree of the Git repository is available via
246 a web interface at wireshark-code-browse-url:[]. You can view each
247 revision of a particular file, as well as diffs between different
248 revisions. You can also download individual files but not entire
254 ==== Buildbot Snapshots
256 Recommended for development purposes, if direct Git access isn't
257 possible (e.g. because of a restrictive firewall).
259 Age: some number of minutes (a bit older than the Git access).
261 The Buildbot server will automatically start to generate a snapshot of
262 Wireshark's source tree after a source code change is committed.
263 These snapshots can be found at wireshark-snapshots-url:[].
265 If Git access isn't possible, e.g. if the connection to the server
266 isn't possible because of a corporate firewall, the sources can be
267 obtained by downloading the Buildbot snapshots. However, if you are
268 going to maintain your sources in parallel to the "official" sources
269 for some time, it's recommended to use the anonymous (or authenticated)
270 Git access if possible (believe it, it will save you a lot of time).
274 ==== Released sources
276 Recommended for building pristine packages.
278 Age: from days to weeks.
280 The official source releases can be found at
281 wireshark-download-page:[]. You should use these sources if you want
282 to build Wireshark on your platform for with minimal or no changes,
283 such Linux distribution packages.
285 The differences between the released sources and the sources in the
286 Git repository will keep on growing until the next release is made.
287 (At the release time, the released and latest Git repository
288 versions are identical again :-).
293 === Update the Wireshark sources
295 After you've obtained the Wireshark sources for the first time,
296 you might want to keep them in sync with the sources at the upstream
300 .Take a look at the Buildbot first
302 As development evolves, the Wireshark sources are compilable
303 most of the time -- but not always. You should take a look at
304 wireshark-buildbot-url:[] before fetching or pulling to make
305 sure the builds are in good shape.
309 // Retain ChSrcAnonUpdate for backward compatibility
312 ==== Update Using Git
314 After you clone Wireshark's Git repository you can update
322 Depending on your preferences and work habits you might want to run
323 `git pull --rebase` or `git checkout -b my-topic-branch origin/master`
326 Fetching should only take a few seconds, even on a slow internet
327 connection. It will update your local repository history with changes
328 from the official repository. If you and someone else have changed
329 the same file since the last update, Git will try to merge the changes
330 into your private file (this works remarkably well).
335 ==== Update Using Source Archives
337 There are several ways to download the Wireshark source code (as
338 described in <<ChSrcObtain>>), but bringing the changes from the
339 official sources into your personal source tree is identical.
341 First of all, you will download the new `.tar.bz2` file of the official
342 sources the way you did it the first time.
344 If you haven't changed anything in the sources, you could simply throw
345 away your old sources and reinstall everything just like the first time.
346 But be sure, that you really haven't changed anything. It might be a good
347 idea to simply rename the "old" dir to have it around, just in case you
348 remember later that you really did change something before.
350 If you have changed your source tree, you have to merge the official
351 changes since the last update into your source tree. You will install
352 the content of the `.tar.bz2` file into a new directory and use a good
353 merge tool (e.g. http://winmerge.sourceforge.net/[]for Win32) to bring
354 your personal source tree in sync with the official sources again.
356 This method can be problematic and can be much more difficult and
357 error-prone than using Git.
359 [[ChSrcBuildFirstTime]]
363 The sources contain several documentation files. It's a good idea to read these
364 files first. After obtaining the sources, tools and libraries, the first place
365 to look at is 'doc/README.developer'. Inside you will find the latest
366 information for Wireshark development for all supported platforms.
368 .Build Wireshark before changing anything
371 It is a very good idea to first test your complete build environment
372 (including running and debugging Wireshark) before making any changes
373 to the source code (unless otherwise noted).
376 Building Wireshark for the first time depends on your platform.
378 ==== Building on Unix
380 Run the `autogen.sh` script at the top-level wireshark directory to configure
381 your build directory.
389 If you need to build with a non-standard configuration, you can run
395 to see what options you have.
399 Follow the build procedure in <<ChWin32Build>> to build Wireshark.
401 After the build process has successfully finished, you should find a
402 `Wireshark.exe` and some other files in the `run\RelWithDebInfo` directory.
404 [[ChSrcRunFirstTime]]
407 === Run generated Wireshark
413 An already installed Wireshark may interfere with your newly generated
414 version in various ways. If you have any problems getting your Wireshark
415 running the first time, it might be a good idea to remove the previously
416 installed version first.
419 [[ChSrcRunFirstTimeUnix]]
423 After a successful build you can run Wireshark right from the build
424 directory. Still the program would need to know that it's being run from
425 the build directory and not from its install location. This has an impact
426 on the directories where the program can find the other parts and
430 In order to run the Wireshark from the build directory set the environment
431 variable `WIRESHARK_RUN_FROM_BUILD_DIRECTORY` and run
432 Wireshark. If your platform is properly setup, your build directory and
433 current working directory are not in your PATH, so the
434 command line to launch Wireshark would be:
437 $ WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./wireshark
440 There's no need to run Wireshark as root user, you just won't be able to
441 capture. When you opt to run Wireshark this way, your terminal output can
442 be informative when things don't work as expected.
445 [[ChSrcRunFirstTimeWin32]]
450 During the build all relevant program files are collected in a subdirectory
451 `run\RelWithDebInfo`. You can run the program from there by
452 launching the Wireshark.exe executable.
454 The older GTK based version is also available in the same
455 subdirectory. You can run the program from there by launching the
456 wireshark-gtk.exe executable.
462 === Debug your generated Wireshark
469 When you want to investigate a problem with Wireshark you want to load
470 the program into your debugger. But loading wireshark into debugger fails
471 because of the libtool build environment. You'll have to wrap loading
472 wireshark into a libtool command:
475 $ libtool --mode=execute gdb wireshark
478 If you prefer a graphic debugger you can use the Data Display Debugger
479 (ddd) instead of GNU debugger (gdb).
482 Additional traps can be set on GLib by setting the `G_DEBUG` environment variable:
485 $ G_DEBUG=fatal_criticals libtool --mode=execute ddd wireshark
488 See http://library.gnome.org/devel/glib/stable/glib-running.html[]
495 You can debug using the Visual Studio Debugger or WinDbg. See the section
496 on using the <<ChToolsDebugger, Debugger Tools>>.
501 === Make changes to the Wireshark sources
503 As the Wireshark developers are working on many different platforms, a lot of
504 editors are used to develop Wireshark (emacs, vi, Microsoft Visual Studio
505 and many, many others). There's no "standard" or "default" development
508 There are several reasons why you might want to change the Wireshark
511 * Add support for a new protocol (a new dissector)
513 * Change or extend an existing dissector
517 * Implement a glorious new feature
519 The internal structure of the Wireshark sources will be described in
522 .Ask the _wireshark-dev_ mailing list before you start a new development task.
525 If you have an idea what you want to add or change it's a good idea to
526 contact the developer mailing list
527 (see <<ChIntroMailingLists>>)
528 and explain your idea. Someone else might already be working on the same
529 topic, so a duplicated effort can be reduced. Someone might also give you tips that
530 should be thought about (like side effects that are sometimes very
534 // XXX - Add a section on branching.
539 === Contribute your changes
541 If you have finished changing the Wireshark sources to suit your needs, you
542 might want to contribute your changes back to the Wireshark community. You gain
543 the following benefits by contributing your improvements:
545 * _It's the right thing to do._ Other people who find your contributions useful
546 will appreciate them, and you will know that you have helped people in the
547 same way that the developers of Wireshark have helped you.
549 * _You get free enhancements._ By making your code public, other developers have
550 a chance to make improvements, as there's always room for improvements. In
551 addition someone may implement advanced features on top of your code, which
552 can be useful for yourself too.
554 * _You save time and effort._ The maintainers and developers of Wireshark will
555 maintain your code as well, updating it when API changes or other changes are
556 made, and generally keeping it in tune with what is happening with Wireshark.
557 So if Wireshark is updated (which is done often), you can get a new Wireshark
558 version from the website and your changes will already be included without any
561 There's no direct way to push changes to the Git repository. Only a few people
562 are authorised to actually make changes to the source code (check-in changed
563 files). If you want to submit your changes, you should upload them to the code
564 review system at wireshark-code-review-url:[]. This requires you to set up git
565 as described at <<ChSrcGit>>.
569 // ==== What is a diff file (a patch)?
571 // A http://en.wikipedia.org/wiki/Diff[diff file]is a plain text file containing the differences between a pair of files
572 // (or a multiple of such file pairs).
574 // .A diff file is often also called a patch.
577 // No matter what the name it can be used to patch an existing source file or tree with changes
578 // from somewhere else.
581 // The Wireshark community is using patches to transfer source code changes
582 // between the authors.
584 // A patch is both readable by humans and (as it is specially formatted) by
585 // some dedicated tools.
587 // Here is a small example of a patch for _file.h_that
588 // makes the second argument in cf_continue_tail()volatile. It was created using _svn diff _,
594 // ===================================================================
595 // --- file.h (revision 21134)
596 // +++ file.h (revision 22401)
597 // @@ -142,7 +142,7 @@
598 // * @param err the error code, if an error had occurred
599 // * @return one of cf_read_status_t
601 // -cf_read_status_t cf_continue_tail(capture_file *cf, int to_read, int *err);
602 // +cf_read_status_t cf_continue_tail(capture_file *cf, volatile int to_read, int *err);
605 // * Finish reading from "end" of a capture file.
608 // The plus sign at the start of a line indicates an added line, a minus
609 // sign indicates a deleted line compared to the original sources.
611 // We prefer to use so called "unified" diff files in Wireshark development,
612 // three unchanged lines before and after the actual changed parts are
613 // included. This makes it much easier for a merge/patch tool to find
614 // the right place(s) to change in the existing sources.
616 [[ChSrcGeneratePatch]]
618 // ==== Generate a patch
620 // There are several ways to generate patches. The preferred way is to
621 // generate them from an updated Subversion tree, since it avoids
622 // unnecessary integration work.
627 // ===== Using the svn command-line client
630 // $ svn diff [changed_files] > svn.diff
633 // Use the command line svn client to generate a patch in the required format
634 // from the changes you've made to your working copy. If you leave out the
635 // name of the changed file the svn client searches for all changes in the
636 // working copy and usually produces a patch containing more than just the
637 // change you want to send. Therefore you should always check the produced
640 // If you've added a new file, e.g.
641 // 'packet-myprotocol.c', you can use `svn add` to add it to your local tree before generating the patch.
642 // Similarly, you can use `svn rm` for files that should be removed.
646 // ===== Using the diff feature of the GUI Subversion clients
648 // Most (if not all) of the GUI Subversion clients (RapidSVN, TortoiseSVN, ...)
649 // have a built-in "diff" feature.
651 // If you use TortoiseSVN:
653 // TortoiseSVN (to be precise Subversion) keeps track of the files you have
654 // changed in the directories it controls, and will generate for you a
655 // unified diff file compiling the differences. To do so - after updating
656 // your sources from the SVN repository if needed - just right-click on the
657 // highest level directory and choose "TortoiseSVN" -> "Create patch...".
658 // You will be asked for a name and then the diff file will be created. The
659 // names of the files in the patch will be relative to the directory you have
660 // right-clicked on, so it will need to be applied on that level too.
662 // When you create the diff file, it will include any difference TortoiseSVN
663 // finds in files in and under the directory you have right-clicked on, and
664 // nothing else. This means that changes you might have made for your
665 // specific configuration - like modifying 'config.nmake' so that it uses
666 // your lib directory - will also be included, and you will need to remove
667 // these lines from the diff file. It also means that only changes will be
668 // recorded, i.e. if you have created new files -- say, a new
669 // 'packet-xxx.c' for a
670 // new protocol dissector -- it will not be included in the diff, you need to
671 // add it separately. And, of course, if you have been working separately in
672 // two different patches, the .diff file will include both topics, which is
673 // probably not a good idea.
677 // ===== Using the diff tool
679 // A diff file is generated, by comparing two files or directories between
680 // your own working copy and the "official" source tree. So to be able to
681 // do a diff, you should
682 // have two source trees on your computer, one with your working copy
683 // (containing your changes), and one with the "official" source tree
684 // (hopefully the latest SVN files) from wireshark-web-site:[].
686 // If you have only changed a single file, you could type something like
690 // $ diff -r -u --strip-trailing-cr svn-file.c work-file.c > foo.diff
693 // To get a diff file for your complete directory (including
694 // subdirectories), you could type something like this:
697 // $ diff -N -r -u --strip-trailing-cr ./svn-dir ./working-dir > foo.diff
700 // It's a good idea to run `make distclean` before the
701 // actual diff call, as this will remove a lot
702 // of temporary files which might be otherwise included in the diff. After
703 // doing the diff, you should edit the _foo.diff_ file and remove unnecessary
704 // things, like your private changes to the
705 // 'config.nmake' file.
708 // .Some useful diff options
709 // [options="header"]
712 // |-N|Add new files when used in conjunction with -r.
713 // |-r|Recursively compare any subdirectories found.
714 // |-u|Output unified context.
715 // |--strip-trailing-cr|Strip trailing carriage return on input. This is useful for Win32
717 // |-x PAT|Exclude files that match PAT.
718 // This could be something like -x *.obj to exclude all win32 object files.
722 // The diff tool has a lot options; they can be listed with:
730 ==== Some tips for a good patch
732 Some tips that will make the merging of your changes into Git much more likely
733 (and you want exactly that, don't you?):
735 * 'Use the latest Git sources.' It's a good idea to work with the same
736 sources that are used by the other developers. This usually makes it much
737 easier to apply your patch. For information about the different ways to get
738 the sources, see <<ChSrcObtain>>.
740 * 'Update your sources just before making a patch.' For the same reasons as the
743 * 'Inspect your patch carefully.' Run `git diff` and make sure you aren't
744 adding, removing, or omitting anything you shouldn't.
746 // * 'Do a "make clean" before generating the patch.' This removes a lot of
747 // unneeded intermediate files (like object files) which can confuse the diff
748 // tool generating a lot of unneeded stuff which you have to remove by hand from
751 // XXX - What *are* good topic names?
752 * 'Find a good descriptive topic name for your patch.' Short, specific
753 names are preferred. 'snowcone-machine-protocol' is good, your name or
754 your company name isn't.
756 * 'Don't put unrelated things into one large patch.' A few smaller patches are
757 usually easier to apply (but also don't put every changed line into a separate
760 In general, making it easier to understand and apply your patch by one of the
761 maintainers will make it much more likely (and faster) that it will actually be
767 Wireshark is a volunteer effort. You aren't paying to have your code reviewed
771 [[ChSrcCodeRequirements]]
773 ==== Code Requirements
775 The core maintainers have done a lot of work fixing bugs and making code
776 compile on the various platforms Wireshark supports.
778 To ensure Wireshark's source code quality, and to reduce the workload of the
779 core maintainers, there are some things you should think about _before_
782 .Pay attention to the coding guidelines
785 Ignoring the code requirements will make it very likely that your patch will
789 * 'Follow the Wireshark source code style guide.' Just because something
790 compiles on your platform, that doesn't mean it'll compile on all of the other
791 platforms for which Wireshark is built. Wireshark runs on many platforms, and
792 can be compiled with a number of different compilers. See <<ChCodeStyle>>for
795 * 'Submit dissectors as built-in whenever possible.' Developing a new dissector
796 as a plugin is a good idea because compiling and testing is quicker, but it's
797 best to convert dissectors to the built-in style before submitting for check in.
798 This reduces the number of files that must be installed with Wireshark and
799 ensures your dissector will be available on all platforms.
801 This is no hard-and-fast rule though. Many dissectors are straightforward so they
802 can easily be put into "the big pile", while some are ASN.1 based which takes a
803 different approach, and some multiple source file dissectors are more suitable to
804 be placed separately as plugins.
806 * 'Verify that your dissector code does not use prohibited or deprecated APIs.'
807 This can be done as follows:
810 $ perl <wireshark_root>/tools/checkAPIs.pl <source filename(s)>
813 * 'Fuzz test your changes!' Fuzz testing is a very
814 effective way to automatically find a lot of dissector related bugs.
815 You'll take a capture file containing packets affecting your dissector
816 and the fuzz test will randomly change bytes in this file, so that unusual
817 code paths in your dissector are checked. There are tools available to
818 automatically do this on any number of input files, see:
819 wireshark-wiki-site:[]FuzzTesting[] for details.
823 ==== Uploading your changes
825 When you're satisfied with your changes (and obtained any necessary approval
826 from your organization) you can upload them for review at
827 wireshark-code-review-url:[]. This requires a Gerrit Code Review account as
828 described at <<ChSrcGitRepository>>.
830 Changes should be pushed to a
831 https://code.wireshark.org/review/Documentation/user-upload.html#push_create[magical "refs/for" branch]
832 in Gerrit. For example, to upload your new Snowcone Machine Protocol dissector
833 you could push to refs/for/master with the topic "snowcone-machine":
836 $ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master/snowcone-machine
839 The username `my.username` is the one which was given during registration with
842 If you have `git-review` installed you can upload the change with a lot less typing:
845 # Note: The "-f" flag deletes your current branch.
849 You can push using any Git client. Many clients have support for Gerrit, either
850 built in or via an additional module.
852 // XXX - Talk about Gerrit change IDs
854 You might get one of the following responses to your patch request:
856 * Your patch is checked into the repository. Congratulations!
858 * You are asked to provide additional information, capture files, or other
859 material. If you haven't fuzzed your code, you may be asked to do so.
861 * Your patch is rejected. You should get a response with the reason for
862 rejection. Common reasons include not following the style guide, buggy or
863 insecure code, and code that won't compile on other platforms. In each case
864 you'll have to fix each problem and upload another patch.
866 * You don't get any response to your patch. Possible reason: All
867 the core developers are busy (e.g., with their day jobs or family or other commitments) and
868 haven't had time to look at your patch. Don't worry, if
869 your patch is in the review system it won't get lost.
871 If you're concerned, feel free to add a comment to the patch or send an email
872 to the developer's list asking for status. But please be patient: most if not
873 all of us do this in our spare time.
877 ==== Backporting a change
879 When a bug is fixed in the master branch it might be desirable or
880 necessary to backport the fix to a stable branch. You can do this
881 in Git by cherry-picking the change from one branch to another.
882 Suppose you want to backport change 1ab2c3d4 from the master branch to
883 master-1.10. Using "pure Git" commands you would do the following:
886 # Create a new topic branch for the backport.
887 $ git checkout -b backport-g1ab2c3d4 origin/master-1.10
889 # Cherry-pick the change. Include a "cherry picked from..." line.
890 $ git cherry-pick -x 1ab2c3d4
892 # If there are conflicts, fix them.
894 # Compile and test the change.
898 # OPTIONAL: Add entries to docbook/release-notes.asciidoc.
899 $ $EDITOR docbook/release-notes.asciidoc
901 # If you made any changes, update your commit:
902 $ git commit --amend -a
904 # Upload the change to Gerrit
905 $ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master-1.10/backport-g1ab2c3d4
908 If you want to cherry-pick a Gerrit change ID (e.g. I5e6f7890) you can use
909 `git review -X I5e6f7890` instead of `git cherry-pick` and `git review`
910 instead of `git push` as described in the previous chapter.
914 === Apply a patch from someone else
916 Sometimes you need to apply a patch to your private source tree. Maybe
917 because you want to try a patch from someone on the developer mailing
918 list, or you want to check your own patch before submitting.
924 If you have problems applying a patch, make sure the line endings (CR/LF)
925 of the patch and your source files match.
933 Given the file 'new.diff' containing a unified diff,
934 the right way to call the patch tool depends on what the pathnames in
935 'new.diff' look like.
936 If they're relative to the top-level source directory (for example, if a
937 patch to 'prefs.c' just has 'prefs.c' as the file name) you'd run it as:
940 $ patch -p0 < new.diff
943 If they're relative to a higher-level directory, you'd replace 0 with the
944 number of higher-level directories in the path, e.g. if the names are
945 'wireshark.orig/prefs.c' and
946 'wireshark.mine/prefs.c', you'd run it with:
949 $ patch -p1 < new.diff
952 If they're relative to a 'subdirectory' of the top-level
953 directory, you'd run `patch` in 'that' directory and run it with `-p0`.
955 If you run it without `-pat` all, the patch tool
956 flattens path names, so that if you
957 have a patch file with patches to 'Makefile.am' and
958 'wiretap/Makefile.am',
959 it'll try to apply the first patch to the top-level
960 'Makefile.am' and then apply the
961 'wiretap/Makefile.am' patch to the top-level
962 'Makefile.am' as well.
964 At which position in the filesystem should the patch tool be called?
966 If the pathnames are relative to the top-level source directory, or to a
967 directory above that directory, you'd run it in the top-level source
970 If they're relative to a *subdirectory* -- for example,
971 if somebody did a patch to 'packet-ip.c' and ran `diff` or `git diff` in
972 the 'epan/dissectors' directory -- you'd run it in that subdirectory.
973 It is preferred that people *not* submit patches like
974 that, especially if they're only patching files that exist in multiple
975 directories such as 'Makefile.am'.
981 Delivering binary packages makes it much easier for the end-users to
982 install Wireshark on their target system. This section will explain how
983 the binary packages are made.
989 ==== Debian: .deb packages
991 The Debian Package is built using dpkg-buildpackage, based on information
992 found in the source tree under _debian_. See
993 http://www.debian-administration.org/articles/336[]for a
994 more in-depth discussion of the build process.
997 In the wireshark directory, type:
1000 $ dpkg-buildpackage -rfakeroot -us -uc
1003 to build the Debian Package.
1007 ==== Red Hat: .rpm packages
1009 The RPM is built using rpmbuild (http://www.rpm.org/), which comes as standard on many flavours of Linux, including
1010 Red Hat and Fedora. The process creates a clean build environment in _packaging/rpm/BUILD_ every
1011 time the RPM is built. The settings controlling the build are in _packaging/rpm/SPECS/wireshark.spec.in_.
1012 After editing the settings in this file, _./configure_ must be run again in the wireshark directory to
1013 generate the actual specification script.
1016 .Careful with that `configure` setting
1019 The SPEC file contains settings for the _configure_ used to set the RPM build
1020 environment. These are mostly independent of any settings passed to the
1021 usual Wireshark `./configure`. The exceptions to this rule are:
1023 * The _prefix_ given to `configure --prefix` is passed to rpmbuild.
1025 * The selection of the GUI (Qt, Gtk+, or both) is passed to rpmbuild.
1027 * The selection of whether to include Lua support is passed to rpmbuild.
1030 In the wireshark directory, type:
1036 to build the RPM and source RPM. Once it is done, there will be a message stating where the built RPM can be found.
1038 .This might take a while
1041 Because this does a clean build as well as constructing the package this can
1042 take quite a long time. Suggestion: add the following to your `~/.rpmmacros`
1043 file to allow parallel builds:
1046 %_smp_mflags -j %(grep -c processor /proc/cpuinfo)
1050 .Build requirements differ from run requirements
1053 Building the RPM requires building a source distribution which itself requires
1054 the Qt development tools `uic` and `moc`. These can usually be obtained by
1055 installing the _qt-devel_ package.
1060 ==== OS X: .dmg packages
1062 The OS X Package is built using OS X packaging tools, based on information
1063 found in the source tree under 'packaging/macosx'.
1065 In the wireshark directory, type:
1071 to build the OS X Package.
1075 ==== Win32: NSIS .exe installer
1077 The _Nullsoft Install System_ is a free installer generator for Win32
1078 based systems; instructions how to install it can be found in <<ChToolsNSIS>>.
1079 NSIS is script based, you will find the Wireshark installer
1080 generation script at: 'packaging/nsis/wireshark.nsi'.
1082 When building with CMake you must first build the 'nsis_package_prep' target,
1083 followed by the 'nsis_package' target, e.g.
1086 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
1087 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
1090 Splitting the packaging projects in this way allows for code signing.
1093 .This might take a while
1095 Please be patient while the package is compressed.
1096 It might take some time, even on fast machines.
1099 If everything went well, you will now find something like:
1100 'wireshark-setup-wireshark-version:[].exe' in
1101 the 'packaging/nsis' directory in the source tree.
1103 [[ChSrcPortableApps]]
1105 ==== Win32: PortableApps .paf.exe package
1107 _PortableApps.com_ is an environment that lets users run popular applications
1108 from portable media such as flash drives and cloud drive services.
1110 Install the 'PortableApps.com Platform'. Install for ``all users``, which
1111 will place it in `C:\PortableApps`. Add the following apps:
1113 - NSIS Portable (Unicode)
1114 - PortableApps.com Installer
1115 - PortableApps.com Launcher
1116 - PortableApps.com AppCompactor
1118 When building with CMake you must first build the 'nsis_package_prep' target
1119 (which takes care of general packaging dependencies), followed by the
1120 'portableapps_package' target, e.g.
1123 > msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
1124 > msbuild /m /p:Configuration=RelWithDebInfo portableapps_package.vcxproj
1128 .This might take a while
1130 Please be patient while the package is compressed.
1131 It might take some time, even on fast machines.
1134 If everything went well, you will now find something like:
1135 'WiresharkPortable_wireshark-major-minor-version:[].paf.exe' in
1136 the 'packaging/portableapps' directory.
1138 ++++++++++++++++++++++++++++++++++++++
1139 <!-- End of WSDG Chapter Sources -->
1140 ++++++++++++++++++++++++++++++++++++++
1142 // vim: set syntax=asciidoc: