2018-02-05 16:59:45 +00:00
|
|
|
|
// WSDG Chapter Sources
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 21:57:28 +00:00
|
|
|
|
[[ChapterSources]]
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
== 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
|
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
This chapter will not explain the source file contents in detail,
|
|
|
|
|
such as where to find specific functionality. This is done in
|
2014-01-24 18:55:27 +00:00
|
|
|
|
<<ChCodeOverview>>.
|
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
[[ChSrcGitRepository]]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
=== The Wireshark Git repository
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
http://git-scm.com/[Git] is used to keep track of the changes made to the
|
2018-02-04 23:15:02 +00:00
|
|
|
|
Wireshark source code. The code is stored inside Wireshark project’s Git
|
2014-01-25 00:17:46 +00:00
|
|
|
|
repository located at a server at the wireshark.org domain.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
Changes to the official repository are managed using the
|
2016-01-09 22:03:02 +00:00
|
|
|
|
https://www.gerritcodereview.com/[Gerrit] code review system. Gerrit
|
2014-04-10 17:56:52 +00:00
|
|
|
|
makes it easy to test and discuss changes before they are
|
2014-02-25 20:22:50 +00:00
|
|
|
|
pushed to the main repository. For an overview of Gerrit see the
|
|
|
|
|
https://code.wireshark.org/review/Documentation/intro-quick.html[Quick
|
|
|
|
|
Introduction].
|
2014-01-27 18:43:57 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
.Why Git?
|
2014-01-27 18:43:57 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
Git is a fast, flexible way of managing source code. It allows large
|
|
|
|
|
scale distributed development and ensures data integrity.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
.Why Gerrit?
|
|
|
|
|
|
|
|
|
|
Gerrit makes it easy to contribute. You can sign in with any OpenID
|
2018-02-04 23:15:02 +00:00
|
|
|
|
provider and push your changes. It’s usable from both the web and
|
2014-02-25 20:22:50 +00:00
|
|
|
|
command line and is integrated with many popular tools.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2015-11-21 16:08:28 +00:00
|
|
|
|
.Git is our *third* revision control system
|
2014-01-25 00:17:46 +00:00
|
|
|
|
[NOTE]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
2014-01-25 00:17:46 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
Using Wireshark’s Git repository you can:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
* 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
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcWebInterface]]
|
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
==== 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
|
|
|
|
|
|
2019-03-04 18:33:43 +00:00
|
|
|
|
==== Git Naming Conventions
|
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
Like most revision control systems, Git uses
|
|
|
|
|
http://en.wikipedia.org/wiki/Branching_%28revision_control%29[branching] to
|
2015-11-21 16:08:28 +00:00
|
|
|
|
manage different copies of the source code and allow parallel development.
|
2019-03-04 18:33:43 +00:00
|
|
|
|
Wireshark uses the following branch naming conventions:
|
|
|
|
|
|
|
|
|
|
* _master_: Main feature development and odd-numbered “development” releases.
|
|
|
|
|
* _master-x.y_: Stable release maintenance. For example, master-3.0 is used
|
|
|
|
|
to manage the 3.0.x official releases.
|
2014-01-25 00:17:46 +00:00
|
|
|
|
|
2019-03-04 18:33:43 +00:00
|
|
|
|
Tags for major releases and release candidates consist of a “v” followed
|
|
|
|
|
by a version number such as “v3.0.1” or “v3.0.3rc0”. Major releases
|
|
|
|
|
additionally have a tag prefixed with “wireshark-” followed by a version
|
|
|
|
|
number, such as “wireshark-3.0.0”.
|
2014-01-25 00:17:46 +00:00
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[[ChSrcObtain]]
|
|
|
|
|
|
|
|
|
|
=== Obtain the Wireshark sources
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
There are several ways to obtain the sources from Wireshark’s Git
|
2014-01-25 00:17:46 +00:00
|
|
|
|
repository.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[TIP]
|
2014-01-25 00:17:46 +00:00
|
|
|
|
.Check out from the master branch using Git.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
2014-04-02 18:05:04 +00:00
|
|
|
|
Using Git is much easier than synchronizing your source tree by hand using any
|
2014-04-10 17:56:52 +00:00
|
|
|
|
of the snapshot methods mentioned below. Git merges changes into your
|
2014-04-02 18:05:04 +00:00
|
|
|
|
personal source tree in a very comfortable and quick way. So you can update your
|
|
|
|
|
source tree several times a day without much effort.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
|
|
|
|
|
[NOTE]
|
2014-01-25 00:17:46 +00:00
|
|
|
|
.Keep your sources up to date
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
The following ways to retrieve the Wireshark sources are sorted in
|
2014-02-25 20:22:50 +00:00
|
|
|
|
decreasing source timeliness. If you plan to commit changes you've
|
2018-02-04 23:15:02 +00:00
|
|
|
|
made to the sources, it’s a good idea to keep your private source
|
2014-02-25 20:22:50 +00:00
|
|
|
|
tree as current as possible.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
|
|
|
|
|
The age mentioned in the following sections indicates the age of the
|
|
|
|
|
most recent change in that set of the sources.
|
|
|
|
|
|
|
|
|
|
[[ChSrcAnon]]
|
2014-02-25 20:22:50 +00:00
|
|
|
|
// Retain ChSrcAnon for backward compatibility
|
|
|
|
|
[[ChSrcGit]]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
==== Git over SSH or HTTPS
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
Recommended for development purposes.
|
|
|
|
|
|
|
|
|
|
Age: a few minutes.
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
You can use a Git client to download the source code from Wireshark’s code
|
2015-05-03 22:47:11 +00:00
|
|
|
|
review system. Anyone can clone from the anonymous git URL:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
* {wireshark-git-anonhttp-url}
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
If you create a Gerrit account you can clone from an authenticated URL:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
* {wireshark-git-ssh-url}
|
|
|
|
|
* {wireshark-git-http-url}
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 00:17:46 +00:00
|
|
|
|
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
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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
|
2018-02-04 23:15:02 +00:00
|
|
|
|
advantage of Gerrit’s HTTP REST API.
|
2014-02-25 20:22:50 +00:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
. Sign in to {wireshark-code-review-url} using OpenID (click Register or Sign
|
2015-05-03 22:47:11 +00:00
|
|
|
|
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_.
|
2014-02-25 20:22:50 +00:00
|
|
|
|
|
|
|
|
|
. 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
|
2018-02-04 19:39:56 +00:00
|
|
|
|
username is `henry.perry`.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
. Select _SSH Public Keys_ and add one or more keys. You will typically
|
|
|
|
|
upload a key for each computer that you use.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
. 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.)
|
2015-02-02 22:32:28 +00:00
|
|
|
|
To install it from Chocolatey run
|
|
|
|
|
+
|
|
|
|
|
--
|
|
|
|
|
----
|
2018-10-13 13:56:02 +00:00
|
|
|
|
# If you have not already, install Python 3 first and then *restart* the shell.
|
|
|
|
|
PS$>choco install -y python3
|
|
|
|
|
PS$>choco install -y git-review -source python
|
|
|
|
|
# Make sure that "git-review" is present in our path (edit the version as needed).
|
|
|
|
|
PS$>$userpath = [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::User)
|
|
|
|
|
PS$>$userpath += ";C:\Python37\Scripts"
|
|
|
|
|
PS$>[Environment]::SetEnvironmentVariable("Path", $userpath, [EnvironmentVariableTarget]::User)
|
|
|
|
|
PS$>RefreshEnv
|
2015-02-02 22:32:28 +00:00
|
|
|
|
----
|
|
|
|
|
--
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
. Now on to the command line. First, make sure `git` works:
|
2014-02-25 23:41:14 +00:00
|
|
|
|
+
|
2014-02-25 20:22:50 +00:00
|
|
|
|
--
|
2014-01-25 00:17:46 +00:00
|
|
|
|
----
|
2014-02-25 20:22:50 +00:00
|
|
|
|
$ git --version
|
2014-01-25 00:17:46 +00:00
|
|
|
|
----
|
2014-02-25 20:22:50 +00:00
|
|
|
|
--
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
. 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.
|
2014-02-25 23:41:14 +00:00
|
|
|
|
+
|
2014-02-25 20:22:50 +00:00
|
|
|
|
--
|
|
|
|
|
----
|
|
|
|
|
$ git config --global user.name "Henry Perry"
|
|
|
|
|
$ git config --global user.email henry.perry@example.com
|
|
|
|
|
----
|
|
|
|
|
--
|
|
|
|
|
|
|
|
|
|
. Next, clone the Wireshark master:
|
2014-02-25 23:41:14 +00:00
|
|
|
|
+
|
2014-02-25 20:22:50 +00:00
|
|
|
|
--
|
|
|
|
|
----
|
|
|
|
|
$ 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.
|
|
|
|
|
--
|
|
|
|
|
|
2014-03-16 18:59:17 +00:00
|
|
|
|
. Then set up the git pre-commit hook and the push address:
|
2014-02-25 23:41:14 +00:00
|
|
|
|
+
|
2014-02-25 20:22:50 +00:00
|
|
|
|
--
|
|
|
|
|
----
|
|
|
|
|
$ cd wireshark
|
2014-03-16 18:59:17 +00:00
|
|
|
|
$ 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
|
2014-04-10 17:56:52 +00:00
|
|
|
|
does not contain trivial errors. It will also warn if it is out of sync
|
|
|
|
|
with its master copy in the tools/ directory.
|
2014-03-16 18:59:17 +00:00
|
|
|
|
The change in the push address is necessary: We have an asymmetric
|
|
|
|
|
process for pulling and pushing because of gerrit.
|
|
|
|
|
--
|
|
|
|
|
|
|
|
|
|
. Initialize git-review.
|
|
|
|
|
+
|
|
|
|
|
--
|
|
|
|
|
----
|
2014-02-25 20:22:50 +00:00
|
|
|
|
$ git review -s
|
|
|
|
|
----
|
|
|
|
|
This prepares your local repository for use with Gerrit, including
|
|
|
|
|
installing the `commit-msg` hook script.
|
|
|
|
|
--
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcSVNWeb]]
|
2014-02-25 20:22:50 +00:00
|
|
|
|
// Retain ChSrcSVNWeb for backward compatibility
|
|
|
|
|
[[ChSrcGitWeb]]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
==== Git web interface
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
Recommended for informational purposes only, as only individual files can
|
|
|
|
|
be downloaded.
|
|
|
|
|
|
2014-04-10 17:56:52 +00:00
|
|
|
|
Age: a few minutes (same as anonymous Git access).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[ChSrcBuildbot]]
|
|
|
|
|
|
|
|
|
|
==== Buildbot Snapshots
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
Recommended for development purposes, if direct Git access isn't
|
2014-01-24 18:55:27 +00:00
|
|
|
|
possible (e.g. because of a restrictive firewall).
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
Age: some number of minutes (a bit older than the Git access).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2015-11-21 16:08:28 +00:00
|
|
|
|
The Buildbot server will automatically start to generate a snapshot of
|
2018-02-04 23:15:02 +00:00
|
|
|
|
Wireshark’s source tree after a source code change is committed. These
|
2016-11-01 21:35:29 +00:00
|
|
|
|
snapshots can be found at {wireshark-snapshots-url}.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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
|
2015-11-21 16:08:28 +00:00
|
|
|
|
obtained by downloading the Buildbot snapshots. However, if you are
|
2014-01-24 18:55:27 +00:00
|
|
|
|
going to maintain your sources in parallel to the "official" sources
|
2018-02-04 23:15:02 +00:00
|
|
|
|
for some time, it’s recommended to use the anonymous (or authenticated)
|
2014-04-10 17:56:52 +00:00
|
|
|
|
Git access if possible (believe it, it will save you a lot of time).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcReleased]]
|
|
|
|
|
|
|
|
|
|
==== Released sources
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
Recommended for building pristine packages.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
Age: from days to weeks.
|
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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 :-).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcUpdating]]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
=== Update the Wireshark sources
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[TIP]
|
2015-11-21 16:08:28 +00:00
|
|
|
|
.Take a look at the Buildbot first
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
2014-02-25 20:22:50 +00:00
|
|
|
|
As development evolves, the Wireshark sources are compilable
|
|
|
|
|
most of the time -- but not always. You should take a look at
|
2016-11-01 21:35:29 +00:00
|
|
|
|
{wireshark-buildbot-url} before fetching or pulling to make
|
2014-02-25 20:22:50 +00:00
|
|
|
|
sure the builds are in good shape.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
|
|
|
|
|
[[ChSrcAnonUpdate]]
|
2014-02-25 20:22:50 +00:00
|
|
|
|
// Retain ChSrcAnonUpdate for backward compatibility
|
|
|
|
|
[[ChSrcGitUpdate]]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
==== Update Using Git
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
After you clone Wireshark’s Git repository you can update
|
2014-02-25 20:22:50 +00:00
|
|
|
|
by running
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-02-25 20:22:50 +00:00
|
|
|
|
----
|
|
|
|
|
$ git status
|
|
|
|
|
$ git pull
|
|
|
|
|
----
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcZipUpdate]]
|
|
|
|
|
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
==== Update Using Source Archives
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2016-07-27 22:31:06 +00:00
|
|
|
|
First of all, you will download the new `.tar.xz` file of the official
|
2014-02-25 20:22:50 +00:00
|
|
|
|
sources the way you did it the first time.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
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
|
2016-07-27 22:31:06 +00:00
|
|
|
|
the content of the `.tar.xz` file into a new directory and use a good
|
2018-10-12 20:32:32 +00:00
|
|
|
|
merge tool (e.g. http://winmerge.sourceforge.net/[]for Windows) to bring
|
2014-01-24 18:55:27 +00:00
|
|
|
|
your personal source tree in sync with the official sources again.
|
|
|
|
|
|
2014-02-25 20:22:50 +00:00
|
|
|
|
This method can be problematic and can be much more difficult and
|
|
|
|
|
error-prone than using Git.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcBuildFirstTime]]
|
|
|
|
|
|
|
|
|
|
=== Build Wireshark
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
The sources contain several documentation files. It’s a good idea to read these
|
2014-01-25 01:01:04 +00:00
|
|
|
|
files first. After obtaining the sources, tools and libraries, the first place
|
2018-02-04 19:39:56 +00:00
|
|
|
|
to look at is _doc/README.developer_. Inside you will find the latest
|
2014-01-25 01:01:04 +00:00
|
|
|
|
information for Wireshark development for all supported platforms.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
.Build Wireshark before changing anything
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[TIP]
|
|
|
|
|
====
|
2014-01-25 01:01:04 +00:00
|
|
|
|
It is a very good idea to first test your complete build environment
|
|
|
|
|
(including running and debugging Wireshark) before making any changes
|
2014-01-24 18:55:27 +00:00
|
|
|
|
to the source code (unless otherwise noted).
|
|
|
|
|
====
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
Building Wireshark for the first time depends on your platform.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-27 05:10:34 +00:00
|
|
|
|
==== Building on Unix
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
The recommended (and fastest) way to build Wireshark is with CMake and
|
|
|
|
|
Ninja:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2018-03-16 22:20:18 +00:00
|
|
|
|
# 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 .)
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
If you need to build with a non-standard configuration, you can run
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2018-03-16 22:20:18 +00:00
|
|
|
|
$ cmake -LH ../wireshark
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
to see what options you have.
|
|
|
|
|
|
2018-10-12 20:24:45 +00:00
|
|
|
|
==== Windows native
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2015-11-01 21:07:42 +00:00
|
|
|
|
Follow the build procedure in <<ChWin32Build>> to build Wireshark.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
After the build process has successfully finished, you should find a
|
2015-11-01 21:07:42 +00:00
|
|
|
|
`Wireshark.exe` and some other files in the `run\RelWithDebInfo` directory.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcRunFirstTime]]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
=== Run generated Wireshark
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[TIP]
|
2018-08-21 23:37:52 +00:00
|
|
|
|
.Beware of multiple Wiresharks
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
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]]
|
|
|
|
|
|
2018-10-12 20:24:45 +00:00
|
|
|
|
==== Unix-like platforms
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
After a successful build you can run Wireshark right from the build
|
2018-02-04 23:15:02 +00:00
|
|
|
|
directory. Still the program would need to know that it’s being run from
|
2015-11-21 16:08:28 +00:00
|
|
|
|
the build directory and not from its install location. This has an impact
|
2014-01-24 18:55:27 +00:00
|
|
|
|
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
|
2015-11-21 16:08:28 +00:00
|
|
|
|
command line to launch Wireshark would be:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2018-11-12 09:44:32 +00:00
|
|
|
|
$ WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1 ./run/wireshark
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
There’s no need to run Wireshark as root user, you just won't be able to
|
2014-01-24 18:55:27 +00:00
|
|
|
|
capture. When you opt to run Wireshark this way, your terminal output can
|
|
|
|
|
be informative when things don't work as expected.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[[ChSrcRunFirstTimeWin32]]
|
|
|
|
|
|
|
|
|
|
|
2018-10-12 20:34:37 +00:00
|
|
|
|
==== Windows native
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
During the build all relevant program files are collected in a
|
|
|
|
|
subdirectory `run\RelWithDebInfo`. You can run the program from there by
|
2015-01-12 15:12:04 +00:00
|
|
|
|
launching the Wireshark.exe executable.
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[[ChSrcDebug]]
|
|
|
|
|
|
2018-04-09 04:11:26 +00:00
|
|
|
|
=== Debug Your Generated Wireshark
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcUnixDebug]]
|
|
|
|
|
|
|
|
|
|
|
2019-01-03 22:21:59 +00:00
|
|
|
|
==== Unix-Like Platforms
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-08-21 23:37:52 +00:00
|
|
|
|
You can debug using command-line debuggers such as gdb, dbx, or lldb.
|
2019-01-03 22:21:59 +00:00
|
|
|
|
If you prefer a graphic debugger, you can use an IDE or debugging frontend
|
|
|
|
|
such as Qt Creator, CLion, or Eclipse.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
Additional traps can be set on GLib by setting the `G_DEBUG` environment variable:
|
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2019-01-03 22:21:59 +00:00
|
|
|
|
$ G_DEBUG=fatal_criticals gdb wireshark
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
|
2018-08-21 23:37:52 +00:00
|
|
|
|
See https://developer.gnome.org/glib/stable/glib-running.html[]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcWin32Debug]]
|
|
|
|
|
|
|
|
|
|
|
2018-10-12 20:24:45 +00:00
|
|
|
|
==== Windows native
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2015-01-12 15:12:04 +00:00
|
|
|
|
You can debug using the Visual Studio Debugger or WinDbg. See the section
|
|
|
|
|
on using the <<ChToolsDebugger, Debugger Tools>>.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[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
|
2018-02-04 23:15:02 +00:00
|
|
|
|
and many, many others). There’s no "standard" or "default" development
|
2014-01-24 18:55:27 +00:00
|
|
|
|
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]
|
|
|
|
|
====
|
2018-02-04 23:15:02 +00:00
|
|
|
|
If you have an idea what you want to add or change it’s a good idea to
|
2014-01-24 18:55:27 +00:00
|
|
|
|
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).
|
|
|
|
|
====
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// XXX - Add a section on branching.
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[[ChSrcContribute]]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
=== Contribute your changes
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
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:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
* _It’s the right thing to do._ Other people who find your contributions useful
|
2014-01-25 01:01:04 +00:00
|
|
|
|
will appreciate them, and you will know that you have helped people in the
|
|
|
|
|
same way that the developers of Wireshark have helped you.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
* _You get free enhancements._ By making your code public, other developers have
|
2018-02-04 23:15:02 +00:00
|
|
|
|
a chance to make improvements, as there’s always room for improvements. In
|
2014-01-25 01:01:04 +00:00
|
|
|
|
addition someone may implement advanced features on top of your code, which
|
|
|
|
|
can be useful for yourself too.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
* _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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
There’s no direct way to push changes to the Git repository. Only a few people
|
2014-01-25 01:01:04 +00:00
|
|
|
|
are authorised to actually make changes to the source code (check-in changed
|
2014-04-02 18:05:04 +00:00
|
|
|
|
files). If you want to submit your changes, you should upload them to the code
|
2016-11-01 21:35:29 +00:00
|
|
|
|
review system at {wireshark-code-review-url}. This requires you to set up git
|
2015-05-03 22:47:11 +00:00
|
|
|
|
as described at <<ChSrcGit>>.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 02:26:12 +00:00
|
|
|
|
[[ChSrcDiffWhat]]
|
2014-04-10 17:56:52 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// ==== 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.
|
2014-01-25 02:26:12 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcGeneratePatch]]
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// ==== 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.
|
2014-01-25 02:26:12 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcSVNDiff]]
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
//
|
|
|
|
|
// ===== 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.
|
2019-01-04 20:00:59 +00:00
|
|
|
|
// _packet-myprotocol.c_, you can use `svn add` to add it to your local tree before generating the patch.
|
2015-11-21 16:08:28 +00:00
|
|
|
|
// Similarly, you can use `svn rm` for files that should be removed.
|
2014-01-25 02:26:12 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcSVNGUIDiff]]
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// ===== 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
|
2019-01-04 20:00:59 +00:00
|
|
|
|
// specific configuration - like modifying _config.nmake_ so that it uses
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// 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
|
2019-01-04 20:00:59 +00:00
|
|
|
|
// _packet-xxx.c_ for a
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// 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.
|
2014-01-25 02:26:12 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcDiff]]
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// ===== 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
|
2016-11-01 21:35:29 +00:00
|
|
|
|
// (hopefully the latest SVN files) from {wireshark-main-url}.
|
2014-01-25 01:01:04 +00:00
|
|
|
|
//
|
|
|
|
|
// 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
|
|
|
|
|
// ----
|
|
|
|
|
//
|
2018-02-04 23:15:02 +00:00
|
|
|
|
// It’s a good idea to run `make distclean` before the
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// 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
|
2019-01-04 20:00:59 +00:00
|
|
|
|
// _config.nmake_ file.
|
2014-01-25 01:01:04 +00:00
|
|
|
|
//
|
|
|
|
|
//
|
|
|
|
|
// .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
|
|
|
|
|
// ----
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcGoodPatch]]
|
|
|
|
|
|
2019-01-04 20:00:59 +00:00
|
|
|
|
==== Some Tips For A Good Patch
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
Some tips that will make the merging of your changes into Git much more likely
|
|
|
|
|
(and you want exactly that, don't you?):
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
* _Use the latest Git sources._ It’s a good idea to work with the same
|
2014-04-30 23:56:50 +00:00
|
|
|
|
sources that are used by the other developers. This usually makes it much
|
2014-01-25 01:01:04 +00:00
|
|
|
|
easier to apply your patch. For information about the different ways to get
|
|
|
|
|
the sources, see <<ChSrcObtain>>.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Update your sources just before making a patch._ For the same reasons as the
|
2014-01-25 01:01:04 +00:00
|
|
|
|
previous point.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Inspect your patch carefully._ Run `git diff` and make sure you aren't
|
2014-01-25 01:01:04 +00:00
|
|
|
|
adding, removing, or omitting anything you shouldn't.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2019-01-04 20:00:59 +00:00
|
|
|
|
// * _Do a "make clean" before generating the patch._ This removes a lot of
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// 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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
// XXX - What *are* good topic names?
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Find a good descriptive topic name for your patch._ Short, specific
|
|
|
|
|
names are preferred. _snowcone-machine-protocol_ is good, your name or
|
2014-01-25 01:01:04 +00:00
|
|
|
|
your company name isn't.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Don't put unrelated things into one large patch._ A few smaller patches are
|
2014-01-25 01:01:04 +00:00
|
|
|
|
usually easier to apply (but also don't put every changed line into a separate
|
2019-05-18 21:43:08 +00:00
|
|
|
|
patch).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
.Please remember
|
|
|
|
|
[NOTE]
|
|
|
|
|
====
|
|
|
|
|
Wireshark is a volunteer effort. You aren't paying to have your code reviewed
|
|
|
|
|
and integrated.
|
|
|
|
|
====
|
|
|
|
|
|
2019-05-18 21:43:08 +00:00
|
|
|
|
[[ChSrcGoodCommitMessage]]
|
|
|
|
|
|
|
|
|
|
==== Writing a Good Commit Message
|
|
|
|
|
|
|
|
|
|
When running git commit, you will be prompted to describe the change. Here are
|
|
|
|
|
some guidelines on how to make that message actually useful to other people (and
|
|
|
|
|
to scripts that may try to parse it):
|
|
|
|
|
|
|
|
|
|
* _Provide a very brief description (under 60 characters) of the change in the first line._
|
|
|
|
|
If the change is specific to a single protocol, start this line with the abbreviated name
|
|
|
|
|
of the protocol and a colon. If the change is not complete yet prefix the line with [WIP]
|
|
|
|
|
to inform this change not to be submitted yet. This can later be removed.
|
|
|
|
|
|
|
|
|
|
* _Insert a single blank line after the first line._
|
|
|
|
|
|
|
|
|
|
* _Provide a detailed description of the change in the following lines_, breaking paragraphs
|
|
|
|
|
where needed. Limit each line to 80 characters. You can also add metadata at the bottom of
|
|
|
|
|
the commit message which will be used by Gerrit for searching and triggering Bugzilla
|
|
|
|
|
integration. Each line of the footer is of the form Label: value. There can be no extra
|
|
|
|
|
line-breaks between footer lines.
|
|
|
|
|
|
|
|
|
|
Wireshark currently supports the following metadata tags:
|
|
|
|
|
|
|
|
|
|
.Commit message tags
|
|
|
|
|
[options="header"]
|
|
|
|
|
|===============
|
|
|
|
|
|Tag|Meaning
|
|
|
|
|
|`Change-id`|A unique hash describing the change, which is generated automatically by
|
|
|
|
|
the git commit-msg hook which you installed during setup. This should not be changed,
|
|
|
|
|
even when rebasing or amending a commit following code review. If you pass --no-verify
|
|
|
|
|
to git commit you will have to add this line yourself.
|
|
|
|
|
|`Bug`|Make Gerrit automatically add a comment and close the given bug number when the
|
|
|
|
|
commit is merged. For use when the change does fully fix the issue.
|
|
|
|
|
|`Ping-Bug`|Make Gerrit just add a comment to the referenced bug. For use when the change
|
|
|
|
|
is related but does not fully fix the issue.
|
|
|
|
|
|===============
|
|
|
|
|
|
|
|
|
|
[NOTE]
|
|
|
|
|
====
|
|
|
|
|
The `Bug` and `Ping-Bug` tags are particularly useful if a capture file has been provided
|
|
|
|
|
via a Bugzilla entry in parallel with the change. All non-trivial fixes to dissectors
|
|
|
|
|
should try to do this.
|
|
|
|
|
====
|
|
|
|
|
|
|
|
|
|
Putting all that together, we get the following example:
|
|
|
|
|
|
|
|
|
|
[source]
|
|
|
|
|
----
|
|
|
|
|
MIPv6: fix dissection of Service Selection Identifier
|
|
|
|
|
|
|
|
|
|
APN field is not encoded as a dotted string so the first character is not a length
|
|
|
|
|
|
|
|
|
|
Bug: 10323
|
|
|
|
|
Change-Id: Ia62137c785d505e9d0f1536a333b421a85480741
|
|
|
|
|
----
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[[ChSrcCodeRequirements]]
|
|
|
|
|
|
|
|
|
|
==== Code Requirements
|
|
|
|
|
|
|
|
|
|
The core maintainers have done a lot of work fixing bugs and making code
|
|
|
|
|
compile on the various platforms Wireshark supports.
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
To ensure Wireshark’s source code quality, and to reduce the workload of the
|
2014-01-25 01:01:04 +00:00
|
|
|
|
core maintainers, there are some things you should think about _before_
|
|
|
|
|
submitting a patch.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
.Pay attention to the coding guidelines
|
|
|
|
|
[WARNING]
|
|
|
|
|
====
|
2014-01-25 01:01:04 +00:00
|
|
|
|
Ignoring the code requirements will make it very likely that your patch will
|
|
|
|
|
be rejected.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Follow the Wireshark source code style guide._ Just because something
|
2014-01-25 01:01:04 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Submit dissectors as built-in whenever possible._ Developing a new dissector
|
2018-02-04 23:15:02 +00:00
|
|
|
|
as a plugin is a good idea because compiling and testing is quicker, but it’s
|
2015-11-21 16:08:28 +00:00
|
|
|
|
best to convert dissectors to the built-in style before submitting for check in.
|
2014-01-25 01:01:04 +00:00
|
|
|
|
This reduces the number of files that must be installed with Wireshark and
|
|
|
|
|
ensures your dissector will be available on all platforms.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
+
|
|
|
|
|
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
|
2015-11-21 16:08:28 +00:00
|
|
|
|
different approach, and some multiple source file dissectors are more suitable to
|
|
|
|
|
be placed separately as plugins.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Ensure Wireshark Git Pre-Commit Hook is in the repository._ In your local
|
2017-11-25 19:18:06 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
+
|
2017-11-25 19:18:06 +00:00
|
|
|
|
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).
|
2018-06-27 23:14:18 +00:00
|
|
|
|
+
|
2018-10-12 20:24:45 +00:00
|
|
|
|
|
|
|
|
|
Additionally, if your system supports symbolic links, as all UNIX-like
|
|
|
|
|
platforms do, you can use them instead of copying files. Running ln -s
|
|
|
|
|
./tools/pre-commit .git/hooks creates a symbolic link that will make the
|
|
|
|
|
hook to be up-to-date with the current master. The same can be done for
|
|
|
|
|
commit-msg script.
|
2018-06-27 23:14:18 +00:00
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
* _Fuzz test your changes!_ Fuzz testing is a very
|
2014-01-24 18:55:27 +00:00
|
|
|
|
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:
|
2016-11-01 21:35:29 +00:00
|
|
|
|
{wireshark-wiki-url}FuzzTesting for details.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
[[ChSrcUpload]]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
==== Uploading your changes
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2016-11-01 21:35:29 +00:00
|
|
|
|
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>>.
|
2015-05-03 22:47:11 +00:00
|
|
|
|
|
|
|
|
|
Changes should be pushed to a
|
|
|
|
|
https://code.wireshark.org/review/Documentation/user-upload.html#push_create[magical "refs/for" branch]
|
2014-01-25 01:01:04 +00:00
|
|
|
|
in Gerrit. For example, to upload your new Snowcone Machine Protocol dissector
|
|
|
|
|
you could push to refs/for/master with the topic "snowcone-machine":
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-25 01:01:04 +00:00
|
|
|
|
----
|
|
|
|
|
$ git push ssh://my.username@code.wireshark.org:29418/wireshark HEAD:refs/for/master/snowcone-machine
|
|
|
|
|
----
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2015-05-03 22:47:11 +00:00
|
|
|
|
The username `my.username` is the one which was given during registration with
|
|
|
|
|
the review system.
|
|
|
|
|
|
2014-04-02 18:05:04 +00:00
|
|
|
|
If you have `git-review` installed you can upload the change with a lot less typing:
|
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-04-02 18:05:04 +00:00
|
|
|
|
----
|
|
|
|
|
# Note: The "-f" flag deletes your current branch.
|
|
|
|
|
$ git review -f
|
|
|
|
|
----
|
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
You can push using any Git client. Many clients have support for Gerrit, either
|
|
|
|
|
built in or via an additional module.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2019-05-27 10:29:37 +00:00
|
|
|
|
The Change-Id is very relevant in the review process, since it's the key used
|
|
|
|
|
to identify one change. See the
|
|
|
|
|
https://gerrit-review.googlesource.com/Documentation/user-changeid.html[Gerrit manual]
|
|
|
|
|
for more details.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
You might get one of the following responses to your patch request:
|
|
|
|
|
|
2014-02-25 16:20:22 +00:00
|
|
|
|
* Your patch is checked into the repository. Congratulations!
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
* 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.
|
2015-11-11 17:49:17 +00:00
|
|
|
|
|
2014-01-25 01:01:04 +00:00
|
|
|
|
If you're concerned, feel free to add a comment to the patch or send an email
|
2018-02-04 23:15:02 +00:00
|
|
|
|
to the developer’s list asking for status. But please be patient: most if not
|
2014-01-25 01:01:04 +00:00
|
|
|
|
all of us do this in our spare time.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-04-02 18:05:04 +00:00
|
|
|
|
[[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:
|
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-04-02 18:05:04 +00:00
|
|
|
|
----
|
|
|
|
|
# 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
|
|
|
|
|
$ ...
|
|
|
|
|
|
2019-02-14 23:23:05 +00:00
|
|
|
|
# OPTIONAL: Add entries to docbook/release-notes.adoc.
|
|
|
|
|
$ $EDITOR docbook/release-notes.adoc
|
2014-04-02 18:05:04 +00:00
|
|
|
|
|
|
|
|
|
# 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.
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[[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
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
Given the file _new.diff_ containing a unified diff,
|
2014-01-24 18:55:27 +00:00
|
|
|
|
the right way to call the patch tool depends on what the pathnames in
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_new.diff_ look like.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
If they're relative to the top-level source directory (for example, if a
|
2018-02-04 23:15:02 +00:00
|
|
|
|
patch to _prefs.c_ just has _prefs.c_ as the file name) you’d run it as:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
$ patch -p0 < new.diff
|
|
|
|
|
----
|
|
|
|
|
|
2018-02-04 23:15:02 +00:00
|
|
|
|
If they're relative to a higher-level directory, you’d replace 0 with the
|
2014-01-24 18:55:27 +00:00
|
|
|
|
number of higher-level directories in the path, e.g. if the names are
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_wireshark.orig/prefs.c_ and
|
2018-02-04 23:15:02 +00:00
|
|
|
|
_wireshark.mine/prefs.c_, you’d run it with:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
$ patch -p1 < new.diff
|
|
|
|
|
----
|
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
If they're relative to a _subdirectory_ of the top-level
|
2018-02-04 23:15:02 +00:00
|
|
|
|
directory, you’d run `patch` in _that_ directory and run it with `-p0`.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
If you run it without `-pat` all, the patch tool
|
|
|
|
|
flattens path names, so that if you
|
2018-04-15 21:40:36 +00:00
|
|
|
|
have a patch file with patches to _CMakeLists.txt_ and
|
|
|
|
|
_wiretap/CMakeLists.txt_,
|
2014-01-24 18:55:27 +00:00
|
|
|
|
it'll try to apply the first patch to the top-level
|
2018-04-15 21:40:36 +00:00
|
|
|
|
_CMakeLists.txt_ and then apply the
|
|
|
|
|
_wiretap/CMakeLists.txt_ patch to the top-level
|
|
|
|
|
_CMakeLists.txt_ as well.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
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
|
2018-02-04 23:15:02 +00:00
|
|
|
|
directory above that directory, you’d run it in the top-level source
|
2014-01-24 18:55:27 +00:00
|
|
|
|
directory.
|
|
|
|
|
|
|
|
|
|
If they're relative to a *subdirectory* -- for example,
|
2018-02-04 19:39:56 +00:00
|
|
|
|
if somebody did a patch to _packet-ip.c_ and ran `diff` or `git diff` in
|
2018-02-04 23:15:02 +00:00
|
|
|
|
the _epan/dissectors_ directory -- you’d run it in that subdirectory.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
It is preferred that people *not* submit patches like
|
|
|
|
|
that, especially if they're only patching files that exist in multiple
|
2018-04-15 21:40:36 +00:00
|
|
|
|
directories such as _CMakeLists.txt_.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcBinary]]
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
=== Binary Packaging
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
[[ChSrcVersioning]]
|
|
|
|
|
|
|
|
|
|
==== Packaging Guidelines
|
|
|
|
|
|
|
|
|
|
The following guidelines should be followed by anyone creating and
|
|
|
|
|
distributing third-party Wireshark packages or redistributing official
|
|
|
|
|
Wireshark packages.
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Spelling And Capitalization
|
|
|
|
|
|
|
|
|
|
Wireshark is spelled with a capital “W”, and with everything else lower
|
|
|
|
|
case. “WireShark” in particular is incorrect.
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Main URL
|
|
|
|
|
|
|
|
|
|
The official Wireshark project URL is https://www.wireshark.org/.
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Download URLs
|
|
|
|
|
|
|
|
|
|
Official packages are distributed on the main web server
|
|
|
|
|
(www.wireshark.org) and a
|
|
|
|
|
https://www.wireshark.org/download.html#spelunking[number of download
|
|
|
|
|
mirrors]. The canonical locations for packages are in the _all_versions_
|
|
|
|
|
subdirectories on each server.
|
|
|
|
|
|
|
|
|
|
For example, if your packaging system links to or downloads the
|
|
|
|
|
source tarball and you want to download from 1.na.dl.wireshark.org,
|
|
|
|
|
use
|
|
|
|
|
|
|
|
|
|
https://1.na.dl.wireshark.org/download/src/all-versions/wireshark-{wireshark-version}.tar.xz
|
|
|
|
|
|
|
|
|
|
instead of
|
|
|
|
|
|
|
|
|
|
https://1.na.dl.wireshark.org/download/src/wireshark-{wireshark-version}.tar.xz
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Artwork
|
|
|
|
|
|
|
|
|
|
Logo and icon artwork can be found in the _image_ directory in the
|
|
|
|
|
distribution. This is available online at
|
|
|
|
|
|
|
|
|
|
{wireshark-code-browse-url};a=tree;f=image;hb=HEAD
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Licensing
|
|
|
|
|
|
|
|
|
|
Wireshark is released under the GNU General Public License version 2 or
|
|
|
|
|
later. Make sure you and your package comply with this license.
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Trademarks
|
|
|
|
|
|
|
|
|
|
Wireshark and the “fin” logo are registered trademarks of the Wireshark
|
|
|
|
|
Foundation. Make sure you and your package comply with trademark law.
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Privileges
|
|
|
|
|
|
|
|
|
|
All function calls that require elevated privileges are in dumpcap.
|
|
|
|
|
|
|
|
|
|
WIRESHARK CONTAINS OVER THREE MILLION LINES OF SOURCE CODE. DO NOT RUN
|
|
|
|
|
THEM AS ROOT.
|
|
|
|
|
|
|
|
|
|
Warnings are displayed when Wireshark and TShark are run as root.
|
|
|
|
|
|
|
|
|
|
There are two <<ChToolsCMake,configure-time options>> on non-Windows
|
|
|
|
|
systems that affect the privileges a normal user needs to capture
|
|
|
|
|
traffic and list interfaces:
|
|
|
|
|
|
|
|
|
|
-DDUMPCAP_INSTALL_OPTION=capabilities::
|
|
|
|
|
Install dumpcap with cap_net_admin and cap_net_raw capabilities. Linux
|
|
|
|
|
only.
|
|
|
|
|
|
|
|
|
|
-DDUMPCAP_INSTALL_OPTION=suid::
|
|
|
|
|
Install dumpcap setuid root.
|
|
|
|
|
|
|
|
|
|
These are necessary for non-root users to be able to capture on most
|
|
|
|
|
systems, e.g. on Linux or FreeBSD if the user doesn't have permissions
|
|
|
|
|
to access /dev/bpf*. Setcap installation is preferred over setuid on
|
|
|
|
|
Linux. If `-DDUMPCAP_INSTALL_OPTION=capabilities` is used it will
|
|
|
|
|
override any setuid settings.
|
|
|
|
|
|
|
|
|
|
The `-DENABLE_CAP` option is only useful when dumpcap is installed
|
|
|
|
|
setuid. If it is enabled dumpcap will try to drop any setuid privileges
|
|
|
|
|
it may have while retaining the `CAP_NET_ADMIN` and `CAP_NET_RAW`
|
|
|
|
|
capabilities. It is enabled by default, if the Linux capabilities
|
|
|
|
|
library (on which it depends) is found.
|
|
|
|
|
|
|
|
|
|
Note that enabling setcap or setuid installation allows packet capture
|
|
|
|
|
for ALL users on your system. If this is not desired, you can restrict
|
|
|
|
|
dumpcap execution to a specific group or user. The following two examples
|
|
|
|
|
show how to restrict access using setcap and setuid respectively:
|
|
|
|
|
|
|
|
|
|
[source,sh]
|
|
|
|
|
----
|
|
|
|
|
# groupadd -g packetcapture
|
|
|
|
|
# chmod 750 /usr/bin/dumpcap
|
|
|
|
|
# chgrp packetcapture /usr/bin/dumpcap
|
|
|
|
|
# setcap cap_net_raw,cap_net_admin+ep /usr/bin/dumpcap
|
|
|
|
|
|
|
|
|
|
# groupadd -g packetcapture
|
|
|
|
|
# chgrp packetcapture /usr/bin/dumpcap
|
|
|
|
|
# chmod 4750 /usr/bin/dumpcap
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
[discrete]
|
|
|
|
|
===== Customization
|
|
|
|
|
|
2019-01-10 17:22:45 +00:00
|
|
|
|
Custom version information can be added by running
|
|
|
|
|
`tools/make-version.pl`. If your package contains significant changes we
|
|
|
|
|
recommend that you use this to differentiate it from official Wireshark
|
|
|
|
|
releases.
|
2019-01-09 23:48:55 +00:00
|
|
|
|
|
2019-01-10 17:22:45 +00:00
|
|
|
|
[source, sh]
|
|
|
|
|
----
|
|
|
|
|
$ tools/make-version.pl --set-release --untagged-version-extra=-{vcsinfo}-FooCorp --tagged-version-extra=-FooCorp
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
See `tools/make-version.pl` for details.
|
|
|
|
|
|
|
|
|
|
The Git version corresponding to each release is in _version.h_. It's
|
2019-01-09 23:48:55 +00:00
|
|
|
|
defined as a string. If you need a numeric definition, let us know.
|
|
|
|
|
|
|
|
|
|
If you have a question not addressed here, please contact
|
|
|
|
|
{wireshark-dev-list-email}.
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcDeb]]
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
==== Debian: .deb Packages
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
The Debian Package is built using dpkg-buildpackage, based on information
|
|
|
|
|
found in the source tree under _debian_. See
|
2017-05-29 20:52:02 +00:00
|
|
|
|
http://www.debian-administration.org/articles/336 for a
|
2014-01-24 18:55:27 +00:00
|
|
|
|
more in-depth discussion of the build process.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In the wireshark directory, type:
|
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2015-04-01 14:32:28 +00:00
|
|
|
|
$ dpkg-buildpackage -rfakeroot -us -uc
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
to build the Debian Package.
|
|
|
|
|
|
|
|
|
|
[[ChSrcRpm]]
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
==== Red Hat: .rpm Packages
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
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.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
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:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
* _\_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_.
|
2015-11-11 17:49:17 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
* Whether or not to create the “wireshark-qt” package
|
|
|
|
|
(`-DBUILD_wireshark`).
|
2015-11-11 17:49:17 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
* Lua, c-ares, nghttp2, and other library support (`-DENABLE_...`).
|
2015-11-11 17:49:17 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
* Building with Ninja (`-G Ninja`).
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
In your build directory, type:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2018-03-20 23:15:33 +00:00
|
|
|
|
$ ninja rpm-package
|
|
|
|
|
# ...or, if you're using GNU make...
|
2014-01-24 18:55:27 +00:00
|
|
|
|
$ make rpm-package
|
|
|
|
|
----
|
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
to build the binary and source RPMs. When it is finished there will be a
|
|
|
|
|
message stating where the built RPM can be found.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
.This might take a while
|
|
|
|
|
[TIP]
|
|
|
|
|
====
|
2018-03-20 23:15:33 +00:00
|
|
|
|
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:
|
2015-11-11 17:49:17 +00:00
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
%_smp_mflags -j %(grep -c processor /proc/cpuinfo)
|
|
|
|
|
----
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
|
2018-03-20 23:15:33 +00:00
|
|
|
|
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_.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcOSX]]
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
==== macOS: .dmg Packages
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2017-03-01 21:58:16 +00:00
|
|
|
|
The macOS Package is built using macOS packaging tools, based on information
|
2018-02-04 19:39:56 +00:00
|
|
|
|
found in the source tree under _packaging/macosx_. It must be built using
|
2017-10-04 23:27:08 +00:00
|
|
|
|
CMake. In your build directory, type:
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,sh]
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
2017-10-04 23:27:08 +00:00
|
|
|
|
$ make dmg_package
|
2014-01-24 18:55:27 +00:00
|
|
|
|
----
|
|
|
|
|
|
2017-03-01 21:58:16 +00:00
|
|
|
|
to build the macOS Package.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
|
|
|
|
[[ChSrcNSIS]]
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
==== Windows: NSIS .exe Installer
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2017-01-31 00:30:45 +00:00
|
|
|
|
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
|
2018-02-04 19:39:56 +00:00
|
|
|
|
generation script at _packaging/nsis/wireshark.nsi_.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
When building with CMake you must first build the _nsis_package_prep_ target,
|
|
|
|
|
followed by the _nsis_package_ target, e.g.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,cmd]
|
2015-06-29 17:00:37 +00:00
|
|
|
|
----
|
2015-11-01 21:07:42 +00:00
|
|
|
|
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
|
|
|
|
|
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
|
2015-06-29 17:00:37 +00:00
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
Splitting the packaging projects in this way allows for code signing.
|
|
|
|
|
|
2014-01-24 18:55:27 +00:00
|
|
|
|
[TIP]
|
2014-09-02 19:18:20 +00:00
|
|
|
|
.This might take a while
|
2014-01-24 18:55:27 +00:00
|
|
|
|
====
|
|
|
|
|
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:
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_wireshark-setup-{wireshark-version}.exe_ in
|
2018-03-15 19:13:35 +00:00
|
|
|
|
the _packaging/nsis_ directory in your build directory.
|
2014-01-24 18:55:27 +00:00
|
|
|
|
|
2014-09-02 19:18:20 +00:00
|
|
|
|
[[ChSrcPortableApps]]
|
|
|
|
|
|
2019-01-09 23:48:55 +00:00
|
|
|
|
==== Windows: PortableApps .paf.exe Package
|
2014-09-02 19:18:20 +00:00
|
|
|
|
|
|
|
|
|
_PortableApps.com_ is an environment that lets users run popular applications
|
|
|
|
|
from portable media such as flash drives and cloud drive services.
|
|
|
|
|
|
2018-03-15 19:13:35 +00:00
|
|
|
|
Install the _PortableApps.com Platform_. Install for “all users”, which
|
2015-04-10 15:00:17 +00:00
|
|
|
|
will place it in `C:\PortableApps`. Add the following apps:
|
|
|
|
|
|
|
|
|
|
- NSIS Portable (Unicode)
|
|
|
|
|
- PortableApps.com Installer
|
|
|
|
|
- PortableApps.com Launcher
|
|
|
|
|
- PortableApps.com AppCompactor
|
2014-09-02 19:18:20 +00:00
|
|
|
|
|
2018-02-04 19:39:56 +00:00
|
|
|
|
When building with CMake you must first build the _nsis_package_prep_ target
|
2015-06-29 17:00:37 +00:00
|
|
|
|
(which takes care of general packaging dependencies), followed by the
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_portableapps_package_ target, e.g.
|
2015-06-29 17:00:37 +00:00
|
|
|
|
|
2018-03-16 22:20:18 +00:00
|
|
|
|
[source,cmd]
|
2015-06-29 17:00:37 +00:00
|
|
|
|
----
|
2015-11-01 21:07:42 +00:00
|
|
|
|
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
|
|
|
|
|
> msbuild /m /p:Configuration=RelWithDebInfo portableapps_package.vcxproj
|
2015-06-29 17:00:37 +00:00
|
|
|
|
----
|
|
|
|
|
|
2014-09-02 19:18:20 +00:00
|
|
|
|
[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:
|
2018-02-04 19:39:56 +00:00
|
|
|
|
_WiresharkPortable_{wireshark-version}.paf.exe_ in
|
|
|
|
|
the _packaging/portableapps_ directory.
|
2014-09-02 19:18:20 +00:00
|
|
|
|
|
2018-02-05 16:59:45 +00:00
|
|
|
|
// End of WSDG Chapter Sources
|
2014-02-25 20:22:50 +00:00
|
|
|
|
|
2014-03-16 18:59:17 +00:00
|
|
|
|
// vim: set syntax=asciidoc:
|