forked from osmocom/wireshark
![Graham Bloice](/assets/img/avatar_default.png)
Corrected info about paths to built executable. Cross referenced empty debugger sections to the section with info. Change-Id: I4366825990f1a5286c7292c9f00e540160c1b5d0 Reviewed-on: https://code.wireshark.org/review/6520 Reviewed-by: Michael Mann <mmann78@netscape.net> Reviewed-by: Graham Bloice <graham.bloice@trihedral.com>
1191 lines
38 KiB
Text
1191 lines
38 KiB
Text
++++++++++++++++++++++++++++++++++++++
|
|
<!-- 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://code.google.com/p/gerrit/[Gerrit] code review sytem. 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 conrol 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
|
|
manange 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 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. 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.)
|
|
|
|
. 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-download-page:[]automated/src/[].
|
|
|
|
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-page:[]. 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
|
|
|
|
----
|
|
$ 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.bz2` 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.bz2` 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
|
|
|
|
Run the `autogen.sh` script at the top-level wireshark directory to configure
|
|
your build directory.
|
|
|
|
----
|
|
$ ./autogen.sh
|
|
$ ./configure
|
|
$ make
|
|
----
|
|
|
|
If you need to build with a non-standard configuration, you can run
|
|
|
|
----
|
|
$ ./configure --help
|
|
----
|
|
|
|
to see what options you have.
|
|
|
|
==== Win32 native
|
|
|
|
First, check the file 'config.nmake' to determine if it reflects your
|
|
configuration. The settings in this file are well documented but there are a lot
|
|
of them so please look closely. If you've installed the libraries and tools as
|
|
recommended there should be no need to change anything.
|
|
|
|
Many of the file and directory names used in the build process go past the old
|
|
8.3 naming limitations. As a result you should use the `cmd.exe` command
|
|
interpreter instead of the old `command.com`.
|
|
|
|
Be sure that your command-line environment is set up to compile
|
|
and link with MSV$$C++$$. When installing MSV$$C++$$, you can have your
|
|
system's environment set up to always allow compiling from the
|
|
command line, or you can invoke the vcvars32.bat script, which can
|
|
usually be found in the _VC98\Bin_subdirectory of the
|
|
directory in which Visual Studio was installed.
|
|
|
|
|
|
You should then cleanup any intermediate files, which are shipped for
|
|
convenience of Unix users, by typing at the command line prompt (cmd.exe):
|
|
|
|
----
|
|
> nmake -f Makefile.nmake distclean
|
|
----
|
|
|
|
After doing this, typing at the command line prompt (cmd.exe):
|
|
|
|
----
|
|
> nmake -f Makefile.nmake all
|
|
----
|
|
|
|
will start the whole Wireshark build process.
|
|
|
|
|
|
After the build process has successfully finished, you should find a
|
|
`wireshark.exe` and some other files
|
|
in the root 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 inpact
|
|
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
|
|
commandline to launch Wireshark would be:
|
|
|
|
----
|
|
$ 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
|
|
'wireshark-qt-release'. You can run the program from there by
|
|
launching the Wireshark.exe executable.
|
|
|
|
The older GTK based version is also available in the 'wireshark-gtk'
|
|
subdirectory. You can run the program from there by launching the
|
|
Wireshark-gtk.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:
|
|
|
|
----
|
|
$ 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:
|
|
|
|
----
|
|
$ 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.
|
|
|
|
[[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 shouldbe 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-web-site:[].
|
|
//
|
|
// 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 checkin.
|
|
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 sourcefile dissectors are more suitable to
|
|
be placed separate as plugin.
|
|
|
|
* 'Verify that your dissector code does not use prohibited or deprecated APIs.'
|
|
This can be done as follows:
|
|
+
|
|
----
|
|
$ perl <wireshark_root>/tools/checkAPIs.pl <source filename(s)>
|
|
----
|
|
|
|
* '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-site:[]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. Changes should be
|
|
pushed to a
|
|
http://test.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":
|
|
|
|
----
|
|
$ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master/snowcone-machine
|
|
----
|
|
|
|
If you have `git-review` installed you can upload the change with a lot less typing:
|
|
|
|
----
|
|
# 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:
|
|
|
|
----
|
|
# 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:
|
|
|
|
----
|
|
$ 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:
|
|
|
|
----
|
|
$ 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'.
|
|
|
|
[[ChSrcAdd]]
|
|
|
|
// Rewrite for Git ?
|
|
// === Add a new file to the Subversion repository
|
|
//
|
|
// The recommended way to commit new files is described in <<ChSrcContribute>>.
|
|
// However, the following might be of interest for contributing developers as well.
|
|
//
|
|
// [NOTE]
|
|
// ====
|
|
// These actions can only be performed by the Wireshark core developers who
|
|
// have write access to the Subversion repository. It is put in here to have
|
|
// all information in one place.
|
|
// ====
|
|
//
|
|
// If you (as a core developer) need to add a file to the SVN repository,
|
|
// then you need to perform the following steps:
|
|
//
|
|
// . Verify that that file is complete (has Wireshark boilerplate, `$Id$`, etc).
|
|
//
|
|
// . Add the new file(s) to the repository:
|
|
// +
|
|
// ----
|
|
// $ svn add new_file
|
|
// ----
|
|
//
|
|
// . Set the line ending property to 'native' for the new file(s):
|
|
// +
|
|
// ----
|
|
// $ svn propset svn:eol-style native new_file
|
|
// ----
|
|
//
|
|
// . Set version keyword to 'Id' for the new file(s):
|
|
// +
|
|
// ----
|
|
// $ svn propset svn:keywords Id new_file
|
|
// ----
|
|
//
|
|
// . Commit your changes, including the added file(s).
|
|
// +
|
|
// ----
|
|
// $ svn commit new_file other_files_you_modified
|
|
// ----
|
|
//
|
|
// 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.
|
|
|
|
[[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:
|
|
|
|
----
|
|
$ make debian-package
|
|
----
|
|
|
|
to build the Debian Package.
|
|
|
|
[[ChSrcRpm]]
|
|
|
|
==== Red Hat: .rpm packages
|
|
|
|
The RPM is built using rpmbuild (http://www.rpm.org/), which comes as standard on many flavours of Linux, including
|
|
Red Hat and Fedora. The process creates a clean build environment in _packaging/rpm/BUILD_every
|
|
time the RPM is built. The settings controlling the build are in _packaging/rpm/SPECS/wireshark.spec.in_.
|
|
After editing the settings in this file, _./configure_must be run again in the wireshark directory to
|
|
generate the actual specification script.
|
|
|
|
|
|
.Careful with that `configure` setting
|
|
[NOTE]
|
|
====
|
|
The SPEC file contains settings for the _configure_ used to set the RPM build
|
|
environment. These are completely independent of any settings passed to the
|
|
usual Wireshark `./configure`. The exception to this rule is that the _prefix_
|
|
given to `configure --prefix` is passed to rpmbuild.
|
|
====
|
|
|
|
In the wireshark directory, type:
|
|
|
|
----
|
|
$ make rpm-package
|
|
----
|
|
|
|
to build the RPM and source RPM. Once it is done, there will be a message stating where the built RPM can be found.
|
|
|
|
.This might take a while
|
|
[TIP]
|
|
====
|
|
Because this does a clean build as well as constructing the package this can
|
|
take quite a long time.
|
|
====
|
|
|
|
.Build requirements differ from run requirements
|
|
[TIP]
|
|
====
|
|
Building the RPM requires building a source distribution which itself requires
|
|
the Qt development tools `uic` and `moc`. These can usually be obtained by
|
|
installing the _qt-devel_ package.
|
|
====
|
|
|
|
[[ChSrcOSX]]
|
|
|
|
==== MAC OS X: .dmg packages
|
|
|
|
The MAC OS X Package is built using OS X packaging tools, based on information
|
|
found in the source tree under 'packaging/macosx'.
|
|
|
|
In the wireshark directory, type:
|
|
|
|
----
|
|
$ make osx-package
|
|
----
|
|
|
|
to build the MAC OS X Package.
|
|
|
|
[[ChSrcNSIS]]
|
|
|
|
==== Win32: NSIS .exe installer
|
|
|
|
The _Nullsoft Install System_ is a free installer generator for Win32
|
|
based systems; instructions how to install it can be found in <<ChToolsNSIS>>.
|
|
NSIS is script based, you will find the Wireshark installer
|
|
generation script at: 'packaging/nsis/wireshark.nsi'.
|
|
|
|
You will probably have to modify the MAKENSIS setting in the
|
|
'config.nmake' file to specify where the NSIS binaries
|
|
are installed.
|
|
|
|
In the top-level source directory type:
|
|
|
|
----
|
|
> nmake -f makefile.nmake packaging
|
|
----
|
|
|
|
to build the installer.
|
|
|
|
[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.
|
|
|
|
[[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.
|
|
|
|
You will probably have to modify the MAKENSIS setting in the
|
|
'config.nmake' file to specify where the NSIS binaries
|
|
are installed.
|
|
|
|
In the top-level source directory type:
|
|
|
|
----
|
|
> nmake -f makefile.nmake packaging_papps
|
|
----
|
|
|
|
to build the installer.
|
|
|
|
[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-major-minor-version:[].paf.exe' in
|
|
the 'packaging/portableapps/win32' directory.
|
|
|
|
++++++++++++++++++++++++++++++++++++++
|
|
<!-- End of WSDG Chapter Sources -->
|
|
++++++++++++++++++++++++++++++++++++++
|
|
|
|
// vim: set syntax=asciidoc:
|