forked from osmocom/wireshark
1255 lines
37 KiB
Plaintext
1255 lines
37 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>>.
|
||
|
||
=== 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 Command Prompt:
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))
|
||
----
|
||
|
||
Chocolatey sometimes installs packages in unexpected locations. Cygwin is a notable
|
||
example -- recent versions of the Cygwin package are installed in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ instead of Cygwin’s default location
|
||
(_C:\cygwin_ or _C:\cygwin64_).
|
||
|
||
[[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.
|
||
|
||
Over time the Wireshark development toolchain has been migrating away from Cygwin
|
||
toward native tools and we hope to eliminate it as a requirement someday.
|
||
|
||
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.
|
||
You can install Cygwin and its packages using Chocolatey, but this is not
|
||
recommended due to Chocolatey’s default installation location, described
|
||
in the previous section.
|
||
|
||
==== 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_ for the 32-bit installer and _C:\cygwin64_ for the 64-bit
|
||
installer.
|
||
|
||
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 menu: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 Prompt
|
||
(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
|
||
|
||
[source,cmd]
|
||
----
|
||
PS$>choco install cygwin
|
||
# You might also need to install cyg-get:
|
||
PS$>choco install cyg-get
|
||
----
|
||
|
||
Chocolatey installs Cygwin in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ by default.
|
||
|
||
One or more Cygwin packages can be installed using `cyg-get`:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS$>cyg-get sed asciidoc
|
||
----
|
||
|
||
[[ChToolsCMake]]
|
||
|
||
=== CMake
|
||
|
||
Wireshark’s build environment can be configured using CMake on Windows,
|
||
Linux, macOS, and UNIX. CMake is designed to support out of tree builds.
|
||
So much so, that in tree builds do not work properly in all cases. Along
|
||
with being cross-platform, CMake supports many build tools and
|
||
environments including traditional make, Ninja, and MSBuild. Our
|
||
Buildbot runs CMake steps on Ubuntu, Win32, Win64, and macOS. In
|
||
particular, the macOS and Windows packages are built using CMake.
|
||
|
||
Building with CMake typically includes creating a build directory and
|
||
specifying a *generator*, aka a build tool. For example, to build
|
||
Wireshark using Ninja in the directory _wireshark-ninja_ you might
|
||
run the following commands:
|
||
|
||
[source,sh]
|
||
----
|
||
# Starting from your Wireshark source directory, create a build directory
|
||
# alongside it.
|
||
$ cd ..
|
||
$ mkdir wireshark-ninja
|
||
$ cd wireshark-ninja
|
||
# Assumes your source directory is named "wireshark".
|
||
$ cmake -G Ninja ../wireshark
|
||
$ ninja (or cmake --build .)
|
||
----
|
||
|
||
Using CMake on Windows is described further in <<ChWin32Generate>>.
|
||
|
||
Along with specifying a generator with the `-G` flag you can set variables
|
||
using the `-D` flag. Useful variables and generators include the following:
|
||
|
||
-DBUILD_wireshark=OFF:: Don't build the Wireshark GUI application.
|
||
Each command line utility has its own BUILD_xxx flag as well. For
|
||
example, you can use -DBUILD_mmdbresolve=OFF to disable mmdbresolve.
|
||
|
||
-DENABLE_CAP=OFF:: Disable the POSIX capabilities check
|
||
|
||
-DCMAKE_BUILD_TYPE=Debug:: Enable debugging symbols
|
||
|
||
-DCARES_INCLUDE_DIR=/your/custom/cares/include, -DCARES_LIBRARY=/your/custom/cares/lib/libcares.so::
|
||
Let you set the path to a locally-compiled version of c-ares. Most
|
||
optional libraries have xxx_INCLUDE_DIR and xxx_LIB flags that let you
|
||
control their discovery.
|
||
|
||
|
||
-DPYTHON_EXECUTABLE=c:/Python27/python:: Force the Python path. Useful on Windows since Cygwin’s /usrbin/python is a symlink.
|
||
|
||
-DENABLE_APPLICATION_BUNDLE=OFF:: Disable building an application bundle (Wireshark.app) on macOS
|
||
|
||
You can list all build variables (with help) by running `cmake -LH [options]
|
||
../<Name_of_WS_source_dir>`. This lists the cache of build variables
|
||
after the cmake run. To only view the current cache, add option `-N`.
|
||
|
||
After running cmake, you can always run `make help` to see a list of all possible make targets.
|
||
|
||
Note that CMake honors user umask for creating directories as of now. You should set
|
||
the umask explicitly before running the `install` target.
|
||
|
||
CMake links:
|
||
|
||
The home page of the CMake project: https://cmake.org/
|
||
|
||
Official documentation: https://cmake.org/documentation/
|
||
|
||
About CMake in general and why KDE4 uses it: http://lwn.net/Articles/188693/
|
||
|
||
Introductory tutorial/presentation:
|
||
http://ait.web.psi.ch/services/linux/hpc/hpc_user_cookbook/tools/cmake/docs/Cmake_VM_2007.pdf
|
||
|
||
Introductory article in the Linux Journal:
|
||
http://www.linuxjournal.com/node/6700/print
|
||
|
||
Useful variables: http://www.cmake.org/Wiki/CMake_Useful_Variables
|
||
|
||
Frequently Asked Questions: http://www.cmake.org/Wiki/CMake_FAQ
|
||
|
||
// 2017-08-04 dead
|
||
//Additional cmake modules: http://code.google.com/p/cmake-modules/
|
||
|
||
[[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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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/{cpp}
|
||
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_)
|
||
|
||
. Resource Compiler (_rc.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_)
|
||
|
||
==== Official Toolchain Packages And Alternatives
|
||
|
||
The official Wireshark 2.4.x releases are compiled using Microsoft Visual {cpp} 2015.
|
||
The Wireshark 2.2.x and 2.0.x releases are compiled using Microsoft Visual {cpp} 2013.
|
||
The Wireshark 1.12.x and 1.10.x releases were compiled using
|
||
Microsoft Visual {cpp} 2010 SP1.
|
||
The 1.8 releases were compiled using
|
||
Microsoft Visual {cpp} 2010 SP1 as well.
|
||
The 1.6, 1.4, and 1.2 releases were compiled using
|
||
Microsoft Visual {cpp} 2008 SP1.
|
||
Other past releases, including the 1.0 branch,
|
||
were compiled using Microsoft Visual {cpp} 6.0.
|
||
|
||
Using the release compilers is recommended for Wireshark development work.
|
||
|
||
The older "Express
|
||
Edition" compilers such as Visual {cpp} 2010 Express Edition SP1 can be
|
||
used but any PortableApps packages you create with them
|
||
will require the installation of a separate Visual {cpp}
|
||
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 {cpp} compiler
|
||
installed. It should be possible to use any of the following with the considerations listed:
|
||
|
||
.Visual {cpp} 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 {cpp} 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 {cpp} 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 {cpp} redistributable
|
||
(_vcredist_x86.exe_).footnoteref[vcredist]
|
||
|
||
You can use Chocolatey to install Visual Studio, e.g:
|
||
|
||
[source,cmd]
|
||
----
|
||
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 2015|14.0|1900|msvcr140.dll
|
||
|Visual Studio 2013|12.0|1800|msvcr120.dll
|
||
|Visual Studio 2012|11.0|1700|msvcr110.dll
|
||
|Visual Studio 2010|10.0|1600|msvcr100.dll
|
||
|===============
|
||
|
||
After correct installation of the toolchain, typing
|
||
at the Visual Studio Command line prompt (cmd.exe):
|
||
|
||
[source,cmd]
|
||
----
|
||
> cl
|
||
----
|
||
|
||
should result in something like:
|
||
|
||
----
|
||
Microsoft (R) C/{cpp} 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):
|
||
|
||
[source,cmd]
|
||
----
|
||
> 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 {cpp} 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 {cpp} Redistributable Merge Modules._
|
||
(Loadable modules for building msi installers.
|
||
Not suitable for Wireshark’s NSIS based installer)
|
||
|
||
. _Install a particular Visual {cpp} 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{cpp} 2012 Express, V{cpp} 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.
|
||
|
||
=== Documentation Toolchain
|
||
|
||
Wireshark’s documentation is split across two directories. The `doc`
|
||
directory contains man pages written in Perl’s POD (Plain Old
|
||
Documentation) format. The `docbook` directory contains the User’s
|
||
Guide, Developer’s Guide, and the release notes, which are written in
|
||
Asciidoctor markup.
|
||
|
||
Our various output formats are generated using the following tools.
|
||
Intermediate formats are in _italics_.
|
||
|
||
Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
|
||
Guide PDF:: Asciidoctor
|
||
Guide HTML Help:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL → HHC
|
||
|
||
Release notes HTML:: Asciidoctor
|
||
Release notes text:: Asciidoctor → _HTML_ → html2text.py
|
||
|
||
==== Asciidoctor
|
||
|
||
Asciidoctor[https://asciidoctor.org/] comes in several flavors: a Ruby
|
||
gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled
|
||
JavaScript (Asciidoctor.js). Only the Asciidoctor and AsciidoctorJ
|
||
flavors are supported for building the Wireshark documentation and
|
||
AsciidoctorJ is recommended.
|
||
|
||
The guides and release notes were originally written in DocBook (hence
|
||
the directory name). They were later converted to AsciiDoc and then
|
||
migrated to Asciidoctor.
|
||
`compat-mode`[https://asciidoctor.org/docs/migration/] is currently
|
||
enabled for the guides, but we are steadily migrating to Asciidoctor’s
|
||
modern (>= 1.5.0) syntax.
|
||
|
||
PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ
|
||
but _not_ with Asciidoctor.
|
||
|
||
==== Xsltproc And DocBook
|
||
|
||
The single HTML, chunked HTML, and HTML Help guides are generated using
|
||
DocBook XSL stylesheets. They in turn require an XSLT processor. We use
|
||
`xsltproc`.
|
||
|
||
==== HTML Help
|
||
|
||
HTML Help is used to create the User’s and Developer’s Guide in .chm format.
|
||
The User’s Guide .chm file is included with the NSIS and WiX installers and
|
||
is used as Wireshark's built-in help on Windows.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
[source,cmd]
|
||
----
|
||
C:\Development\wsbuild32>set PATH="%PATH%;C:\Development\wsbuild32\run\RelwithDebInfo"
|
||
C:\Development\wsbuild32>wireshark.sln
|
||
----
|
||
|
||
for PowerShell use
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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]]
|
||
|
||
[[ChToolsPython]]
|
||
|
||
=== Python
|
||
|
||
http://python.org/[Python] is an interpreted programming language. It is
|
||
used to generate some source files, documenation, and other tasks.
|
||
Python 2.5 or later (including Python 3) should work fine and Python 3.5 and
|
||
2.7 are recommended. If you're building documentation you must have Python
|
||
2 installed since AsciiDoc doesn't support Python 3.
|
||
|
||
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:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\> choco install Python3
|
||
----
|
||
|
||
or
|
||
|
||
[source,cmd]
|
||
----
|
||
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
|
||
|
||
[source,sh]
|
||
----
|
||
$ python --version
|
||
----
|
||
|
||
on UNIX and Linux and
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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.
|
||
|
||
// Sed is no longer required.
|
||
//[[ChToolsSed]]
|
||
|
||
[[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
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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_.
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ git --version
|
||
----
|
||
|
||
should result in something like:
|
||
|
||
----
|
||
git version 2.14.1
|
||
----
|
||
|
||
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:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\> choco install git
|
||
----
|
||
|
||
After correct installation, typing at the command
|
||
line prompt (cmd.exe):
|
||
|
||
[source,cmd]
|
||
----
|
||
> git --version
|
||
----
|
||
|
||
should result in something like:
|
||
|
||
----
|
||
git version 2.16.1.windows.1
|
||
----
|
||
|
||
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:
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|
||
|
||
[source,sh]
|
||
----
|
||
$ 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 from
|
||
http://nsis.sourceforge.net[]. NSIS v3 is required. You can also install
|
||
it using Chocolatey:
|
||
|
||
[source,cmd]
|
||
----
|
||
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:
|