forked from osmocom/wireshark
![Gerald Combs](/assets/img/avatar_default.png)
Change-Id: Ie4ad0388b920ba4a8483ad8af351ddbdd121a28b Reviewed-on: https://code.wireshark.org/review/6254 Reviewed-by: Gerald Combs <gerald@wireshark.org>
1208 lines
35 KiB
Text
1208 lines
35 KiB
Text
++++++++++++++++++++++++++++++++++++++
|
|
<!-- WSDG Chapter Tools -->
|
|
++++++++++++++++++++++++++++++++++++++
|
|
|
|
[[ChapterTools]]
|
|
|
|
== Tool Reference
|
|
|
|
[[ChToolsIntro]]
|
|
|
|
=== Introduction
|
|
|
|
This chapter will provide you with information about the
|
|
various tools needed for Wireshark development.
|
|
|
|
None of the tools mentioned in this chapter are needed to
|
|
run Wireshark; they are only needed to build it.
|
|
|
|
Most of these tools have their roots on UNIX like
|
|
platforms, but Windows ports are also available. Therefore the
|
|
tools are available in different "flavours":
|
|
|
|
* UNIX (or Windows Cygwin): the tools should be commonly available on the
|
|
supported UNIX platforms, and for Windows platforms by using the Cygwin UNIX
|
|
emulation
|
|
|
|
* Windows native: some tools are available as native Windows tools, no special
|
|
emulation is required. Many of these tools can be installed (and updated)
|
|
using http://chocolatey.org[Chocolatey], a Windows package manager similar
|
|
to the Linux package managers apt-get or yum.
|
|
|
|
[WARNING]
|
|
.Follow the directions
|
|
====
|
|
Unless you know exactly what you are doing, you should strictly follow the recommendations given in <<ChapterSetup>>.
|
|
====
|
|
|
|
The following sections give a very brief description of
|
|
what a particular tool is doing, how it is used in the
|
|
Wireshark project and how it can be installed and
|
|
tested.
|
|
|
|
Documentation for these tools is outside the scope of this document. If you need
|
|
further information on using a specific tool you should find lots of useful
|
|
information on the web, as these tools are commonly used. You can also get help
|
|
for the UNIX based tools with `toolname --help` or the man page via `man
|
|
toolname`.
|
|
|
|
You will find explanations of the tool usage for some of the specific
|
|
development tasks in <<ChapterSources>>.
|
|
|
|
[[ChToolsWindowsPowerShell]]
|
|
|
|
=== Windows PowerShell
|
|
|
|
PowerShell 2.0 or later is required for building Wireshark and the NSIS package.
|
|
Windows 7 and later include compatible versions.
|
|
|
|
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[]
|
|
|
|
=== Chocolatey
|
|
|
|
Chocolatey is a Windows package manager that can be used to install (and update)
|
|
many of the packages required for Wireshark development. Chocolatey can be
|
|
obtained from the http://chocolatey.org[website] or from a DOS command prompt:
|
|
|
|
----
|
|
C:\>@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
|
|
----
|
|
|
|
or a Powershell prompt:
|
|
|
|
----
|
|
PS:\>iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))
|
|
----
|
|
|
|
[[ChToolsCygwin]]
|
|
|
|
=== Windows: Cygwin
|
|
|
|
Cygwin provides a lot of UNIX based tools on the Windows platform. It uses a UNIX
|
|
emulation layer which might be a bit slower compared to the native Windows tools,
|
|
but at an acceptable level. The installation and update is pretty easy and done
|
|
through a single utility, 'setup-x86.exe' for 32-bit Windows and
|
|
'setup-x86_64.exe' for 64-bit Windows.
|
|
|
|
The native Windows tools will typically be a bit faster but more complicated to
|
|
install, as you would have to download the tools from different web sites and
|
|
install and configure them individually.
|
|
|
|
|
|
[NOTE]
|
|
.You must have Cygwin installed
|
|
====
|
|
As there's no Windows native bash version available, at least a basic installation
|
|
of Cygwin is required in any case. This may change in the future as packaging
|
|
systems such as NuGet and Chocolatey mature.
|
|
====
|
|
|
|
Although Cygwin consists of several separate packages, the installation
|
|
and update is done through a single utility, 'setup-x86.exe' or
|
|
'setup-x86_64.exe', which acts similarly to other web based installers.
|
|
All tools will be installed into one base folder. The default is
|
|
'C:\cygwin'.
|
|
|
|
You will find 'setup-x86.exe', for 32-bit systems, and
|
|
'setup-x86_64.exe', for 64-bit systems, at
|
|
http://www.cygwin.com/install.html[]. Click on the link for the
|
|
appropriate setup utility to download it. After the download completes,
|
|
run it.
|
|
|
|
The setup utility will ask you for some settings. The defaults
|
|
should usually work well, at least initially.
|
|
|
|
If, at the "Choose A Download Source" page, you use the default "Install
|
|
from Internet" setting, you will need to choose a download site at the
|
|
"Choose A Download Site" page. See the list of mirror sites at
|
|
http://cygwin.com/mirrors.html[] to choose a download site appropriate
|
|
to your location.
|
|
|
|
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 the required package.
|
|
|
|
After clicking the Next button several times the setup
|
|
will then download and install the selected packages (this may
|
|
take a while, depending on the package size).
|
|
|
|
Under: 'Start->Programs->Cygwin->Cygwin Bash Shell' you should now be able to start
|
|
a new Cygwin bash shell, which is similar to the standard Windows command line
|
|
interpreters (command.com / cmd.exe) but much more powerful.
|
|
|
|
[[ChToolsCygwinPackages]]
|
|
|
|
==== Add/Update/Remove Cygwin Packages
|
|
|
|
If you want to add, update, or remove packages later you can do so by
|
|
running the setup utility again. At the "Select Packages" page, the
|
|
entry in the "New" column will control what is done (or not) with the
|
|
package. If a new version of a package is available, the new version
|
|
number will be displayed, so it will be automatically updated. You can
|
|
change the current setting by simply clicking at it, it will change
|
|
between:
|
|
|
|
* 'A specific version number.' This specific package version will be installed.
|
|
|
|
* 'Skip.' Not installed, no changes.
|
|
|
|
* 'Keep.' Already installed, no changes.
|
|
|
|
* 'Uninstall.' Uninstall this package.
|
|
|
|
* 'Reinstall.' Reinstall this package.
|
|
|
|
[[ChToolsGNUChain]]
|
|
|
|
=== GNU compiler toolchain (UNIX only)
|
|
|
|
[[ChToolsGCC]]
|
|
|
|
==== gcc (GNU compiler collection)
|
|
|
|
The GCC C compiler is available for most of the
|
|
UNIX-like platforms.
|
|
|
|
If GCC isn't already installed or available
|
|
as a package for your platform, you can get it at:
|
|
http://gcc.gnu.org/[].
|
|
|
|
After correct installation, typing at the
|
|
bash command line prompt:
|
|
|
|
----
|
|
$ gcc --version
|
|
----
|
|
|
|
should result in something like
|
|
|
|
----
|
|
gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1
|
|
Copyright (C) 2014 Free Software Foundation, Inc.
|
|
This is free software; see the source for copying conditions. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
----
|
|
|
|
Your version string may vary, of course.
|
|
|
|
[[ChToolsGDB]]
|
|
|
|
==== gdb (GNU project debugger)
|
|
|
|
GDB is the debugger for the GCC compiler. It is
|
|
available for many (if not all) UNIX-like platforms.
|
|
|
|
If you don't like debugging using the command line
|
|
there are some GUI frontends for it available, most notably
|
|
GNU DDD.
|
|
|
|
If gdb isn't already installed or available
|
|
as a package for your platform, you can get it at:
|
|
http://www.gnu.org/software/gdb/gdb.html[].
|
|
|
|
After correct installation:
|
|
|
|
----
|
|
$ gdb --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
GNU gdb (Ubuntu 7.8-1ubuntu4) 7.8.0.20141001-cvs
|
|
Copyright (C) 2014 Free Software Foundation, Inc.
|
|
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
|
|
This is free software: you are free to change and redistribute it.
|
|
There is NO WARRANTY, to the extent permitted by law. Type "show copying"
|
|
and "show warranty" for details.
|
|
This GDB was configured as "x86_64-linux-gnu".
|
|
Type "show configuration" for configuration details.
|
|
For bug reporting instructions, please see:
|
|
<http://www.gnu.org/software/gdb/bugs/>.
|
|
Find the GDB manual and other documentation resources online at:
|
|
<http://www.gnu.org/software/gdb/documentation/>.
|
|
For help, type "help".
|
|
Type "apropos word" to search for commands related to "word".
|
|
----
|
|
|
|
Your version string may vary, of course.
|
|
|
|
[[ChToolsDDD]]
|
|
|
|
|
|
==== ddd (GNU Data Display Debugger)
|
|
|
|
The GNU Data Display Debugger is a good GUI frontend
|
|
for GDB (and a lot of other command line debuggers), so you
|
|
have to install GDB first. It is available for many UNIX-like
|
|
platforms.
|
|
|
|
If GNU DDD isn't already installed or
|
|
available as a package for your platform, you can get it at:
|
|
http://www.gnu.org/software/ddd/[].
|
|
|
|
[[ChToolsGNUmake]]
|
|
|
|
==== make (GNU Make)
|
|
|
|
[NOTE]
|
|
.GNU make isn't supported either for Windows
|
|
|
|
GNU Make is available for most of the UNIX-like
|
|
platforms.
|
|
|
|
If GNU Make isn't already installed or
|
|
available as a package for your platform, you can get it at:
|
|
http://www.gnu.org/software/make/[].
|
|
|
|
After correct installation:
|
|
|
|
----
|
|
$ make --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
GNU Make 4.0
|
|
Built for x86_64-pc-linux-gnu
|
|
Copyright (C) 1988-2013 Free Software Foundation, Inc.
|
|
Licence GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
|
|
This is free software: you are free to change and redistribute it.
|
|
There is NO WARRANTY, to the extent permitted by law.
|
|
----
|
|
|
|
Your version string may vary, of course.
|
|
|
|
[[ChToolsMSChain]]
|
|
|
|
=== Microsoft compiler toolchain (Windows native)
|
|
|
|
To compile Wireshark on Windows using the Microsoft C/$$C++$$
|
|
compiler, you'll need:
|
|
|
|
. C compiler (`cl.exe`)
|
|
|
|
. Assembler (`ml.exe` for 32-bit targets and `ml64.exe` for 64-bit targets)
|
|
|
|
. Linker (`link.exe`)
|
|
|
|
. Make (`nmake.exe`)
|
|
|
|
. C runtime headers and libraries (e.g. 'stdio.h', 'msvcrt.lib')
|
|
|
|
. Windows platform headers and libraries (e.g.
|
|
'windows.h', 'WSock32.lib')
|
|
+
|
|
// Can we drop support for CHM?
|
|
. HTML help headers and libraries ('htmlhelp.h', 'htmlhelp.lib')
|
|
|
|
==== Toolchain Package Alternatives
|
|
|
|
The Wireshark 1.99.x releases are compiled using Microsoft Visual $$C++$$ 2013.
|
|
The official Wireshark 1.12.x and 1.10.x releases are compiled using
|
|
Microsoft Visual $$C++$$ 2010 SP1.
|
|
The official 1.8 releases were compiled using
|
|
Microsoft Visual $$C++$$ 2010 SP1 as well.
|
|
The official 1.6, 1.4, and 1.2 releases were compiled using
|
|
Microsoft Visual $$C++$$ 2008 SP1.
|
|
Other past releases, including the 1.0 branch,
|
|
were compiled using Microsoft Visual $$C++$$ 6.0.
|
|
|
|
Using the release
|
|
compilers is recommended for Wireshark development work.
|
|
|
|
The older "Express
|
|
Edition" compilers such as Visual $$C++$$ 2010 Express Edition SP1 can be
|
|
used but any PortableApps packages you create with them
|
|
will require the installation of a separate Visual $$C++$$
|
|
Redistributable package on any machine on which the PortableApps
|
|
package is to be used. See
|
|
<<msvc-runtime-redistributable>> below for more details.
|
|
|
|
However, you might already have a different Microsoft $$C++$$ compiler
|
|
installed. It should be possible to use any of the following with the considerations listed:
|
|
|
|
.Visual C++ 2013 Community Edition
|
|
|
|
IDE + Debugger?:: Yes
|
|
|
|
Purchase required?:: http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs#d-community[Free Download]
|
|
|
|
SDK required for 64-bit builds?:: No
|
|
|
|
config.nmake MSVC_VARIANT:: MSVC2013
|
|
|
|
.Visual C++ 2010 Express Edition
|
|
|
|
IDE + Debugger?:: Yes
|
|
|
|
Purchase required?:: http://www.microsoft.com/express/Downloads/#Visual_Studio_2010_Express_Downloads[Free Download]
|
|
|
|
SDK required for 64-bit builds?:: Yes.
|
|
|
|
config.nmake MSVC_VARIANT:: MSVC2010EE
|
|
|
|
Remarks:: Installers created using express editions require a $$C++$$ redistributable
|
|
'$$vcredist_x86.exe$$' (3MB free
|
|
download) is required to build
|
|
Wireshark-win32-wireshark-major-minor-version:[].x.exe, and
|
|
'$$vcredist_x64.exe$$' is required to build
|
|
Wireshark-win64-wireshark-major-minor-version:[].x.exe. The version of
|
|
'$$vcredist_x86.exe$$' or '$$vcredist_x64.exe$$' _must_ match the version for your
|
|
compiler including any service packs installed for the compiler.]
|
|
|
|
.Visual Studio 2010
|
|
|
|
IDE + Debugger?:: Yes
|
|
|
|
Purchase required?:: Yes
|
|
|
|
SDK required for 64-bit builds?:: No
|
|
|
|
config.nmake MSVC_VARIANT:: MSVC2010
|
|
|
|
Remarks:: Building a 64-bit installer
|
|
requires a a $$C++$$ redistributable
|
|
('$$vcredist_x86.exe$$').footnoteref[vcredist]
|
|
|
|
You can use Chocolatey to install Visual Studio, e.g:
|
|
|
|
----
|
|
PS:\> cinst VisualStudioCommunity2013
|
|
----
|
|
|
|
==== cl.exe (C Compiler)
|
|
|
|
The following table gives an overview of the possible
|
|
Microsoft toolchain variants and their specific C compiler
|
|
versions ordered by release date.
|
|
|
|
|===============
|
|
|Compiler Package|cl.exe|_MSC_VER|CRT DLL
|
|
|Visual Studio 2013|12.0|1800|msvcr120.dll
|
|
|Visual Studio 2010|10.0|1600|msvcr100.dll
|
|
|Visual Studio 2010 Express Edition
|
|
|===============
|
|
|
|
After correct installation of the toolchain, typing
|
|
at the Visual Studio Command line prompt (cmd.exe):
|
|
|
|
----
|
|
> cl
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
Microsoft (R) C/C++ Optimizing Compiler Version 18.00.31101 for x86
|
|
Copyright (C) Microsoft Corporation. All rights reserved.
|
|
|
|
usage: cl [ option... ] filename... [ /link linkoption...
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
Documentation on the compiler can be found at
|
|
http://msdn.microsoft.com/en-us/library/wk21sfcf.aspx[Microsoft MSDN]
|
|
|
|
[[ChToolsNMake]]
|
|
|
|
==== nmake.exe (Make)
|
|
|
|
Nmake is part of the toolchain packages described
|
|
above.
|
|
|
|
Instead of using the workspace (.dsw) and projects (.dsp) files, the traditional
|
|
nmake makefiles are used. This has one main reason: it makes it much easier to
|
|
maintain changes simultaneously with the GCC toolchain makefile.am files as both
|
|
file formats are similar. However, as no Visual Studio workspace/project files
|
|
are available, this makes it hard to use the Visual Studio IDE e.g. for using
|
|
the integrated debugging feature.
|
|
|
|
After correct installation, typing at the Visual Studio Command line prompt (cmd.exe):
|
|
|
|
----
|
|
> nmake
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
Microsoft (R) Program Maintenance Utility Version 12.00.21005.1
|
|
Copyright (C) Microsoft Corporation. All rights reserved.
|
|
|
|
NMAKE : fatal error U1064: MAKEFILE not found and no target specified
|
|
Stop.
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
Documentation on nmake can be found at
|
|
http://msdn.microsoft.com/en-us/library/dd9y37ha.aspx[Microsoft MSDN]
|
|
|
|
==== link.exe (Linker)
|
|
|
|
After correct installation, typing at the Visual Studio Command line prompt (cmd.exe):
|
|
|
|
----
|
|
> link
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
Microsoft (R) Incremental Linker Version 12.00.31101.0
|
|
Copyright (C) Microsoft Corporation. All rights reserved.
|
|
|
|
usage: LINK [options] [files] [@commandfile]
|
|
...
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
Documentation on the linker can be found at
|
|
http://msdn.microsoft.com/en-us/library/t2fck18t.aspx[Microsoft MSDN]
|
|
|
|
[[msvc-runtime-redistributable]]
|
|
|
|
|
|
==== C-Runtime "Redistributable" Files
|
|
|
|
Please note: The following is not legal advice - ask your preferred lawyer
|
|
instead. It's the authors view and this view might be wrong.
|
|
|
|
Depending on the Microsoft compiler version you use, some binary files coming
|
|
from Microsoft might be required to be installed on Windows machine to run
|
|
Wireshark. On a developer machine, the compiler setup installs these files so
|
|
they are available - but they might not be available on a user machine!
|
|
|
|
This is especially true for the C runtime DLL (msvcr*.dll), which contains the
|
|
implementation of ANSI and alike functions, e.g.: fopen(), malloc(). The DLL is
|
|
named like: msvcr'version'.dll, an abbreviation for "MicroSoft Visual C
|
|
Runtime". For Wireshark to work, this DLL must be available on the users
|
|
machine.
|
|
|
|
Starting with MSVC7, it is necessary to ship the C runtime DLL
|
|
(msvcr'version'.dll) together with the application installer somehow, as that
|
|
DLL is possibly not available on the target system.
|
|
|
|
|
|
[NOTE]
|
|
.Make sure you're allowed to distribute this file
|
|
====
|
|
The files to redistribute must be mentioned in the
|
|
redist.txt file of the compiler package. Otherwise it
|
|
can't be legally redistributed by third parties like
|
|
us.
|
|
====
|
|
|
|
The following MSDN link is recommended for the
|
|
interested reader:
|
|
|
|
* http://msdn.microsoft.com/en-us/library/ms235299.aspx[Redistributing Visual C++ Files]
|
|
|
|
In all cases where '$$vcredist_x86.exe$$' or '$$vcredist_x64.exe$$' is
|
|
downloaded it should be downloaded to the directory into which the support
|
|
libraries for Wireshark have been downloaded and installed. This directory is
|
|
specified by the WIRESHARK_LIB_DIR setting in the 'config.nmake'. By default it
|
|
is 'C:\Development\wireshark-win32-libs'. It need not, and should not, be run after being
|
|
downloaded.
|
|
|
|
===== msvcr120.dll / vcredist_x86.exe / vcredist_x64.exe - Version 12.0 (2013)
|
|
|
|
There are three redistribution methods that MSDN
|
|
mentions for MSVC 2013 (see:
|
|
http://msdn.microsoft.com/en-us/library/vstudio/ms235316(v=vs.120).aspx["Choosing a Deployment Method"]):
|
|
|
|
. 'Using Visual $$C++$$ Redistributable Package'.
|
|
The Microsoft libraries are installed by copying
|
|
'$$vcredist_x64.exe$$' or
|
|
'$$vcredist_x86.exe$$' to the target
|
|
machine and executing it on that machine (MSDN recommends
|
|
this for applications built with Visual Studio 2013)
|
|
|
|
. 'Using Visual $$C++$$ Redistributable Merge Modules'.
|
|
(Loadable modules for building msi installers.
|
|
Not suitable for Wireshark's NSIS based installer)
|
|
|
|
. 'Install a particular Visual $$C++$$ assembly as a
|
|
private assembly for the application'. The
|
|
Microsoft libraries are installed by copying the folder
|
|
content of 'Microsoft.VC120.CRT' to
|
|
the target directory (e.g. 'C:\Program Files\Wireshark')
|
|
|
|
To save installer size, and to make a portable
|
|
version of Wireshark (which must be completely self-contained,
|
|
on a medium such as a flash drive, and not require that an
|
|
installer be run to install anything on the target machine)
|
|
possible, when building 32-bit Wireshark with MSVC2013, method
|
|
3 (copying the content of 'Microsoft.VC120.CRT')
|
|
is used (this produces the smallest package).
|
|
|
|
==== Windows (Platform) SDK
|
|
|
|
The Windows Platform SDK (PSDK) or Windows SDK is a free
|
|
(as in beer) download and contains platform specific headers and
|
|
libraries (e.g. 'windows.h', 'WSock32.lib', etc.). As new Windows
|
|
features evolve in time, updated SDK's become available that
|
|
include new and updated APIs.
|
|
|
|
When you purchase a commercial Visual Studio or use the Community Edition, it will
|
|
include an SDK. The free Express (as in beer) downloadable C compiler
|
|
versions (V$$C++$$ 2012 Express, V$$C++$$ 2012 Express, etc.) do not
|
|
contain an SDK -- you'll need to download a PSDK in order to
|
|
have the required C header files and libraries.
|
|
|
|
Older versions of the SDK should also work. However, the
|
|
command to set the environment settings will be different, try
|
|
search for SetEnv.* in the SDK directory.
|
|
|
|
==== HTML Help
|
|
|
|
HTML Help is used to create the User's and Developer's Guide in .chm format and
|
|
to show the User's Guide as the Wireshark "Online Help".
|
|
|
|
Both features are currently optional, and might be removed in future versions.
|
|
|
|
===== HTML Help Compiler (hhc.exe)
|
|
|
|
This compiler is used to generate a .chm file from a bunch of HTML files -- in
|
|
our case to generate the User's and Developer's Guide in .chm format.
|
|
|
|
The compiler is only available as the free (as in beer) "HTML Help Workshop"
|
|
download. If you want to compile the guides yourself, you need to download and
|
|
install this. If you don't install it into the default directory, you may also
|
|
have a look at the HHC_DIR setting in the file docbook/Makefile.
|
|
|
|
===== HTML Help Build Files (htmlhelp.c / htmlhelp.lib)
|
|
|
|
The files 'htmlhelp.c' and 'htmlhelp.lib' are required to
|
|
be able to open .chm files from Wireshark and show the
|
|
online help. Both files are part of the SDK (standalone (P)SDK or MSVC
|
|
since 2002).
|
|
|
|
Simply set HHC_DIR in 'config.nmake' to use it.
|
|
|
|
[[ChToolsDebugger]]
|
|
|
|
==== Debugger
|
|
|
|
Using a good debugger can save you a lot of development time.
|
|
|
|
The debugger you use must match the C compiler Wireshark was compiled with,
|
|
otherwise the debugger will simply fail or you will only see a lot of garbage.
|
|
|
|
[[ChToolsMSVCDebugger]]
|
|
|
|
===== Visual Studio integrated debugger
|
|
|
|
You can use the integrated debugger of Visual Studio if your toolchain includes
|
|
it. As described on http://msdn.microsoft.com/en-us/library/0bxe8ytt.aspx[MSDN],
|
|
create an EXE project for your built copy,
|
|
i.e. C:\Development\Wireshark\wireshark-qt-release\Wireshark.exe, and then
|
|
start the debugger in the mormal way. To set a breakpoint, open the required
|
|
source file using the File -> Open -> File menu and set the breakpoint as normal.
|
|
|
|
The normal build is an optimised release version so debugging can be a bit
|
|
difficult as variables are optimised out into registers and the execution
|
|
order of statements can jump around.
|
|
|
|
If you require a non-optimised version, then edit config.nmake and replace the /O2
|
|
flag from LOCAL_CFLAGS with /Od, clean up the build (nmake -f Makefile.nmake clean)
|
|
and then rebuild.
|
|
|
|
[[ChToolsMSDebuggingTools]]
|
|
|
|
===== Debugging Tools for Windows
|
|
|
|
You can also use the Microsoft Debugging Tools for Windows toolkit, which is a
|
|
standalone GUI debugger. Although it's not that comfortable compared to
|
|
debugging with the Visual Studio integrated debugger it can be helpful if you
|
|
have to debug on a machine where an integrated debugger is not available.
|
|
|
|
You can get it free of charge from Microsoft in several ways, see the
|
|
http://msdn.microsoft.com/en-us/library/windows/hardware/ff551063%28v=vs.85%29.aspx)[Debugging tools for Windows] page.
|
|
|
|
You can also use Chocolatey to install WinDbg:
|
|
|
|
----
|
|
PS:\> cinst windbg
|
|
----
|
|
|
|
To debug Wireshark using WinDbg, open the built copy of Wireshark using
|
|
the File -> Open Executable... menu,
|
|
i.e. C:\Development\Wireshark\wireshark-qt-release\Wireshark.exe. To set a
|
|
breakpoint open the required source file using the File -> Open Source File...
|
|
menu and then click on the required line and press F9. To run the program,
|
|
press F5.
|
|
|
|
[[ChToolsBash]]
|
|
|
|
=== bash
|
|
|
|
The bash shell is needed to run several shell scripts.
|
|
|
|
[[ChToolsGNUBash]]
|
|
|
|
==== UNIX and Cygwin: GNU bash
|
|
|
|
The bash shell is available for most of the UNIX-like
|
|
platforms and as the bash package from the
|
|
<<ChToolsCygwin,Cygwin setup>>.
|
|
|
|
If bash isn't already installed or
|
|
available as a package for your platform, you can get it at
|
|
http://www.gnu.org/software/bash/bash.html[].
|
|
|
|
After correct installation, typing at the bash command line prompt:
|
|
|
|
----
|
|
$ bash --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
GNU bash, version 3.1.17(6)-release (i686-pc-cygwin)
|
|
Copyright (C) 2005 Free Software Foundation, Inc.
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
[[ChToolsWindowsBash]]
|
|
|
|
==== Windows native:
|
|
|
|
// MinGW? PowerShell?
|
|
****
|
|
This section not yet written
|
|
****
|
|
|
|
[[ChToolsPython]]
|
|
|
|
=== Python
|
|
|
|
Python is an interpreted programming language. The homepage of the Python
|
|
project is http://python.org/[]. It is used to generate some source files.
|
|
Python 2.5 or later (including Python 3) should work fine but Python 2.7 is
|
|
recommended.
|
|
|
|
Python is either included or available as a package on most UNIX-like platforms.
|
|
Windows packages and source are available at http://python.org/download/[].
|
|
The Cygwin Python package is *not* recommended since `/usr/bin/python` is
|
|
a symbolic link, which causes confusion outside Cygwin.
|
|
|
|
You can also use Chocolatey to install Python:
|
|
|
|
----
|
|
PS:\> cinst Python2
|
|
----
|
|
|
|
You can verify your Python version by running
|
|
|
|
----
|
|
$ python --version
|
|
----
|
|
|
|
on UNIX and Linux and
|
|
|
|
----
|
|
C:> cd python27
|
|
C:Python27> python --version
|
|
----
|
|
|
|
on Windows. You should see something like
|
|
|
|
----
|
|
Python 2.7.3
|
|
----
|
|
|
|
Your version string may vary of course.
|
|
|
|
[[ChToolsPerl]]
|
|
|
|
=== Perl
|
|
|
|
Perl is an interpreted programming language. The
|
|
homepage of the Perl project is
|
|
http://www.perl.com[]. Perl is used to convert
|
|
various text files into usable source code. Perl version 5.6
|
|
and above should work fine.
|
|
|
|
[[ChToolsUnixPerl]]
|
|
|
|
==== UNIX and Cygwin: Perl
|
|
|
|
Perl is available for most of the UNIX-like platforms
|
|
and as the perl package from the
|
|
<<ChToolsCygwin,Cygwin setup>>.
|
|
|
|
If perl isn't already installed or available
|
|
as a package for your platform, you can get it at
|
|
http://www.perl.com/[].
|
|
|
|
After correct installation, typing at the
|
|
bash command line prompt:
|
|
|
|
----
|
|
$ perl --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
This is perl, v5.8.7 built for cygwin-thread-multi-64int
|
|
(with 1 registered patch, see perl -V for more detail)
|
|
|
|
Copyright 1987-2005, Larry Wall
|
|
|
|
Perl may be copied only under the terms of either the Artistic License or the
|
|
GNU General Public License, which may be found in the Perl 5 source kit.
|
|
|
|
Complete documentation for Perl, including FAQ lists, should be found on
|
|
this system using `man perl' or `perldoc perl'. If you have access to the
|
|
Internet, point your browser at http://www.perl.com/, the Perl Home Page.
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
[[ChToolsWindowsPerl]]
|
|
|
|
==== Windows native: Perl
|
|
|
|
A native Windows Perl package can be obtained from
|
|
http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation
|
|
should be straightforward.
|
|
|
|
You may also use Chocolatey to install either package:
|
|
|
|
----
|
|
PS:\> cinst ActivePerl
|
|
----
|
|
|
|
or
|
|
|
|
----
|
|
PS:\> cinst StrawberryPerl
|
|
----
|
|
|
|
After correct installation, typing at the command
|
|
line prompt (cmd.exe):
|
|
|
|
----
|
|
> perl -v
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
This is perl, v5.8.0 built for MSWin32-x86-multi-thread
|
|
(with 1 registered patch, see perl -V for more detail)
|
|
|
|
Copyright 1987-2002, Larry Wall
|
|
|
|
Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
|
|
Built 18:08:02 Feb 4 2003
|
|
...
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
[[ChToolsSed]]
|
|
|
|
=== sed
|
|
|
|
Sed it the streaming editor. It makes it easy for example
|
|
to replace text inside a source code file.
|
|
The Wireshark build process uses this to stamp version strings
|
|
in various places.
|
|
|
|
[[ChToolsUnixSed]]
|
|
|
|
==== UNIX and Cygwin: sed
|
|
|
|
Sed is available for most of the UNIX-like platforms
|
|
and as the sed package from the
|
|
<<ChToolsCygwin,Cygwin setup>>.
|
|
|
|
If sed isn't already installed or available
|
|
as a package for your platform, you can get it at
|
|
http://directory.fsf.org/GNU/sed.html[]
|
|
|
|
After correct installation, typing at the
|
|
bash command line prompt:
|
|
|
|
----
|
|
$ sed --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
GNU sed version 4.1.5
|
|
Copyright (C) 2003 Free Software Foundation, Inc.
|
|
This is free software; see the source for copying conditions. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE,
|
|
to the extent permitted by law.
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
[[ChToolsWindowsSed]]
|
|
|
|
==== Windows native: sed
|
|
|
|
A native Windows sed package can be obtained from
|
|
http://gnuwin32.sourceforge.net/[]. The
|
|
installation should be straightforward.
|
|
|
|
[[ChToolsBison]]
|
|
|
|
=== Bison
|
|
|
|
Bison is a parser generator used for some of Wireshark's file format support.
|
|
|
|
[[ChToolsUnixBison]]
|
|
|
|
==== UNIX or Cygwin: bison
|
|
|
|
Bison is available for most UNIX-like platforms and as the bison package from
|
|
<<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
|
|
|
|
If GNU Bison isn't already installed or available as a package for your
|
|
platform you can get it at: http://www.gnu.org/software/bison/bison.html[].
|
|
|
|
After correct installation running the following
|
|
|
|
----
|
|
$ bison --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
bison (GNU Bison) 2.3
|
|
Written by Robert Corbett and Richard Stallman.
|
|
|
|
Copyright (C) 2006 Free Software Foundation, Inc.
|
|
This is free software; see the source for copying conditions. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
----
|
|
|
|
Your version string may vary.
|
|
|
|
[[ChToolsWindowsBison]]
|
|
|
|
==== Windows Native: Win flex-bison and bison
|
|
|
|
A native Windows version of bison is available in the _winflexbison_
|
|
https://chocolatey.org/[Chocolatey] package. Note that the executable is named
|
|
`win_bison`.
|
|
|
|
Native packages are available from other sources such as
|
|
http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin]. They aren't
|
|
officially supported but _should_ work.
|
|
|
|
[[ChToolsFlex]]
|
|
|
|
=== Flex
|
|
|
|
Flex is a lexical analyzer generator used for Wireshark's display filters, some
|
|
file formats, and other features.
|
|
|
|
[[ChToolsUnixFlex]]
|
|
|
|
==== UNIX or Cygwin: flex
|
|
|
|
Flex is available for most UNIX-like platforms and as the flex package from
|
|
<<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
|
|
|
|
If GNU flex isn't already installed or available as a package for your platform
|
|
you can get it at http://www.gnu.org/software/flex/[].
|
|
|
|
After correct installation running the following
|
|
|
|
----
|
|
$ flex --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
flex version 2.5.4
|
|
----
|
|
|
|
Your version string may vary.
|
|
|
|
[[ChToolsWindowsFlex]]
|
|
|
|
==== Windows Native: Win flex-bison and flex
|
|
|
|
A native Windows version of flex is available in the _winflexbison_
|
|
https://chocolatey.org/[Chocolatey] package. Note that the executable is named
|
|
`win_flex`.
|
|
|
|
----
|
|
PS:\>cinst winflexbison
|
|
----
|
|
|
|
Native packages are available from other sources such as
|
|
http://gnuwin32.sourceforge.net/packages/flex.htm[GnuWin]. They aren't
|
|
officially supported but _should_ work.
|
|
|
|
[[ChToolsGit]]
|
|
|
|
=== Git client
|
|
|
|
The Wireshark project uses its own Git repository
|
|
to keep track of all the changes done to the source
|
|
code. Details about the usage of Git in the Wireshark
|
|
project can be found in
|
|
<<ChSrcGitRepository>>.
|
|
|
|
If you want to work with the source code and are planning to
|
|
commit your changes back to the Wireshark community, it is
|
|
recommended to use a Git client to get the latest source files.
|
|
For detailed information about the different ways to obtain the
|
|
Wireshark sources, see
|
|
<<ChSrcObtain>>.
|
|
|
|
You will find more instructions in
|
|
<<ChSrcGit>> on how to use the Git
|
|
client.
|
|
|
|
[[ChToolsUnixGit]]
|
|
|
|
==== UNIX or Cygwin: git
|
|
|
|
Git is available for most of the UNIX-like platforms
|
|
and as the Git package from the
|
|
<<ChToolsCygwin,Cygwin setup>>
|
|
|
|
If Git isn't already installed or available as a package for your platform, you
|
|
can get it at: http://git-scm.com/[].
|
|
|
|
After correct installation, typing at the bash command line prompt:
|
|
|
|
----
|
|
$ git --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
git version 1.8.3.4
|
|
----
|
|
|
|
Your version will likely be different.
|
|
|
|
[[ChToolsWindowsGit]]
|
|
|
|
==== Windows native: git
|
|
|
|
The Git command line tools for Windows can be found at
|
|
http://git-scm.com/download/win[] and can also be installed using Chocolatey:
|
|
|
|
----
|
|
PS:\> cinst git
|
|
----
|
|
|
|
After correct installation, typing at the command
|
|
line prompt (cmd.exe):
|
|
|
|
----
|
|
$ git --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
git version 1.8.3.4
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
[[ChToolsGitPowerShellExtensions]]
|
|
|
|
=== Git Powershell Extensions (optional)
|
|
|
|
A useful tool for command line git on Windows is https://github.com/dahlbyk/posh-git[PoshGit].
|
|
Poshgit provides git command completion and alters the prompt to indicate the local working
|
|
copy status. You can install it using Chocolatey:
|
|
|
|
----
|
|
PS:\>cinst poshgit
|
|
----
|
|
|
|
[[ChToolsGitGUI]]
|
|
|
|
=== Git GUI client (optional)
|
|
|
|
Along with the traditional command-line client, several
|
|
GUI clients are available for a number of platforms. See
|
|
http://git-scm.com/downloads/guis[] for details.
|
|
|
|
// [[ChToolsUnixGitGUI]]
|
|
// XXX Add Gui client section
|
|
|
|
[[ChToolsPatch]]
|
|
|
|
=== patch (optional)
|
|
|
|
The patch utility is used to merge a diff file into your own source tree. This
|
|
tool is only needed, if you want to apply a patch (diff file) from someone else
|
|
(probably from the developer mailing list) to try out in your own private source
|
|
tree.
|
|
|
|
It most cases you may not need the patch tool installed. Git and Gerrit should
|
|
handle patches for you.
|
|
|
|
You will find more instructions in <<ChSrcPatchApply>>on how to use the patch
|
|
tool.
|
|
|
|
[[ChToolsUnixPatch]]
|
|
|
|
==== UNIX and Cygwin: patch
|
|
|
|
Patch is available for most of the UNIX-like platforms
|
|
and as the patch package from the
|
|
<<ChToolsCygwin,Cygwin setup>>.
|
|
|
|
If GNU patch isn't already installed or
|
|
available as a package for your platform, you can get it at
|
|
http://www.gnu.org/software/patch/patch.html[].
|
|
|
|
After correct installation, typing at the
|
|
bash command line prompt:
|
|
|
|
----
|
|
$ patch --version
|
|
----
|
|
|
|
should result in something like:
|
|
|
|
----
|
|
patch 2.5.8
|
|
Copyright (C) 1988 Larry Wall
|
|
Copyright (C) 2002 Free Software Foundation, Inc.
|
|
|
|
This program comes with NO WARRANTY, to the extent permitted by law.
|
|
You may redistribute copies of this program
|
|
under the terms of the GNU General Public License.
|
|
For more information about these matters, see the file named COPYING.
|
|
|
|
written by Larry Wall and Paul Eggert
|
|
----
|
|
|
|
However, the version string may vary.
|
|
|
|
[[ChToolsWindowsPatch]]
|
|
|
|
==== Windows native: patch
|
|
|
|
The Windows native Git tools provide patch. A native Windows patch package can be obtained from
|
|
http://gnuwin32.sourceforge.net/[]. The
|
|
installation should be straightforward.
|
|
|
|
[[ChToolsWget]]
|
|
|
|
=== Windows: GNU wget (optional)
|
|
|
|
GNU wget is used to download files from the internet using the command line.
|
|
|
|
GNU wget is available for most of the UNIX-like platforms and as the wget
|
|
package from the <<ChToolsCygwin,Cygwin setup>> and also using Chocolatey:
|
|
|
|
----
|
|
PS$> cinst Wget
|
|
----
|
|
|
|
You will only need wget, if you want to use the Windows automated library
|
|
download, see <<ChLibsSetup>>for details.
|
|
|
|
If GNU wget isn't already installed or available as a package for your platform
|
|
(well, for Windows it is available as a Cygwin package), you can get it at
|
|
http://www.gnu.org/software/wget/wget.html[].
|
|
|
|
If wget is trying to download files but fails to do so, your Internet connection
|
|
might use an HTTP proxy. Some Internet providers use such a proxy and it is
|
|
common in many company networks today. Wireshark's setup script will try to
|
|
discover your proxy settings automatically, but you may need to set the
|
|
environment variable 'HTTP_PROXY' by hand before using wget. For example, if you
|
|
are behind proxy.com which is listening on port 8080, you have to set it to
|
|
something like:
|
|
|
|
----
|
|
set HTTP_PROXY=http://proxy.com:8080/
|
|
----
|
|
|
|
If you are unsure about the settings, you might ask your system administrator.
|
|
|
|
[[ChToolsUnzip]]
|
|
|
|
=== Windows: GNU unzip (optional)
|
|
|
|
GNU unzip is used to, well, unzip the zip files downloaded using the wget tool.
|
|
|
|
GNU unzip is available for most of the UNIX-like platforms and as the unzip
|
|
package from the <<ChToolsCygwin,Cygwin setup>>.
|
|
|
|
You will only need unzip, if you want to use the Windows automated library
|
|
download, see <<ChLibsSetup>>for details.
|
|
|
|
If GNU unzip isn't already installed or available as a package for your platform
|
|
(well, for Windows it is available as a Cygwin package), you can get it at
|
|
http://gnuwin32.sourceforge.net/packages/unzip.htm[].
|
|
|
|
[[ChToolsNSIS]]
|
|
|
|
=== Windows: NSIS (optional)
|
|
|
|
The NSIS (Nullsoft Scriptable Install System) is used to generate
|
|
'wireshark-win32-wireshark-major-minor-version:[].x.exe' from all the files
|
|
needed to be installed, including all required DLLs, plugins, and supporting
|
|
files.
|
|
|
|
To install it, simply download the latest released version (currently 2.46)
|
|
from http://nsis.sourceforge.net[] and start the downloaded installer. You will
|
|
need NSIS version 2. Version 3 is not yet supported.
|
|
|
|
You can find more instructions on using NSIS in <<ChSrcNSIS>>.
|
|
|
|
=== Windows: PortableApps (optional)
|
|
|
|
The PortableApps.com Installer is used to generate
|
|
'WiresharkPortable-wireshark-major-minor-version:[].paf.exe' from all the files
|
|
needed to be installed, including all required DLLs, plugins, and supporting
|
|
files.
|
|
|
|
To install it, do the following:
|
|
|
|
* Download the latest PortableApps.com Platform release from
|
|
http://portableapps.com/[]. `config.nmake` uses the ``Local
|
|
All Users'' install location (`C:`) by default.
|
|
|
|
* Install the following applications in the PortableApps.com environment:
|
|
|
|
** PortableApps.com Installer
|
|
|
|
** PortableApps.com Launcher
|
|
|
|
** NSIS Portable (Unicode)
|
|
|
|
** PortableApps.com AppCompactor
|
|
|
|
You can find more instructions on using the PortableApps.com Installer in
|
|
<<ChSrcPortableApps>>.
|
|
|
|
++++++++++++++++++++++++++++++++++++++
|
|
<!-- End of WSDG Chapter Tools -->
|
|
++++++++++++++++++++++++++++++++++++++
|
|
|
|
// vim: set syntax=asciidoc:
|