Wireshark Wireshark - 2.1 Developer’s Guide
Wireshark Developer’s Guide
For Wireshark 2.1
Ulf Lamping <ulf.lamping[AT]web.de>
Luis E. Ontanon <luis[AT]ontanon.org>
Graham Bloice <graham.bloice[AT]trihedral.com>
Wireshark Developer’s Guide: For Wireshark 2.1
by Ulf Lamping, Luis E. Ontanon, and Graham Bloice
Copyright © 2004-2014 Ulf Lamping, Luis E. Garcia Ontanon, Graham Bloice
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later
version published by the Free Software Foundation.
All logos and trademarks in this document are property of their respective owners.
Preface ............................................................................................................................. ix
1. Foreword ............................................................................................................... ix
2. Who should read this document? ............................................................................... ix
3. Acknowledgements ................................................................................................. ix
4. About this document ............................................................................................... ix
5. Where to get the latest copy of this document? ............................................................. x
6. Providing feedback about this document ...................................................................... x
I. Wireshark Build Environment ............................................................................................ 1
1. Introduction ............................................................................................................ 2
1.1. Introduction .................................................................................................. 2
1.2. What is Wireshark? ....................................................................................... 2
1.3. Supported Platforms ...................................................................................... 2
1.3.1. Unix ................................................................................................. 2
1.3.2. Linux ................................................................................................ 2
1.3.3. Microsoft Windows ............................................................................ 3
1.4. Development and maintenance of Wireshark ...................................................... 3
1.4.1. Programming languages used ................................................................ 3
1.4.2. Open Source Software ......................................................................... 4
1.5. Releases and distributions ............................................................................... 4
1.5.1. Binary distributions ............................................................................. 4
1.5.2. Source code distributions ..................................................................... 5
1.6. Automated Builds (Buildbot) .......................................................................... 5
1.6.1. Advantages ........................................................................................ 5
1.6.2. What does the Buildbot do? ................................................................. 6
1.7. Reporting problems and getting help ................................................................ 6
1.7.1. Website ............................................................................................. 6
1.7.2. Wiki ................................................................................................. 6
1.7.3. FAQ ................................................................................................. 7
1.7.4. Other sources ..................................................................................... 7
1.7.5. Mailing Lists ..................................................................................... 7
1.7.6. Bug database (Bugzilla) ....................................................................... 8
1.7.7. Q&A Site .......................................................................................... 8
1.7.8. Reporting Problems ............................................................................ 8
1.7.9. Reporting Crashes on UNIX/Linux platforms ........................................... 9
1.7.10. Reporting Crashes on Windows platforms ............................................. 9
2. Quick Setup .......................................................................................................... 10
2.1. UNIX: Installation ....................................................................................... 10
2.2. Win32/64: Step-by-Step Guide ...................................................................... 10
2.2.1. Install PowerShell ............................................................................. 10
2.2.2. Optional: Install Chocolatey ................................................................ 10
2.2.3. Install Microsoft C compiler and SDK .................................................. 10
2.2.4. Install Qt ......................................................................................... 11
2.2.5. Install Cygwin .................................................................................. 12
2.2.6. Install Python ................................................................................... 12
2.2.7. Install Git ........................................................................................ 13
2.3. Install CMake ............................................................................................. 13
2.3.1. Install and Prepare Sources ................................................................. 14
2.3.2. Open a Visual Studio Command Prompt ............................................... 14
2.3.3. Generate the build files ...................................................................... 15
2.3.4. Build Wireshark ............................................................................... 16
2.3.5. Debug Environment Setup .................................................................. 16
2.3.6. Optional: Create User’s and Developer’s Guide ...................................... 16
2.3.7. Optional: Create a Wireshark Installer .................................................. 16
3. Work with the Wireshark sources ............................................................................. 18
iii
Wireshark Developer’s Guide
3.1. Introduction ................................................................................................ 18
3.2. The Wireshark Git repository ........................................................................ 18
3.2.1. The web interface to the Git repository ................................................. 18
3.3. Obtain the Wireshark sources ........................................................................ 19
3.3.1. Git over SSH or HTTPS .................................................................... 19
3.3.2. Git web interface .............................................................................. 20
3.3.3. Buildbot Snapshots ............................................................................ 21
3.3.4. Released sources ............................................................................... 21
3.4. Update the Wireshark sources ........................................................................ 21
3.4.1. Update Using Git .............................................................................. 21
3.4.2. Update Using Source Archives ............................................................ 22
3.5. Build Wireshark .......................................................................................... 22
3.5.1. Building on Unix .............................................................................. 22
3.5.2. Win32 native ................................................................................... 23
3.6. Run generated Wireshark .............................................................................. 23
3.6.1. Unix/Linux ...................................................................................... 23
3.6.2. Win32 native ................................................................................... 23
3.7. Debug your generated Wireshark ................................................................... 23
3.7.1. Unix/Linux ...................................................................................... 23
3.7.2. Win32 native ................................................................................... 24
3.8. Make changes to the Wireshark sources .......................................................... 24
3.9. Contribute your changes ............................................................................... 24
3.9.1. Some tips for a good patch ................................................................. 25
3.9.2. Code Requirements ........................................................................... 25
3.9.3. Uploading your changes ..................................................................... 26
3.9.4. Backporting a change ........................................................................ 26
3.10. Apply a patch from someone else ................................................................. 27
3.10.1. Using patch .................................................................................... 27
3.11. Binary packaging ....................................................................................... 28
3.11.1. Debian: .deb packages ...................................................................... 28
3.11.2. Red Hat: .rpm packages .................................................................... 28
3.11.3. OS X: .dmg packages ....................................................................... 29
3.11.4. Win32: NSIS .exe installer ................................................................ 29
3.11.5. Win32: PortableApps .paf.exe package ................................................ 29
4. Tool Reference ...................................................................................................... 31
4.1. Introduction ................................................................................................ 31
4.2. Windows PowerShell ................................................................................... 31
4.3. Chocolatey ................................................................................................. 31
4.4. Windows: Cygwin ....................................................................................... 32
4.4.1. Installing Cygwin using the Cygwin installer ......................................... 32
4.4.2. Add/Update/Remove Cygwin Packages ................................................. 32
4.4.3. Installing Cygwin using Chocolatey ..................................................... 33
4.5. GNU compiler toolchain (UNIX only) ............................................................ 33
4.5.1. gcc (GNU compiler collection) ............................................................ 33
4.5.2. gdb (GNU project debugger) ............................................................... 33
4.5.3. ddd (GNU Data Display Debugger) ...................................................... 34
4.5.4. make (GNU Make) ........................................................................... 34
4.6. Microsoft compiler toolchain (Windows native) ................................................ 34
4.6.1. Toolchain Package Alternatives ........................................................... 35
4.6.2. cl.exe (C Compiler) ........................................................................... 36
4.6.3. link.exe (Linker) ............................................................................... 36
4.6.4. C-Runtime "Redistributable" Files ....................................................... 36
4.6.5. Windows (Platform) SDK .................................................................. 37
4.6.6. HTML Help ..................................................................................... 38
iv
Wireshark Developer’s Guide
4.6.7. Debugger ......................................................................................... 38
4.7. bash .......................................................................................................... 39
4.7.1. UNIX and Cygwin: GNU bash ............................................................ 39
4.7.2. Windows native: ............................................................................... 39
4.8. Python ....................................................................................................... 39
4.9. Perl ........................................................................................................... 40
4.9.1. UNIX and Cygwin: Perl ..................................................................... 40
4.10. sed .......................................................................................................... 40
4.10.1. UNIX and Cygwin: sed .................................................................... 40
4.10.2. Windows native: sed ........................................................................ 41
4.11. Bison ....................................................................................................... 41
4.11.1. UNIX or Cygwin: bison ................................................................... 41
4.11.2. Windows Native: Win flex-bison and bison .......................................... 41
4.12. Flex ......................................................................................................... 42
4.12.1. UNIX or Cygwin: flex ..................................................................... 42
4.12.2. Windows Native: Win flex-bison and flex ............................................ 42
4.13. Git client .................................................................................................. 42
4.13.1. UNIX or Cygwin: git ....................................................................... 42
4.13.2. Windows native: git ......................................................................... 43
4.14. Git Powershell Extensions (optional) ............................................................. 43
4.15. Git GUI client (optional) ............................................................................. 43
4.16. patch (optional) ......................................................................................... 43
4.16.1. UNIX and Cygwin: patch ................................................................. 43
4.16.2. Windows native: patch ..................................................................... 44
4.17. Windows: NSIS (optional) .......................................................................... 44
4.18. Windows: PortableApps (optional) ................................................................ 44
5. Library Reference .................................................................................................. 45
5.1. Introduction ................................................................................................ 45
5.2. Binary library formats .................................................................................. 45
5.2.1. Unix ............................................................................................... 45
5.2.2. Win32: MSVC ................................................................................. 45
5.2.3. Win32: cygwin gcc ........................................................................... 45
5.3. Win32: Automated library download .............................................................. 45
5.4. Qt ............................................................................................................. 46
5.4.1. Unix ............................................................................................... 46
5.4.2. Win32 MSVC .................................................................................. 46
5.5. GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv ...................... 46
5.5.1. Unix ............................................................................................... 46
5.5.2. Win32 MSVC .................................................................................. 46
5.6. SMI (optional) ............................................................................................ 46
5.6.1. Unix ............................................................................................... 47
5.6.2. Win32 MSVC .................................................................................. 47
5.7. c-ares (optional) .......................................................................................... 47
5.7.1. Unix ............................................................................................... 47
5.7.2. Win32 MSVC .................................................................................. 47
5.8. zlib (optional) ............................................................................................. 47
5.8.1. Unix ............................................................................................... 47
5.8.2. Win32 MSVC .................................................................................. 47
5.9. libpcap/WinPcap (optional) ........................................................................... 47
5.9.1. Unix: libpcap ................................................................................... 47
5.9.2. Win32 MSVC: WinPcap .................................................................... 48
5.10. GnuTLS (optional) ..................................................................................... 48
5.10.1. Unix ............................................................................................. 48
5.10.2. Win32 MSVC ................................................................................. 48
v
Wireshark Developer’s Guide
5.11. Gcrypt (optional) ....................................................................................... 48
5.11.1. Unix ............................................................................................. 48
5.11.2. Win32 MSVC ................................................................................. 48
5.12. Kerberos (optional) .................................................................................... 48
5.12.1. Unix ............................................................................................. 48
5.12.2. Win32 MSVC ................................................................................. 48
5.13. LUA (optional) .......................................................................................... 48
5.13.1. Unix ............................................................................................. 49
5.13.2. Win32 MSVC ................................................................................. 49
5.14. PortAudio (optional) ................................................................................... 49
5.14.1. Unix ............................................................................................. 49
5.14.2. Win32 MSVC ................................................................................. 49
5.15. GeoIP (optional) ........................................................................................ 49
5.15.1. Unix ............................................................................................. 49
5.15.2. Win32 MSVC ................................................................................. 49
5.16. WinSparkle (optional) ................................................................................. 49
5.16.1. Win32 MSVC ................................................................................. 49
II. Wireshark Development ................................................................................................. 50
6. How Wireshark Works ........................................................................................... 51
6.1. Introduction ................................................................................................ 51
6.2. Overview ................................................................................................... 51
6.3. Capturing packets ........................................................................................ 52
6.4. Capture Files .............................................................................................. 52
6.5. Dissect packets ........................................................................................... 52
7. Introduction .......................................................................................................... 53
7.1. Source overview .......................................................................................... 53
7.2. Coding Style .............................................................................................. 53
7.3. The GLib library ......................................................................................... 53
8. Packet capturing .................................................................................................... 54
8.1. How to add a new capture type to libpcap ....................................................... 54
9. Packet dissection ................................................................................................... 55
9.1. How it works .............................................................................................. 55
9.2. Adding a basic dissector ............................................................................... 55
9.2.1. Setting up the dissector ...................................................................... 55
9.2.2. Dissecting the details of the protocol .................................................... 57
9.2.3. Improving the dissection information .................................................... 60
9.3. How to handle transformed data ..................................................................... 62
9.4. How to reassemble split packets ..................................................................... 63
9.4.1. How to reassemble split UDP packets ................................................... 64
9.4.2. How to reassemble split TCP Packets ................................................... 67
9.5. How to tap protocols ................................................................................... 68
9.6. How to produce protocol stats ....................................................................... 69
9.7. How to use conversations ............................................................................. 70
9.8. idl2wrs: Creating dissectors from CORBA IDL files .......................................... 70
9.8.1. What is it? ....................................................................................... 71
9.8.2. Why do this? ................................................................................... 71
9.8.3. How to use idl2wrs ........................................................................... 71
9.8.4. TODO ............................................................................................. 72
9.8.5. Limitations ...................................................................................... 73
9.8.6. Notes .............................................................................................. 73
10. Lua Support in Wireshark ...................................................................................... 74
10.1. Introduction .............................................................................................. 74
10.2. Example of Dissector written in Lua ............................................................. 74
10.3. Example of Listener written in Lua ............................................................... 75
vi
Wireshark Developer’s Guide
11. Wireshark’s Lua API Reference Manual ................................................................... 77
11.1. Saving capture files .................................................................................... 77
11.1.1. Dumper ......................................................................................... 77
11.1.2. PseudoHeader ................................................................................. 78
11.2. Obtaining dissection data ............................................................................ 79
11.2.1. Field ............................................................................................. 79
11.2.2. FieldInfo ........................................................................................ 81
11.2.3. Global Functions ............................................................................. 84
11.3. GUI support .............................................................................................. 84
11.3.1. ProgDlg ......................................................................................... 84
11.3.2. TextWindow ................................................................................... 85
11.3.3. Global Functions ............................................................................. 88
11.4. Post-dissection packet analysis ..................................................................... 90
11.4.1. Listener ......................................................................................... 90
11.5. Obtaining packet information ....................................................................... 92
11.5.1. Address ......................................................................................... 92
11.5.2. Column ......................................................................................... 92
11.5.3. Columns ........................................................................................ 93
11.5.4. NSTime ......................................................................................... 94
11.5.5. Pinfo ............................................................................................. 95
11.5.6. PrivateTable ................................................................................... 99
11.6. Functions for new protocols and dissectors ..................................................... 99
11.6.1. Dissector ........................................................................................ 99
11.6.2. DissectorTable .............................................................................. 101
11.6.3. Pref ............................................................................................. 104
11.6.4. Prefs ............................................................................................ 105
11.6.5. Proto ........................................................................................... 106
11.6.6. ProtoExpert .................................................................................. 108
11.6.7. ProtoField .................................................................................... 109
11.6.8. Global Functions ........................................................................... 119
11.7. Adding information to the dissection tree ..................................................... 120
11.7.1. TreeItem ...................................................................................... 120
11.8. Functions for handling packet data .............................................................. 126
11.8.1. ByteArray .................................................................................... 126
11.8.2. Tvb ............................................................................................. 130
11.8.3. TvbRange ..................................................................................... 132
11.9. Custom file format reading/writing .............................................................. 138
11.9.1. CaptureInfo .................................................................................. 138
11.9.2. CaptureInfoConst ........................................................................... 140
11.9.3. File ............................................................................................. 142
11.9.4. FileHandler ................................................................................... 143
11.9.5. FrameInfo .................................................................................... 147
11.9.6. FrameInfoConst ............................................................................. 149
11.9.7. Global Functions ........................................................................... 151
11.10. Directory handling functions .................................................................... 151
11.10.1. Dir ............................................................................................ 151
11.11. Utility Functions .................................................................................... 154
11.11.1. Global Functions .......................................................................... 154
11.12. Handling 64-bit Integers .......................................................................... 157
11.12.1. Int64 .......................................................................................... 157
11.12.2. UInt64 ....................................................................................... 163
11.13. Binary encode/decode support .................................................................. 169
11.13.1. Struct ......................................................................................... 171
11.14. GLib Regular Expressions ........................................................................ 173
vii
Wireshark Developer’s Guide
11.14.1. GRegex ...................................................................................... 173
12. User Interface .................................................................................................... 181
12.1. Introduction ............................................................................................. 181
12.2. The Qt Application Framework .................................................................. 181
12.2.1. Source Code Overview ................................................................... 181
12.2.2. Coding Practices and Naming Conventions ......................................... 182
12.2.3. Other Issues .................................................................................. 183
12.3. The GTK library ...................................................................................... 183
12.3.1. GTK Version 2.x ........................................................................... 183
12.3.2. GTK Version 3.x ........................................................................... 184
12.3.3. Compatibility GTK versions ............................................................ 184
12.3.4. GTK resources on the web .............................................................. 184
12.4. GUI Reference documents ......................................................................... 184
12.5. Adding/Extending Dialogs ......................................................................... 185
12.6. Widget naming ........................................................................................ 185
12.7. Common GTK programming pitfalls ........................................................... 185
12.7.1. Usage of gtk_widget_show() / gtk_widget_show_all() .......................... 185
13. This Document’s License (GPL) ........................................................................... 186
viii
Preface
1. Foreword
This book tries to give you a guide to start your own experiments into the wonderful world of Wireshark
development.
Developers who are new to Wireshark often have a hard time getting their development environment up
and running. This is especially true for Win32 developers, as a lot of the tools and methods used when
building Wireshark are much more common in the UNIX world than on Win32.
The first part of this book will describe how to set up the environment needed to develop Wireshark.
The second part of this book will describe how to change the Wireshark source code.
We hope that you find this book useful, and look forward to your comments.
2. Who should read this document?
The intended audience of this book is anyone going into the development of Wireshark.
This book is not intended to explain the usage of Wireshark in general. Please refer the Wireshark User’s
Guide about Wireshark usage.
By reading this book, you will learn how to develop Wireshark. It will hopefully guide you around
some common problems that frequently appear for new (and sometimes even advanced) developers of
Wireshark.
3. Acknowledgements
The authors would like to thank the whole Wireshark team for their assistance. In particular, the authors
would like to thank:
• Gerald Combs, for initiating the Wireshark project.
• Guy Harris, for many helpful hints and his effort in maintaining the various contributions on the mailing
lists.
• Frank Singleton from whose README.idl2wrs Section 9.8, “idl2wrs: Creating dissectors from
CORBA IDL files” is derived.
The authors would also like to thank the following people for their helpful feedback on this document:
• XXX - Please give feedback :-)
And of course a big thank you to the many, many contributors of the Wireshark development community!
4. About this document
This book was developed by Ulf Lamping and updated for VS2013 by Graham Bloice
It is written in AsciiDoc.
ix
Preface
You will find some specially marked parts in this book:
This is a warning
You should pay attention to a warning, as otherwise data loss might occur.
This is a note
A note will point you to common mistakes and things that might not be obvious.
This is a tip
Tips will be helpful for your everyday work developing Wireshark.
5. Where to get the latest copy of this document?
The latest copy of this documentation can always be found at: https://www.wireshark.org/docs/ in A4 PDF,
US letter PDF, single HTML, and chunked HTML.
6. Providing feedback about this document
Should you have any feedback about this document, please send it to the authors through wireshark-
dev[AT]wireshark.org.
x
Part I. Wireshark Build Environment
Wireshark Build Environment
The first part describes how to set up the tools, libraries and source needed to generate Wireshark and how to do some
typical development tasks.
Chapter 1. Introduction
1.1. Introduction
This chapter will provide you with information about Wireshark development in general.
1.2. What is Wireshark?
Well, if you want to start Wireshark development, you might already know what Wireshark is doing. If not,
please have a look at the Wireshark User’s Guide, which will provide a lot of general information about it.
1.3. Supported Platforms
Wireshark currently runs on most UNIX platforms and various Windows platforms. It requires Qt, GLib,
libpcap and some other libraries in order to run.
As Wireshark is developed in a platform independent way and uses libraries (such as the Qt GUI library)
which are available for many different platforms, it’s thus available on a wide variety of platforms.
If a binary package is not available for your platform, you should download the source and try to build it.
Please report your experiences to wireshark-dev[AT]wireshark.org.
Binary packages are available for the following platforms along with many others:
1.3.1. Unix
• Apple OS X
• FreeBSD
• HP-UX
• IBM AIX
• NetBSD
• OpenBSD
• Oracle Solaris
1.3.2. Linux
• Debian GNU/Linux
• Ubuntu
• Gentoo Linux
• IBM S/390 Linux (Red Hat)
• Mandrake Linux
• PLD Linux
2
• Red Hat Linux
• Rock Linux
• Slackware Linux
• Suse Linux
1.3.3. Microsoft Windows
Wireshark supports Windows natively via the Windows API. Note that in this documentation and
elsewhere we tend to use the terms “Win32”, “Win”, and “Windows” interchangeably to refer to the
Windows API. Wireshark runs on and can be compiled on the following platforms:
• Windows 10 / Windows Server 2016
• Windows 8.1 / Windows Server 2012 R2
• Windows 8 / Windows Server 2012
• Windows 7 / Windows Server 2008 R2
Introduction
• Windows Vista / Windows Server 2008
Development on Windows XP, Server 2003, and older versions may be possible but is not supported.
1.4. Development and maintenance of Wireshark
Wireshark was initially developed by Gerald Combs. Ongoing development and maintenance of Wireshark
is handled by the Wireshark core developers, a loose group of individuals who fix bugs and provide new
functionality.
There have also been a large number of people who have contributed protocol dissectors and other
improvements to Wireshark, and it is expected that this will continue. You can find a list of the people
who have contributed code to Wireshark by checking the About dialog box of Wireshark, or have a look
at the https://www.wireshark.org/about.html#authors page on the Wireshark web site.
The communication between the developers is usually done through the developer mailing list, which can
be joined by anyone interested in the development activities. At the time this document was written, more
than 500 persons were subscribed to this mailing list!
It is strongly recommended to join the developer mailing list, if you are going to do any Wireshark
development. See Section 1.7.5, “Mailing Lists” about the different Wireshark mailing lists available.
1.4.1. Programming languages used
Most of Wireshark is implemented in plain ANSI C. A notable exception is the code in ui/qt, which is
written in C++.
The typical task for a new Wireshark developer is to extend an existing, or write a new dissector for a
specific network protocol. As (almost) any dissector is written in plain old ANSI C, a good knowledge
about ANSI C will be sufficient for Wireshark development in almost any case.
3
Introduction
So unless you are going to change the build process of Wireshark itself, you won’t come in touch with any
other programming language than ANSI C (such as Perl or Python, which are used only in the Wireshark
build process).
Beside the usual tools for developing a program in C (compiler, make, …), the build process uses some
additional helper tools (Perl, Python, Sed, …), which are needed for the build process when Wireshark is to
be build and installed from the released source packages. If Wireshark is installed from a binary package,
none of these helper tools are needed on the target system.
1.4.2. Open Source Software
Wireshark is an open source software (OSS) project, and is released under the GNU General Public License
(GPL). You can freely use Wireshark on any number of computers you like, without worrying about license
keys or fees or such. In addition, all source code is freely available under the GPL. Because of that, it is
very easy for people to add new protocols to Wireshark, either as plugins, or built into the source, and
they often do!
You are welcome to modify Wireshark to suit your own needs, and it would be appreciated if you contribute
your improvements back to the Wireshark community.
You gain three benefits by contributing your improvements back to the community:
• 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 and other people.
• The developers of Wireshark might improve your changes even more, as there’s always room for
improvement. Or they may implement some advanced things on top of your code, which can be useful
for yourself too.
• The maintainers and developers of Wireshark will maintain your code as well, fixing it when API
changes or other changes are made, and generally keeping it in tune with what is happening with
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.
The Wireshark source code and binary packages for some platforms are all available on the download page
of the Wireshark website: https://www.wireshark.org/download.html.
1.5. Releases and distributions
The officially released files can be found at: https://www.wireshark.org/download.html. A new Wireshark
version is released after significant changes compared to the last release are completed or a serious security
issue is encountered. The typical release schedule is about every 4-8 weeks (although this may vary). There
are two kinds of distributions: binary and source; both have their advantages and disadvantages.
1.5.1. Binary distributions
Binary distributions are usually easy to install (as simply starting the appropriate file is usually the only
thing to do). They are available for the following systems:
• Windows (.exe file). The typical Windows end user is used to getting a setup.exe file which will install
all the required things for him.
• Win32 PAF (.paf.exe file). Another Windows end user method is to get a portable application file which
will install all the required things for him.
4
Introduction
• Debian (.deb file). A user of a Debian Package Manager (DPKG) based system obtains a .deb file from
which the package manager checks the dependencies and installs the software.
• Red Hat (.rpm file). A user of a RPM Package Manager (RPM) based system obtains an .rpm file from
which the package manager checks the dependencies and installs the software.
• OS X (.dmg file). The typical OS X end user is used to getting a .dmg file which will install all the
required things for him.
• Solaris. A Solaris user obtains a file from which the package manager (PKG) checks the dependencies
and installs the software.
However, if you want to start developing with Wireshark, the binary distributions won’t be too helpful,
as you need the source files, of course.
For details about how to build these binary distributions yourself, e.g. if you need a distribution for a
special audience, see Section 3.11, “Binary packaging”.
1.5.2. Source code distributions
It’s still common for UNIX developers to give the end user a source tarball and let the user compile it on
their target machine (configure, make, make install). However, for different UNIX (Linux) distributions
it’s becoming more common to release binary packages (e.g. .deb or .rpm files) these days.
You should use the released sources if you want to build Wireshark from source on your platform for
productive use. However, if you going to develop changes to the Wireshark sources, it might be better
to use the latest GIT sources. For details about the different ways to get the Wireshark source code see
Section 3.3, “Obtain the Wireshark sources”.
Before building Wireshark from a source distribution, make sure you have all the tools and libraries
required to build. The following chapters will describe the required tools and libraries in detail.
1.6. Automated Builds (Buildbot)
The Wireshark Buildbot automatically rebuilds Wireshark on every change of the source code repository
and indicates problematic changes. This frees the developers from repeating (and annoying) work, so time
can be spent on more interesting tasks.
1.6.1. Advantages
• Recognizing (cross platform) build problems - early. Compilation problems can be narrowed down to
a few commits, making a fix much easier.
• "Health status" overview of the sources. A quick look at: https://buildbot.wireshark.org/wireshark-
master/ gives a good "feeling" if the sources are currently "well". On the other hand, if all is "red", an
update of a personal source tree might better be done later …
• "Up to date" binary packages are available. After a change was committed to the repository, a binary
package / installer is usually available within a few hours at: https://www.wireshark.org/download/
automated/. This can be quite helpful, e.g. a bug reporter can easily verify a bugfix by installing a recent
build.
• Automated regression tests. In particular, the fuzz tests often indicate "real life" problems that are
otherwise hard to find.
5
Introduction
1.6.2. What does the Buildbot do?
The Buildbot will do the following (to a different degree on the different platforms):
• Check out from the source repository
• Build
• Create binary packages and installers
• Create source packages and run distribution checks
• Run regression tests
Each step is represented at the status page by a rectangle, green if it succeeded or red if it failed. Most
steps provide a link to the corresponding console logfile, to get additional information.
The Buildbot runs on a platform collection that represents the different "platform specialties" quite well:
• Windows 8.1 x86 (Win32, little endian, Visual Studio 2013)
• Windows 7 x86-64 (Win64, little endian, Visual Studio 2013)
• Ubuntu x86-64 (Linux, little endian, gcc, Clang)
• Solaris SPARC (Solaris, big endian, gcc)
• OS X x86 (BSD, little endian, Clang)
• OS X x86-64 (BSD, little endian, Clang)
and two buildslaves that run static code analysis to help spot coding issues:
• Visual Studio Code Analysis (Win64, little endian, VS 2013)
• Clang Code Analysis (Linux, little endian, Clang)
Each platform is represented at the status page by a single column, the most recent entries are at the top.
1.7. Reporting problems and getting help
If you have problems, or need help with Wireshark, there are several places that may be of interest to you
(well, beside this guide of course).
1.7.1. Website
You will find lots of useful information on the Wireshark homepage at https://www.wireshark.org/.
1.7.2. Wiki
The Wireshark Wiki at https://wiki.wireshark.org/ provides a wide range of information related to
Wireshark and packet capturing in general. You will find a lot of information not part of this developer’s
guide. For example, there is an explanation how to capture on a switched network, an ongoing effort to
build a protocol reference and a lot more.
6
And best of all, if you would like to contribute your knowledge on a specific topic (maybe a network
protocol you know well), you can edit the Wiki pages by simply using your webbrowser.
1.7.3. FAQ
The "Frequently Asked Questions" will list often asked questions and the corresponding answers.
Before sending any mail to the mailing lists below, be sure to read the FAQ, as it will often answer any
questions you might have. This will save yourself and others a lot of time. Keep in mind that a lot of people
are subscribed to the mailing lists.
You will find the FAQ inside Wireshark by clicking the menu item Help/Contents and selecting the FAQ
page in the upcoming dialog.
An online version is available at the Wireshark website: https://www.wireshark.org/faq.html. You might
prefer this online version as it’s typically more up to date and the HTML format is easier to use.
1.7.4. Other sources
If you don’t find the information you need inside this book, there are various other sources of information:
• The file doc/README.developer and all the other README.xxx files in the source code. These are
various documentation files on different topics
Introduction
Read the README
README.developer is packed full with all kinds of details relevant to the developer of
Wireshark source code. Its companion file README.dissector advises you around common
pitfalls, shows you basic layout of dissector code, shows details of the APIs available to the
dissector developer, etc.
• The Wireshark source code
• Tool documentation of the various tools used (e.g. manpages of sed, gcc, etc.)
• The different mailing lists. See Section 1.7.5, “Mailing Lists”
1.7.5. Mailing Lists
There are several mailing lists available on specific Wireshark topics:
wireshark-announce This mailing list will inform you about new program releases, which
wireshark-users This list is for users of Wireshark. People post questions about building
wireshark-dev This list is for Wireshark developers. People post questions about the
usually appear about every 4-8 weeks.
and using Wireshark, others (hopefully) provide answers.
development of Wireshark, others (hopefully) provide answers. If you
want to start developing a protocol dissector, join this list.
wireshark-bugs This list is for Wireshark developers. Every time a change to the bug
database occurs, a mail to this mailing list is generated. If you want to be
notified about all the changes to the bug database, join this list. Details
about the bug database can be found in Section 1.7.6, “Bug database
(Bugzilla)”.
7
Introduction
wireshark-commits This list is for Wireshark developers. Every time a change to the GIT
repository is checked in, a mail to this mailing list is generated. If you
want to be notified about all the changes to the GIT repository, join this
list. Details about the GIT repository can be found in Section 3.2, “The
Wireshark Git repository”.
You can subscribe to each of these lists from the Wireshark web site: https://www.wireshark.org/lists/.
From there, you can choose which mailing list you want to subscribe to by clicking on the Subscribe/
Unsubscribe/Options button under the title of the relevant list. The links to the archives are included on
that page as well.
The archives are searchable
You can search in the list archives to see if someone previously asked the same question
and maybe already got an answer. That way you don’t have to wait until someone answers
your question.
1.7.6. Bug database (Bugzilla)
The Wireshark community collects bug reports in a Bugzilla database at https://bugs.wireshark.org/. This
database is filled with manually filed bug reports, usually after some discussion on wireshark-dev, and
automatic bug reports from the Buildbot tools.
1.7.7. Q&A Site
The Wireshark Q and A site at https://ask.wireshark.org/ offers a resource where questions and answers
come together. You have the option to search what questions were asked before and what answers were
given by people who knew about the issue. Answers are graded, so you can pick out the best ones easily.
If your issue isn’t discussed before you can post one yourself.
1.7.8. Reporting Problems
Test with the latest version
Before reporting any problems, please make sure you have installed the latest version of
Wireshark. Reports on older maintenance releases are usually met with an upgrade request.
If you report problems, provide as much information as possible. In general, just think about what you
would need to find that problem, if someone else sends you such a problem report. Also keep in mind that
people compile/run Wireshark on a lot of different platforms.
When reporting problems with Wireshark, it is helpful if you supply the following information:
1. The version number of Wireshark and the dependent libraries linked with it, e.g. Qt, GTK+, etc. You
can obtain this with the command wireshark -v.
2. Information about the platform you run Wireshark on.
3. A detailed description of your problem.
4. If you get an error/warning message, copy the text of that message (and also a few lines before and
after it, if there are some), so others may find the build step where things go wrong. Please don’t give
something like: "I get a warning when compiling x" as this won’t give any direction to look at.
8
Introduction
Don’t send large files
Do not send large files (>100KB) to the mailing lists, just place a note that further data
is available on request. Large files will only annoy a lot of people on the list who are not
interested in your specific problem. If required, you will be asked for further data by the
persons who really can help you.
Don’t send confidential information
If you send captured data to the mailing lists, or add it to your bug report, be sure it doesn’t
contain any sensitive or confidential information, such as passwords. Visibility of such files
can be limited to certain groups in the Bugzilla database though.
1.7.9. Reporting Crashes on UNIX/Linux platforms
When reporting crashes with Wireshark, it is helpful if you supply the traceback information (besides the
information mentioned in Section 1.7.8, “Reporting Problems”).
You can obtain this traceback information with the following commands:
$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
backtrace
^D
$
Using GDB
Type the characters in the first line verbatim. Those are back-tics there.
backtrace is a gdb command. You should enter it verbatim after the first line shown
above, but it will not be echoed. The ^D (Control-D, that is, press the Control key and the D
key together) will cause gdb to exit. This will leave you with a file called bt.txt in the current
directory. Include the file with your bug report.
If you do not have gdb available, you will have to check out your operating system’s
debugger.
You should mail the traceback to the wireshark-dev mailing list, or attach it to your bug report.
1.7.10. Reporting Crashes on Windows platforms
You can download Windows debugging symbol files (.pdb) from the following locations:
• 32-bit Windows: https://www.wireshark.org/download/win32/all-versions/
• 64-bit Windows: https://www.wireshark.org/download/win64/all-versions/
Files are named "Wireshark-pdb-winbits-x.y.z.zip" to match their corresponding "Wireshark-winbitsx.y.z.exe" installer packages.
9
Chapter 2. Quick Setup
2.1. UNIX: Installation
All the tools required are usually installed on a UNIX developer machine.
If a tool is not already installed on your system, you can usually install it using the package in your
distribution: aptitude, yum, Synaptic, etc.
If an install package is not available or you have a reason not to use it (maybe because it’s simply too
old), you can install that tool from source code. The following sections will provide you with the webpage
addresses where you can get these sources.
2.2. Win32/64: Step-by-Step Guide
A quick setup guide for Win32 and Win64 with recommended configuration.
Warning
Unless you know exactly what you are doing, you should strictly follow the recommendations
below. They are known to work and if the build breaks, please re-read this guide carefully.
Known traps are:
1. Not using the correct (x86 or x64) version of the Visual Studio command prompt.
2. Not copying/downloading the correct version of vcredist_xYY.exe.
2.2.1. Install PowerShell
PowerShell 2.0 or later is required for building Wireshark and the NSIS package. Windows 7 and later
include compatible versions. It is also required by Chocolatey.
If you are running Windows Vista and have thus far managed to not install PowerShell 2.0, either directly
or via anything that requires it, you must now install PowerShell 2.0. You can download it from https://
www.microsoft.com/powershell
2.2.2. Optional: Install Chocolatey
Chocolatey is a native package manager for Windows. There are packages for most of the software listed
below. Along with traditional Windows packages it supports Cygwin and the Python Package Index.
2.2.3. Install Microsoft C compiler and SDK
You need to install, in exactly this order:
1. C compiler: Download and install "Microsoft Visual Studio 2013 Community Edition." This is a small
download that then downloads all the other required parts (which are quite large).
Uncheck all the optional components (unless you want to use them for purposes other than Wireshark).
10
Quick Setup
You can use Chocolatey to install Visual Studio:
PS$>choco install VisualStudioCommunity2013
You can use other Microsoft C compiler variants, but VS2013 is used to build the development releases
and is the preferred option. It’s possible to compile Wireshark with a wide range of Microsoft C compiler
variants. For details see Section 4.6, “Microsoft compiler toolchain (Windows native)”.
You may have to do this as Administrator.
Compiling with gcc or Clang is not recommended and will certainly not work (at least not without a lot of
advanced tweaking). For further details on this topic, see Section 4.5, “GNU compiler toolchain (UNIX
only)”. This may change in future as releases of Visual Studio add more cross-platform support.
Why is this recommended? While this is a huge download, Visual Studio 2013 Community Edition is the
only free (as in beer) versions that includes the Visual Studio integrated debugger. Visual Studio 2013 is
also used to create official Wireshark builds, so it will likely have fewer development-related problems.
For VS2010 You will need some extra items:
1. Windows SDK for Windows 7, if you want to build 64-bit binaries for Windows 7: Download and
install "Microsoft Windows SDK for Windows 7."
In case the install of the SDK fails go to software management and remove the VC++ 2010 runtime
and redist packages (don’t worry, they will be added back via the service pack later). If installation of
the SDK still fails, there may be a permission problem. See here for a solution.
2. C compiler service pack: Download and install "Microsoft Visual Studio 2010 Service Pack 1." This
is a very large download.
3. Microsoft Visual C++ 2010 Service Pack 1 Compiler Update for the Windows SDK 7.1, if you want to
build 64-bit binaries for Windows 7: Download and install "Microsoft Visual C++ 2010 Service Pack
1 Compiler Update for the Windows SDK 7.1."
4. If you will be building 64-bit binaries those items must be installed in that order as installing the
Microsoft Visual Studio 2010 Service Pack 1 can, if you’ve installed the Microsoft Windows SDK
for Windows 7, remove the 64-bit compilers, as per http://support.microsoft.com/?kbid=2519277 the
Microsoft Knowledge Base article "FIX: Visual C++ compilers are removed when you upgrade Visual
Studio 2010 Professional or Visual Studio 2010 Express to Visual Studio 2010 SP1 if Windows SDK
v7.1 is installed". The release notes for the Microsoft Visual C++ 2010 Service Pack 1 Compiler Update
for the Windows SDK 7.1 say that, to ensure that your system has a supported configuration, you
must install the items in the order specified above. If you have Microsoft Update installed, so that the
Windows update process will update software other than components of Windows, and thus will update
Visual Studio, you may need to disable it until after all of the above are installed, to make sure it doesn’t
install Visual Studio 2010 SP1 out of order.
2.2.4. Install Qt
The main Wireshark application uses the Qt windowing toolkit. To install Qt download the Online
Installer from the Qt Project download page and select a component that matches your target system and
compiler. For example, the “msvc2013 64-bit OpenGL” component is used to build the official 64-bit
packages.
Note that separate installations (into different directories) of Qt are required for 32 bit and 64 bit builds.
The environment variable QT5_BASE_DIR should be set as appropriate for your environment and should
point to the Qt directory that contains the bin directory, e.g. C:\Qt\Qt5.5.0\5.5\msvc2013
11
2.2.5. Install Cygwin
On 32-bit Windows, download the 32-bit Cygwin installer and start it. On 64-bit Windows, download the
64-bit Cygwin installer and start it.
At the "Select Packages" page, you’ll need to select some additional packages which are not installed by
default. Navigate to the required Category/Package row and, if the package has a "Skip" item in the "New"
column, click on the "Skip" item so it shows a version number for:
• Archive/unzip (not needed if using CMake)
• Devel/bison (or install Win flex-bison - see Chocolatey below)
• Devel/flex (or install Win flex-bison - see Chocolatey below)
• Devel/git (recommended - see discussion about using Git below)
• Interpreters/perl
• Utils/patch (only if needed) (may be Devel/patch instead)
• Web/wget (not needed if using CMake)
Quick Setup
• Text/asciidoc
• Text/docbook-xml45
You might also have to install
• Interpreters/m4
if installing Devel/bison doesn’t provide a working version of Bison. If m4 is missing bison will fail.
After clicking the Next button several times, the setup will then download and install the selected packages
(this may take a while).
Why is this recommended? Cygwin’s bash version is required, as no native Win32 version is available.
As additional packages can easily be added, Perl and other packages are also used.
Alternatively you can install Cygwin and its packages using Chocolatey:
PS$>choco install cygwin
PS$>choco install cyg-get
PS$>choco install sed asciidoc [...] -source cygwin
Chocolatey installs Cygwin in C:\tools\cygwin by default.
You can use Chocolatey’s Win flex-bison packages rather than the Cygwin Bison and Flex package:
PS$>choco install winflexbison
2.2.6. Install Python
Get the Python 2.7 installer from http://python.org/download/ and install Python into the default location
(C:\Python27).
Why is this recommended? Cygwin’s Python package doesn’t work on some machines, so the Win32
native package is recommended (and it’s faster). Note that Python 3.x isn’t currently supported.
12
Quick Setup
Alternatively you can install Python using Chocolatey:
PS$>choco install python2
Chocolatey installs Python 2 in C:\tools\python2 by default.
2.2.7. Install Git
Please note that the following is not required to build Wireshark but can be quite helpful when working
with the sources.
Working with the Git source repositories is highly recommended, see Section 3.3, “Obtain the Wireshark
sources”. It is much easier to update a personal source tree (local repository) with Git rather than
downloading a zip file and merging new sources into a personal source tree by hand. It also makes firsttime setup easy and enables the Wireshark build process to determine your current source code revision.
There are several ways in which Git can be installed. Most packages are available at the URLs below or
via Chocolatey. Note that many of the GUI interfaces depend on the command line version.
2.2.7.1. The Official Windows Installer
The official command-line installer is available at http://msysgit.github.io/.
2.2.7.2. Git Extensions
Git Extensions is a native Windows graphical Git client for Windows. You can download the installer
from http://code.google.com/p/gitextensions/.
2.2.7.3. TortoiseGit
TortoiseGit is a native Windows graphical Git similar to TortoiseSVN. You can download the installer
from http://code.google.com/p/tortoisegit/.
2.2.7.4. Command Line client via Chocolatey
The command line client can be installed (and updated) using Chocolatey:
PS$> choco install git
2.2.7.5. Others
A list of other GUI interfaces for Git can be found at http://git-scm.com/downloads/guis
2.3. Install CMake
Get the CMake installer from https://cmake.org/download/ and install CMake into the default location.
Ensure the directory containing cmake.exe is added to your path.
Alternatively you can install CMake using Chocolatey:
PS$>choco install cmake.portable
Chocolatey ensures cmake.exe is on your path.
13
Quick Setup
2.3.1. Install and Prepare Sources
Make sure everything works
It’s a good idea to make sure Wireshark compiles and runs at least once before you start
hacking the Wireshark sources for your own project. This example uses Git Extensions but
any other Git client should work as well.
Download sources Download Wireshark sources into C:\Development\wireshark using either the
command line or Git Extensions:
Using the command line:
>cd C:\Development
>git clone https://code.wireshark.org/review/wireshark
Using Git extensions:
1. Open the Git Extensions application. By default Git Extensions will show a validation checklist at
startup. If anything needs to be fixed do so now. You can bring up the checklist at any time via Tools
# Settings.
2. In the main screen select Clone repository. Fill in the following:
Repository to clone: https://code.wireshark.org/review/wireshark
Destination: Your top-level development directory, e.g. C:\Development.
Subdirectory to create: Anything you’d like. Usually wireshark.
Check your paths
Make sure your repository path doesn’t contain spaces.
3. Click the Clone button. Git Extensions should start cloning the Wireshark repository.
2.3.2. Open a Visual Studio Command Prompt
From the Start Menu (or Start Screen), navigate to the Visual Studio 2013 → Visual Studio Tools directory
and choose the Command Prompt appropriate for the build you wish to make, e.g. VS2013 x86 Native
Tools Command Prompt for a 32-bit version, VS2013 x64 Native Tools Command Prompt for a 64-bit
version.
Pin the items to the Task Bar
Pin the Command Prompt you use to the Task Bar for easy access.
All subsequent operations take place in this Command Prompt window.
1. Set environment variables to control the build.
Set the following environment variables, using paths and values suitable for your installation:
> set CYGWIN=nodosfilewarning
> set WIRESHARK_BASE_DIR=C:\Development or set WIRESHARK_LIB_DIR to the appropriate library directory for your build.
> set WIRESHARK_TARGET_PLATFORM=win32 or win64 as required
14
Quick Setup
> set QT5_BASE_DIR=C:\Qt\Qt5.5.0\5.5\msvc2013
> set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo
If your Cygwin installation path is not automatically detected by CMake, you can explicitly specify it
with the following environment variable:
> set WIRESHARK_CYGWIN_INSTALL_PATH=c:\cygwin or whatever other path that is applicable to your setup
If you are using a version of Visual Studio earlier than VS2012 then you must set an additional env
var, e.g. for VS2010 set the following:
> set VisualStudioVersion=10.0
Setting these variables could be added to a batch file to be run after you open the Visual Studio Tools
Command Prompt.
2. Create and change to the correct build directory. CMake is best used in an out-of-tree build configuration
where the build is done in a separate directory to the source tree, leaving the source tree in a pristine
state. 32 and 64 bit builds require a separate build directory. Create (if required) and change to the
appropriate build directory.
> mkdir C:\Development\wsbuild32
> cd C:\Development\wsbuild32
to create and jump into the build directory.
The build directory can be deleted at any time and the build files regenerated as detailed in Section 2.3.3,
“Generate the build files”.
2.3.3. Generate the build files
CMake is used to process the CMakeLists.txt files in the source tree and produce build files appropriate
for your system.
You can generate Visual Studio solution files to build either from within Visual Studio, or from the
command line with MSBuild. CMake can also generate other build types but they aren’t supported.
The initial generation step is only required the first time a build directory is created. Subsequent builds
will regenerate the build files as required.
If you’ve closed the Visual Studio Command Prompt prepare it again.
To generate the build files enter the following at the Visual Studio command prompt:
> cmake -DENABLE_CHM_GUIDES=on -G "Visual Studio 12" ..\wireshark
Adjusting the paths as required to Python and the wireshark source tree. To use a different generator modify
the -G parameter, cmake -G lists all the CMake supported generators, but only Visual Studio is supported
for Wireshark builds.
To build an x64 version, the -G parameter must have a Win64 suffix, e.g. -G "Visual Studio 12 Win64"
The CMake generation process will download the required 3rd party libraries (apart from Qt) as required,
then test each library for usability before generating the build files.
At the end of the CMake generation process the following should be displayed:
-- Configuring done
-- Generating done
15
-- Build files have been written to: C:/Development/wsbuild32
If you get any other output, there is an issue in your envirnment that must be rectified before building.
Check the parameters passed to CMake, especially the -G option and the path to the Wireshark sources
and the environment variables WIRESHARK_BASE_DIR, WIRESHARK_TARGET_PLATFORM and
QT5_BASE_DIR.
2.3.4. Build Wireshark
Now it’s time to build Wireshark!
1. If you’ve closed the Visual Studio Command Prompt prepare it again.
2. Run
> msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln
to build Wireshark.
3. Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the
command prompt window
4. For the QT version run C:\Development\wsbuild32\run\RelWithDebInfo
\Wireshark.exe and make sure it starts.
Quick Setup
5. For the older GTK version run C:\Development\wsbuild32\run\RelWithDebInfo
\wireshark-gtk.exe.
6. Open Help # About. If it shows your "private" program version, e.g.: Version 2.1.x-myprotocol123
congratulations! You have compiled your own version of Wireshark!
You may also open the Wireshark solution file (Wireshark.sln) in the Visual Studio IDE and build there.
Tip
If compilation fails for suspicious reasons after you changed some source files try to clean the
build files by running msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean
and then building the solution again.
The build files produced by CMake will regenerate themselves if required by changes in the source tree.
2.3.5. Debug Environment Setup
You can debug using the Visual Studio Debugger or WinDbg. See the section on using the Debugger Tools.
2.3.6. Optional: Create User’s and Developer’s Guide
Detailed information to build these guides can be found in the file docbook\README.txt in the Wireshark
sources.
2.3.7. Optional: Create a Wireshark Installer
Note: You should have successfully built Wireshark before doing the following.
If you want to build your own wireshark-win32-2.1.x-myprotocol123.exe, you’ll need NSIS.
16
Quick Setup
1. NSIS: Download and install NSIS
Note that the 32-bit version of NSIS will work for both 32-bit and 64-bit versions of Wireshark.
Note: If you do not yet have a copy of vcredist_x86.exe or vcredist_x64.exe in ./wireshark-winXX-libs
(where XX is 32 or 64) you will need to download the appropriate file and place it in ./wireshark-winXXlibs before starting this step.
If building an x86 version using a Visual Studio "Express" edition or an x64 version with any edition,
then you must have the appropriate vcredist file for your compiler in the support libraries directory
(vcredist_x86.exe in wireshark-32-libs or vcredist_x64.exe in wireshark-win64-libs).
The files can be located in the Visual Studio install directory for non-Express edition builds, or downloaded
from Microsoft for Expresss edition builds.
Note you must use the correct version of vcredist for your compiler, unfortunately they all have the same
name (vcredist_x86.exe or vcredist_x64.exe). You can use Windows Explorer and examine the Properties
>> Details tab for a vcredist file to determine which compiler version the file is for use with.
1. If you’ve closed the Visual Studio Command Prompt prepare it again.
2. Run
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj
to build a Wireshark installer.
3. Run
> C:\Development\wireshark\packaging\nsis\wireshark-win32-wireshark-major-minor-version:[].x-myprotocol123.exe
to test your new installer. It’s a good idea to test on a different machine than the developer machine.
Note that if you’ve built an x64 version, the installer will be named accordingly.
17
Chapter 3. Work with the Wireshark sources
3.1. 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 Section 7.1, “Source overview”.
3.2. The Wireshark Git repository
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 Gerrit code review system. Gerrit makes it easy
to test and discuss changes before they are pushed to the main repository. For an overview of Gerrit see
the Quick Introduction.
Why Git? Git is a fast, flexible way of managing source code. It allows large scale distributed
development and ensures data integrity.
Why Gerrit? Gerrit makes it easy to contribute. You can sign in with any OpenID provider and push
your changes. It’s usable from both the web and command line and is integrated with many popular tools.
Git is our third revision control system
Wireshark originally used Concurrent Versions System (CVS) and migrated to 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
3.2.1. 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:
18
Work with the Wireshark sources
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 branching to manage different copies of the source code and
allow parallel development. Wireshark uses the following branches for official releases:
• master: Main feature development and odd-numbered "feature" releases.
• master-x.y: Stable release maintenance. For example, master-1.10 is used to manage the 1.10.x official
releases.
3.3. Obtain the Wireshark sources
There are several ways to obtain the sources from Wireshark’s Git repository.
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.
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.
3.3.1. Git over SSH or HTTPS
Recommended for development purposes.
Age: a few minutes.
You can use a Git client to download the source code from Wireshark’s code review system. Anyone can
clone from the anonymous git URL:
• https://code.wireshark.org/review/wireshark
If you create a Gerrit account you can clone from an authenticated URL:
• ssh://your.username@code.wireshark.org:29418/wireshark
• https://your.username@code.wireshark.org/review/wireshark
SSH lets you use Gerrit on the 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.
19
Work with the Wireshark sources
The following example shows how to get up and running on the command line. See Section 4.13, “Git
client” for information on installing and configuring graphical Git and Gerrit clients.
1. Sign in to https://code.wireshark.org/review using OpenID (click Register or Sign In in the upper right
corner of the web page). Follow the login instructions.
2. In the upper right corner of the web page, click on your account name and select Settings.
3. 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.
4. Select SSH Public Keys and add one or more keys. You will typically upload a key for each computer
that you use.
5. Install git-review. This is an installable package in many Linux distributions. You can also install it as
a Python package. (This step isn’t strictly necessary but it makes working with Gerrit much easier.) To
install it from Chocolatey run
# Make sure "Scripts" is in our path
PS$>$env:path += ";C:\tools\python2\Scripts"
PS$>choco install pip
PS$>choco install git-review -source python
6. Now on to the command line. First, make sure git works:
$ git --version
7. 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
8. 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.
9. 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.
10.Initialize git-review.
$ git review -s
This prepares your local repository for use with Gerrit, including installing the commit-msg hook
script.
3.3.2. Git web interface
Recommended for informational purposes only, as only individual files can be downloaded.
20
Loading...