1189 lines
34 KiB
Plaintext
1189 lines
34 KiB
Plaintext
++++++++++++++++++++++++++++++++++++++
|
|
<!-- 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.
|
|
Alternatively you can install Cygwin and its packages using Chocolatey.
|
|
|
|
==== Installing Cygwin using the Cygwin installer
|
|
|
|
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.
|
|
|
|
All tools will be installed into one base folder. The default is
|
|
'C:\cygwin'.
|
|
|
|
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.
|
|
|
|
==== Installing Cygwin using Chocolatey
|
|
|
|
Chocolatey supports Cygwin as an external package source.
|
|
To install Cygwin itself run
|
|
|
|
----
|
|
PS$>choco install cygwin
|
|
# You might also need to install cyg-get:
|
|
PS$>choco install cyg-get
|
|
----
|
|
|
|
Chocolatey installs Cygwin in 'C:\tools\cygwin' by default.
|
|
|
|
One or more Cygwin packages can be installed using "cyg-get":
|
|
|
|
----
|
|
PS$>cyg-get sed asciidoc
|
|
----
|
|
|
|
[[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`)
|
|
|
|
. 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 2.0.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
|
|
|
|
CMake Generator: `Visual Studio 12`
|
|
|
|
.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.
|
|
|
|
CMake Generator: `Visual Studio 10`
|
|
|
|
Remarks:: Installers created using express editions require a $$C++$$ redistributable
|
|
'$$vcredist_x86.exe$$' (3MB free
|
|
download) is required to build
|
|
Wireshark-win32-{wireshark-version}.exe, and
|
|
'$$vcredist_x64.exe$$' is required to build
|
|
Wireshark-win64-{wireshark-version}.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
|
|
|
|
CMake Generator: `Visual Studio 10`
|
|
|
|
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:\> choco install 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]
|
|
|
|
==== 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_BASE_DIR or WIRESHARK_LIB_DIR environment variables.
|
|
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).
|
|
|
|
[[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. Open the solution in your build directory and build and debug as normal
|
|
with a Visual Studio solution.
|
|
|
|
To set the correct paths for Visual Studio when running Wireshark under the
|
|
debugger, add the build output directory to the path before opening Visual
|
|
Studio from the same command prompt, e.g.
|
|
|
|
----
|
|
C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo"
|
|
C:\Development\wsbuild32>wireshark.sln
|
|
----
|
|
|
|
for PowerShell use
|
|
|
|
----
|
|
PS C:\Development\wsbuild32>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)"
|
|
PS C:\Development\wsbuild32>wireshark.sln
|
|
----
|
|
|
|
When Visual Studio has finished loading the solution, set the executable to
|
|
be run in the debugger, e.g. Executables\Wireshark, by right clicking it in
|
|
the Solution Explorer window and selecting "Set as StartUp Project". Also
|
|
set the Solution Configuration (usually RelWithDebInfo) from the droplist on
|
|
the toolbar.
|
|
|
|
NOTE: Currently Visual Studio regards a command line build as incomplete, so
|
|
will report that some items need to be built when starting the debugger. These
|
|
can either be rebuilt or ignored as you wish.
|
|
|
|
|
|
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 build using a debug configuration.
|
|
|
|
[[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:\> choco install windbg
|
|
----
|
|
|
|
To debug Wireshark using WinDbg, open the built copy of Wireshark using
|
|
the File -> Open Executable... menu,
|
|
i.e. C:\Development\wsbuild32\run\RelWithDebInfo\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.
|
|
|
|
If you require a non-optimised version, then build using a debug configuration, e.g.
|
|
`msbuild /m /p:Configuration=Debug Wireshark.sln`. The build products will be found
|
|
in C:\Development\wsbuild32\run\Debug\.
|
|
|
|
[[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 and Python 3.5 and
|
|
2.7 are 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:\> choco install Python3
|
|
----
|
|
|
|
or
|
|
|
|
----
|
|
PS:\> choco install Python2
|
|
----
|
|
|
|
Chocolatey installs Python into 'C:\tools\python3' or 'C:\tools\python2' by
|
|
default. You can verify your Python version by running
|
|
|
|
----
|
|
$ python --version
|
|
----
|
|
|
|
on UNIX and Linux and
|
|
|
|
----
|
|
rem Official package
|
|
C:> cd python35
|
|
C:Python35> python --version
|
|
|
|
rem Chocolatey
|
|
C:> cd \tools\python3
|
|
C:\tools\python3> python --version
|
|
----
|
|
|
|
on Windows. You should see something like
|
|
|
|
----
|
|
Python 3.5.1
|
|
----
|
|
|
|
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:\> choco install ActivePerl
|
|
//----
|
|
//
|
|
//or
|
|
//
|
|
//----
|
|
//PS:\> choco install 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>>. It is also available via Chocolatey:
|
|
|
|
// XXX Is sed part of the base Cygwin install?
|
|
|
|
----
|
|
PS$>cyg-get sed
|
|
----
|
|
|
|
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. A Chocolatey package
|
|
(devbox-sed) is available but has not been tested.
|
|
|
|
[[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:\>choco install 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:\> choco install 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:\>choco install 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.
|
|
|
|
[[ChToolsNSIS]]
|
|
|
|
=== Windows: NSIS (optional)
|
|
|
|
The NSIS (Nullsoft Scriptable Install System) is used to generate
|
|
'Wireshark-win32-{wireshark-version}.exe' from all the files
|
|
needed to be installed, including all required DLLs, plugins, and supporting
|
|
files.
|
|
|
|
To install it, 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 also install it
|
|
using Chocolatey:
|
|
|
|
----
|
|
PS$> choco install nsis
|
|
----
|
|
|
|
You can find more instructions on using NSIS in <<ChSrcNSIS>>.
|
|
|
|
=== Windows: PortableApps (optional)
|
|
|
|
The PortableApps.com Installer is used to generate
|
|
'WiresharkPortable-{wireshark-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/[].
|
|
|
|
* 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:
|