Thanks to the Win32 API, development on all Windows platforms will be done in a very similar way. All Windows platforms referred to as Win32, Win or Windows may be used with the same meaning. Older Windows versions are no longer supported by Wireshark. As Windows CE differs a lot compared to the other Windows platforms mentioned, Wireshark will not run on Windows CE and there are no plans to support it.

Almost any part of Wireshark is implemented in plain ANSI 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.

So unless you are going to change the development 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 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.

Wireshark is an open source software project, and is released under the GNU General Public Licence (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 team.

You gain three benefits by contributing your improvements back to the community:

The Wireshark source code and binary kits for some platforms are all available on the download page of the Wireshark website: http://www.wireshark.org/download/.

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:

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.12, “Binary packaging”.

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 SVN 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.

The Buildbot will do the following (to a different degree on the different platforms):

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:

Each platform is represented at the status page by a single column, the most recent entries are at the top.

You will find lot's of useful information on the Wireshark homepage at http://www.wireshark.org.

The Wireshark Wiki at http://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.

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.

The "Frequently Asked Questions" will list often asked questions and the corresponding answers.

	Read the FAQ!
	Before sending any mail to the mailing lists below, be sure to read the FAQ, as it will often answer the question(s) 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: http://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.

If you don't find the information you need inside this book, there are various other sources of information:

There are several mailing lists available on specific Wireshark topics:

You can subscribe to each of these lists from the Wireshark web site: http://www.wireshark.org. Simply select the mailing lists link on the left hand side of the site. The lists are archived at the Wireshark web site as well.

	Tip!
	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.

The Wireshark community collects bug reports in a Bugzilla database at http://bugs.wireshark.org. This database is filled with manually filed bug reports, usually after some discussion on wireshark-dev, and bug reports from the QA build tools.

	Note!
	Before reporting any problems, please make sure you have installed the latest version of Wireshark.

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:

	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.

When reporting crashes with Wireshark, it is helpful if you supply the traceback information (besides the information mentioned in Section 1.7.7, “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
$

		

	Note
	Type the characters in the first line verbatim! Those are back-tics there!

	Note
	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.

	Note
	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[AT]wireshark.org mailing list, or append it to your bug report.

The Windows distributions don't contain the symbol files (.pdb), because they are very large. For this reason it's not possible to create a meaningful backtrace file from it. You should report your crash just like other problems, using the mechanism from Section 1.7.7, “Reporting Problems”.

You need to install:

Install MSVC the usual way. Don't forget to install vcvars32.bat or call it manually before building Wireshark. vcvars32.bat will set some required environment (e.g. the PATH) settings.

	Other Microsoft C compiler variants possible!
	It's possible to compile Wireshark with a wide range of Microsoft C compiler variants, for details see Section 4.4, “Microsoft compiler toolchain (Win32 native)”!

	Don't use cygwin's gcc!
	Using cygwin's gcc is not recommended and will certainly not work (at least without a lot of advanced tweaking). For further details on this topic, see Section 4.3, “GNU compiler toolchain (UNIX or Win32 Cygwin)”.

XXX - mention the compiler and PSDK web installers - which significantly reduce download size - and find out the required components

XXX - how to get the right PATH settings?

Why this is recommended: While this is a huge download, the 2005 express edition is the only free (as in beer) version that includes the Visual Studio integrated debugger.

Download the 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 click on the "Skip" item in the "New" column so it shows a version number for:

After clicking the Next button several times, the setup will then download and install the selected packages (this may take a while).

Why this is recommended: Cygwin's bash version is required, as no native Win32 version is available. As additional packages can easily be added, the perl and alike packages are also used.

Get the python 2.4 installer from: http://python.org/download/ and install python into the default location (currently: C:/Python24).

Beware: python 2.5 won't work without modifications.

Why this is recommended: Cygwin's python package doesn't work on some machines, so the Win32 native package is recommended.

Please note that the following is not required to build Wireshark, but can be quite helpful when working with the sources.

Why this is recommended: updating a personal source tree is significantly easier to do with Subversion than downloading a zip file and merging new sources into a personal source tree "by hand".

	Tip
	It's a good idea to successfully compile and run Wireshark at least once before you start hacking the Wireshark sources for your own project!

¹Compiler dependent: This step depends on the compiler variant used, for other variants than the recommended Visual C++ 2005 Express Edition see the table at Section 4.4, “Microsoft compiler toolchain (Win32 native)”!

²International Windows might use different values here, e.g. a german version uses C:/Programme - take this also in account where C:\Program Files appears elsewhere

Prepare cmd.exe - set environment and current dir.

¹Compiler dependent: This step depends on the compiler variant used, for other variants than the recommended Visual C++ 2005 Express Edition see the table at Section 4.4, “Microsoft compiler toolchain (Win32 native)”!

²International Windows might use different values here, e.g. a german version uses C:/Programme - take this also in account where C:\Program Files appears elsewhereNote: You need to repeat steps 1 - 4 each time you open a new cmd.exe!

After you've installed the Wireshark sources (see Section 3.3, “Obtain the Wireshark sources”), you can check the correct installation of all tools by using the verify_tools target of the Makefile.nmake from the source package.

	Warning!
	You will need the Wireshark sources and some tools (nmake, bash) installed, before this verification is able to work.

Enter at the command line (cmd.exe, not Cygwin's bash!):

> nmake -f Makefile.nmake verify_tools

This will check for the various tools needed to build Wireshark:

          Checking for required applications:
        cl: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/cl
        link: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/link
        nmake: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/nmake
        bash: /usr/bin/bash
        bison: /usr/bin/bison
        flex: /usr/bin/flex
        env: /usr/bin/env
        grep: /usr/bin/grep
        /usr/bin/find: /usr/bin/find
        perl: /usr/bin/perl
        env: /usr/bin/env
        C:/python24/python.exe: /cygdrive/c/python24/python.exe
        sed: /usr/bin/sed
        unzip: /usr/bin/unzip
        wget: /usr/bin/wget

If you have problems with all the first three items (cl, link, nmake), check if you called vcvars32/SetEnv as mentioned in Section 2.2.6, “Prepare cmd.exe” (which will "fix" your PATH settings). However, the exact text will be slightly different depending on the MSVC version used.

Unfortunately, the link command is defined both in cygwin and in MSVC each with completely different functionality; you'll need the MSVC link. If your link command looks something like: /usr/bin/link, the link command of cygwin takes precedence over the MSVC one. To fix this, you can change your PATH environment setting or simply rename the link.exe in cygwin. If you rename it, make sure to remember that a cygwin update may provide a new version of it.

The released Wireshark sources contain files that are prepared for a UNIX build (e.g. config.h).

You must distclean your sources before building the first time!

Now it's time to build Wireshark ...

Tip: If compilation fails for suspicious reasons after you changed some source files try to distclean the sources and make "all" again

XXX - debug needs to be written, e.g. an idea is the create a simple MSVC 6 workspace/project(s) to ease Visual Studio debugging

Detailed information to build these guides can be found in the file docbook/README.txt in the Wireshark sources.

Note: You should have successfully built Wireshark before doing the following!

If you want to build your own wireshark-setup.exe, you'll need NSIS.

¹Compiler dependent: This step depends on the compiler variant used, for other variants than the recommended Visual C++ 2005 Express Edition see the table at Section 4.4, “Microsoft compiler toolchain (Win32 native)”!

If you need a quick look at the Wireshark source code, you will only need a Web browser.

A simple view on the latest developer version can be found at:

http://anonsvn.wireshark.org/wireshark/trunk/.

A comprehensive view of all source versions (e.g. including the capability to show differences between versions) is available at:

http://anonsvn.wireshark.org/viewvc/viewvc.cgi/.

Of special interest might be the subdirectories:

Recommended for development purposes.

Age: a few minutes.

You can use a Subversion client to download the source code from Wireshark's anonymous Subversion repository. The URL for the repository trunk is: http://anonsvn.wireshark.org/wireshark/trunk/.

See Section 4.11, “Subversion (SVN) client (optional)” on how to install a Subversion client.

For example, to check out using the command-line Subversion client, you would type:

$ svn checkout http://anonsvn.wireshark.org/wireshark/trunk wireshark

The checkout has to be only done once. This will copy all the sources of the latest version (including directories) from the server to your machine. This will take some time, depending on the speed of your internet connection.

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

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

The entire source tree of the Subversion repository is available via a web interface at: http://anonsvn.wireshark.org/viewvc/viewvc.cgi/. 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.

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

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

The buildbot server will automatically start to generate a snapshot of Wireshark's source tree after a source code change is committed. These snapshots can be found at: http://www.wireshark.org/download/automated/src/.

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

Recommended for productive purposes.

Age: from days to weeks.

The officially released source files can be found at: http://www.wireshark.org/download/. You should use these sources if you want to build Wireshark on your platform for productive use.

The differences between the released sources and the sources stored at the Subversion repository will keep on growing until the next release is done (at the release time, the released and latest Subversion repository versions are then identical again :-).

After the first time checkout is done, updating your sources is simply done by typing (in the Wireshark source dir):

$ svn update

This will only take a few seconds, even on a slow internet connection. It will replace old file versions by new ones. If you and someone else have changed the same file since the last update, Subversion will try to merge the changes into your private file (this works remarkably well).

Independent of the way you retrieve the zip file of the Wireshark sources (as described in Section 3.3, “Obtain the Wireshark sources” ), the way to bring the changes from the official sources into your personal source tree is identical.

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

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

Well, if you did change something in your source tree, you have to merge the official changes since the last update into your source tree. You will install the content of the zip file into a new directory and use a good merge tool (e.g. http://winmerge.sourceforge.net/ for Win32) to bring your personal source tree in sync with the official sources again.

Run the autogen.sh script at the top-level wireshark directory to configure your build directory.

./autogen.sh
./configure
make
	

If you need to build with a GTK 1.x version, you have to use:

./configure --disable-gtk2
	

instead of just ./configure.

The first thing to do will be to check the file config.nmake to determine if it reflects your configuration. The settings in this file are well documented, so please have a look at that file. However, if you've installed the libraries and tools as recommended there should be no need to edit things here.

Many of the file and directory names used in the build process go past the old 8.3 naming limitations. As a result, you should use the "cmd.exe" command interpreter instead of the old "command.com".

Be sure that your command-line environment is set up to compile and link with MSVC++. When installing MSVC++, you can have your system's environment set up to always allow compiling from the command line, or you can invoke the vcvars32.bat script, which can usually be found in the "VC98\Bin" subdirectory of the directory in which Visual Studio was installed.

You should then cleanup any intermediate files, which are shipped for convenience of Unix users, by typing at the command line prompt (cmd.exe):

> nmake -f Makefile.nmake distclean

After doing this, typing at the command line prompt (cmd.exe):

> nmake -f Makefile.nmake all

will start the whole Wireshark build process.

After the build process has successfully finished, you should find a wireshark.exe and some other files in the root directory.

XXX - add more info here.

A diff file is a plain text file containing the differences between a pair of files (or a multiple of such file pairs).

	Tip!
	A diff file is often also called a patch, as 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:

Index: file.h
===================================================================
--- file.h      (revision 21134)
+++ file.h      (revision 22401)
@@ -142,7 +142,7 @@
  * @param err the error code, if an error had occured
  * @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.

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.