forked from osmocom/wireshark
1052 lines
31 KiB
Plaintext
1052 lines
31 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 or UNIX-like platforms such
|
||
as Linux, but Windows ports are also available. Therefore the tools are
|
||
available in different "flavours":
|
||
|
||
* UNIX and UNIX-like platforms: The tools should be commonly available
|
||
on the supported UNIX and UNIX-like platforms. Cygwin is unsupported.
|
||
* 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 https://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>>.
|
||
|
||
[#ChToolsChocolatey]
|
||
=== 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 https://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. Python
|
||
is a notable example. While it's typically installed in a top-level
|
||
directory, e.g. _C:\Python37_ or in %PROGRAMFILES%, e.g. _C:\Program
|
||
Files\Python37_, Chocolatey tends to install it under
|
||
_C:\ProgramData\chocolatey_ or _C:\Tools_. If you want to avoid this
|
||
behavior you'll probably want to install Python using the packages from
|
||
python.org.
|
||
|
||
Other package managers for Windows include the https://docs.microsoft.com/en-us/windows/package-manager/[Windows Package Manager (winget)] and https://scoop.sh/[Scoop].
|
||
As of January 2022 neither option provides all of the packages we require, but that might change in the future.
|
||
|
||
[#ChToolsCMake]
|
||
|
||
=== CMake
|
||
|
||
Wireshark’s build environment can be configured using CMake on various UNIX-like platforms, including Linux, macOS, and *BSD, and on Windows.
|
||
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.
|
||
|
||
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 <<ChWindowsGenerate>>.
|
||
|
||
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_CCACHE=ON:: Build using the ccache compiler cache.
|
||
|
||
-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.
|
||
|
||
-DCMAKE_OSX_DEPLOYMENT_TARGET=10.12::
|
||
Specify the minimum macOS version for Wireshark and each command line utility.
|
||
Note that this doesn’t affect the minimum target for third-party libraries.
|
||
For example, if you’re building for macOS 10.12 you’ll need to install https://doc.qt.io/archives/qt-5.13/supported-platforms.html[Qt 5.14 or earlier] and ensure that other libraries support macOS 10.12, for example by running `tools/macos-setup.sh -t 10.12`.
|
||
|
||
-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`.
|
||
|
||
Depending on your needs, it might be useful to save your CMake configuration options in a file outside your build directory.
|
||
CMake supports this via its https://cmake.org/cmake/help/v3.23/manual/cmake-presets.7.html[presets] option.
|
||
For example, adding the follwing to `CMakeUserPresets.json` would let you build using Ninja in the `build` directory, enable ccache, and set a custom Qt directory by running `cmake --preset mydev`:
|
||
|
||
[source,json]
|
||
----
|
||
{
|
||
"version: 4,
|
||
"configurePresets": [
|
||
{
|
||
"name": "mydev",
|
||
"displayName": "Local development",
|
||
"generator": "Ninja",
|
||
"binaryDir": "${sourceDir}/build",
|
||
"cacheVariables": {
|
||
"ENABLE_CCACHE": "ON",
|
||
},
|
||
"environment": {
|
||
"CMAKE_PREFIX_PATH": "/usr/local/Qt6"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
----
|
||
|
||
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: https://lwn.net/Articles/188693/
|
||
|
||
Useful variables: https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/Useful-Variables
|
||
|
||
Frequently Asked Questions: https://gitlab.kitware.com/cmake/community/wikis/FAQ
|
||
|
||
[#ChToolsGNUChain]
|
||
|
||
=== GNU Compiler Toolchain (UNIX And UNIX-like Platforms)
|
||
|
||
[#ChToolsGCC]
|
||
|
||
==== gcc (GNU Compiler Collection)
|
||
|
||
The GCC C compiler is available for most UNIX and UNIX-like operating
|
||
systems.
|
||
|
||
If GCC isn't already installed or available
|
||
as a package for your platform, you can get it at:
|
||
https://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, many
|
||
https://sourceware.org/gdb/wiki/GDB%20Front%20Ends[GUI frontends for it
|
||
available], including Qt Creator, CLion, and Eclipse.
|
||
|
||
If gdb isn't already installed or available
|
||
as a package for your platform, you can get it at:
|
||
https://www.gnu.org/software/gdb/gdb.html[].
|
||
|
||
After correct installation:
|
||
|
||
[source,sh]
|
||
----
|
||
$ gdb --version
|
||
----
|
||
|
||
should result in something like:
|
||
|
||
----
|
||
GNU gdb (GDB) 8.3
|
||
Copyright (C) 2019 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.
|
||
----
|
||
|
||
Your version string may vary, of course.
|
||
|
||
[#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:
|
||
https://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.
|
||
|
||
==== Ninja
|
||
|
||
Ninja is an alternative to make, and is available for many of the
|
||
UNIX-like platforms. It runs builds faster than make does.
|
||
|
||
It is designed to have its build files generated by tools such as CMake;
|
||
to generate build files for Ninja, run CMake with the `-G Ninja` flag.
|
||
|
||
If Ninja isn't already installed, see the list of suggestions for Ninja
|
||
packages at:
|
||
https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages.
|
||
|
||
If Ninja isn't already installed and isn't
|
||
available as a package for your platform, you can get it from:
|
||
https://ninja-build.org. You can download the source code or binaries
|
||
for Linux, macOS, and Windows (we have not tested Ninja on Windows).
|
||
|
||
[#ChToolsMSChain]
|
||
|
||
=== Microsoft compiler toolchain (Windows native)
|
||
|
||
To compile Wireshark on Windows using the Microsoft C/{cpp}
|
||
compiler (MSVC), 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_, _vcruntime140.lib_)
|
||
|
||
. Windows platform headers and libraries (e.g.
|
||
_windows.h_, _WS2_32.lib_)
|
||
|
||
==== Official Toolchain Packages And Alternatives
|
||
|
||
Official releases are or were built with the following Visual {cpp} versions:
|
||
|
||
// * Wireshark 4.0.x: Microsoft Visual {cpp} 2022.
|
||
* Wireshark 3.6.x: Microsoft Visual {cpp} 2019.
|
||
* Wireshark 3.4.x: Microsoft Visual {cpp} 2019.
|
||
* Wireshark 3.2.x: Microsoft Visual {cpp} 2019.
|
||
* Wireshark 3.0.x: Microsoft Visual {cpp} 2017.
|
||
* Wireshark 2.6.x: Microsoft Visual {cpp} 2017.
|
||
* Wireshark 2.4.x: Microsoft Visual {cpp} 2015.
|
||
* Wireshark 2.2.x: Microsoft Visual {cpp} 2013.
|
||
* Wireshark 2.0.x: Microsoft Visual {cpp} 2013.
|
||
* Wireshark 1.12.x: Microsoft Visual {cpp} 2010 SP1.
|
||
* Wireshark 1.10.x: Microsoft Visual {cpp} 2010 SP1.
|
||
* Wireshark 1.8.x: Microsoft Visual {cpp} 2010 SP1.
|
||
* Wireshark 1.6.x: Microsoft Visual {cpp} 2008 SP1.
|
||
* Wireshark 1.4.x: Microsoft Visual {cpp} 2008 SP1.
|
||
* Wireshark 1.2.x: Microsoft Visual {cpp} 2008 SP1.
|
||
* Wireshark 1.0.x and earlier: Microsoft Visual {cpp} 6.0.
|
||
|
||
Using the release compilers is recommended for Wireshark development work.
|
||
|
||
“Community” editions of Visual Studio such as “Visual Studio Community
|
||
2022” can be used to compile Wireshark but any PortableApps packages you
|
||
create with them might 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. You will need to sign up for a
|
||
https://visualstudio.microsoft.com/dev-essentials/[Visual Studio Dev
|
||
Essentials] account if you don't have a Visual Studio (MSDN)
|
||
subscription. The older versions can be downloaded from
|
||
https://visualstudio.microsoft.com/vs/older-downloads/[].
|
||
|
||
==== Visual {cpp} 2022 Community Edition
|
||
|
||
IDE + Debugger?:: Yes
|
||
|
||
SDK required for 64-bit builds?:: No
|
||
|
||
CMake Generator: *`Visual Studio 17`*
|
||
|
||
You can use Chocolatey to install Visual Studio, e.g:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\> choco install visualstudiocommunity2022 visualstudio2022-workload-nativedesktop
|
||
----
|
||
|
||
==== Visual {cpp} 2019 Community Edition
|
||
|
||
IDE + Debugger?:: Yes
|
||
|
||
SDK required for 64-bit builds?:: No
|
||
|
||
CMake Generator: *`Visual Studio 16`*
|
||
|
||
You can use Chocolatey to install Visual Studio, e.g:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\> choco install visualstudiocommunity2019 visualstudio2019-workload-nativedesktop
|
||
----
|
||
|
||
==== 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
|
||
| Visual Studio 2019 | 16.0.0 | 1920
|
||
| Visual Studio 2019 | 16.1.2 | 1921
|
||
| Visual Studio 2019 | 16.2.3 | 1922
|
||
| Visual Studio 2019 | 16.3.2 | 1923
|
||
| Visual Studio 2022 | 17.0 | 1930
|
||
| Visual Studio 2022 | 17.1 | 1931
|
||
|===
|
||
|
||
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/C++ Optimizing Compiler Version 19.23.28106.4 for x64
|
||
Copyright (C) Microsoft Corporation. All rights reserved.
|
||
|
||
usage: cl [ option... ] filename... [ /link linkoption... ]
|
||
----
|
||
|
||
However, the version string may vary.
|
||
|
||
Documentation on recent versions of the compiler can be found at
|
||
https://docs.microsoft.com/en-us/cpp/build/reference/compiling-a-c-cpp-program[Microsoft Docs]
|
||
|
||
==== 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 14.23.28106.4
|
||
Copyright (C) Microsoft Corporation. All rights reserved.
|
||
|
||
usage: LINK [options] [files] [@commandfile]
|
||
...
|
||
----
|
||
|
||
However, the version string may vary.
|
||
|
||
Documentation on recent versions of the linker can be found at
|
||
https://docs.microsoft.com/en-us/cpp/build/reference/linking[Microsoft Docs]
|
||
|
||
[#msvc-runtime-redistributable]
|
||
|
||
==== Visual {cpp} 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.
|
||
|
||
Wireshark and its libraries depend on POSIX functions such as fopen()
|
||
and malloc(). On Windows, these functions are provided by the Microsoft
|
||
Visual {cpp} C Runtime (CRT). There are many different versions of the CRT and
|
||
Visual {cpp} 2015 and later use the _Universal CRT_ (UCRT).
|
||
|
||
The Universal CRT comes standard with Windows 10 and is installed as part
|
||
of Windows Update on earlier versions of Windows. The Wireshark .exe
|
||
installers include redistributables (_vc_redist.x64.exe_ or
|
||
_vc_redist.x86.exe_) which ensure that the Universal CRT is installed and
|
||
up to date.
|
||
|
||
[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 Microsoft Docs link is recommended for the
|
||
interested reader:
|
||
|
||
https://docs.microsoft.com/en-us/cpp/windows/redistributing-visual-cpp-files[Redistributing Visual {cpp} Files]
|
||
|
||
In all cases where _vc_redist.x64.exe_ or _vc_redist.x86.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.
|
||
|
||
==== 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 SDKs 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.
|
||
|
||
[#ChToolsDocumentationToolchain]
|
||
=== Documentation Toolchain
|
||
|
||
Wireshark’s documentation is split across two directories.
|
||
The `doc` directory contains man pages written in Asciidoctor markup.
|
||
The `docbook` directory contains the User’s Guide, Developer’s Guide, and the release notes, which are also written in Asciidoctor markup.
|
||
The split is for historical reasons (described below), and the documentation will likely be consolidated into one directory in the future.
|
||
|
||
Our various output formats are generated using the following tools.
|
||
Intermediate formats are in _italics_.
|
||
|
||
Man page roff:: Asciidoctor
|
||
Man page HTML:: Asciidoctor
|
||
|
||
Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
|
||
Guide PDF:: Asciidoctor
|
||
|
||
Release notes HTML:: Asciidoctor
|
||
Release notes text:: Asciidoctor → _HTML_ → html2text.py
|
||
|
||
==== Asciidoctor
|
||
|
||
https://asciidoctor.org/[Asciidoctor] comes in several flavors: a Ruby gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled JavaScript (Asciidoctor.js).
|
||
The Ruby and Java flavors can be used to build Wireshark’s documentation, but the JavaScript flavor doesn’t support all of the features that we require.
|
||
// We need docbook5, PDF & EPUB output and macros
|
||
|
||
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.
|
||
The man pages were originally in Perl’s POD (Plain Old Documentation) format and were later converted to Asciidoctor.
|
||
We use Asciidoctor’s modern (>= 1.5.0) syntax.
|
||
|
||
PDF output requires Asciidoctor’s PDF backend.
|
||
It is included with AsciidoctorJ but _not_ with Asciidoctor.
|
||
|
||
==== DocBook XML and XSL
|
||
|
||
Converting from DocBook to HTML requires the DocBook DTD
|
||
(http://www.sagehill.net/docbookxsl/ToolsSetup.html)
|
||
and DocBook stylesheets
|
||
(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
|
||
These are available via installable packages on most Linux distributions, Chocolatey, and Homebrew.
|
||
|
||
==== xsltproc
|
||
|
||
http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various formats based on XSL stylesheets.
|
||
It either ships as part of the operating system or is available via an installable package on most Linux distributions, Chocolatey, and Homebrew.
|
||
|
||
[#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\wsbuild64>set PATH="%PATH%;C:\Development\wsbuild64\run\RelwithDebInfo"
|
||
C:\Development\wsbuild64>wireshark.sln
|
||
----
|
||
|
||
for PowerShell use
|
||
|
||
[source,cmd]
|
||
----
|
||
PS C:\Development\wsbuild64>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)"
|
||
PS C:\Development\wsbuild64>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
|
||
https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/[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\wsbuild64\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\wsbuild64\run\Debug\.
|
||
|
||
[#ChToolsBash]
|
||
|
||
=== bash
|
||
|
||
The bash shell is needed to run several shell scripts.
|
||
|
||
[#ChToolsGNUBash]
|
||
|
||
[discrete]
|
||
==== Unix
|
||
|
||
Bash (the GNU Bourne-Again SHell) is available for most UNIX and
|
||
UNIX-like platforms. If it isn't already installed or available as a
|
||
package for your platform, you can get it at
|
||
https://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 4.4.12(1)-release (x86_64-pc-linux-gnu)
|
||
Copyright (C) 2016 Free Software Foundation, Inc.
|
||
----
|
||
|
||
Your version string will likely vary.
|
||
|
||
[#ChToolsPython]
|
||
|
||
=== Python
|
||
|
||
https://python.org/[Python] is an interpreted programming language.
|
||
It is used to generate some source files, documentation, testing and other tasks.
|
||
Python 3.6 and later is required.
|
||
Python 2 is no longer supported.
|
||
|
||
Python is either included or available as a package on most UNIX-like platforms.
|
||
Windows packages and source are available at https://python.org/download/[].
|
||
|
||
You can also use Chocolatey to install Python:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\> choco install python3
|
||
----
|
||
|
||
Chocolatey installs Python into _C:\Python37_ by
|
||
default. You can verify your Python version by running
|
||
|
||
[source,sh]
|
||
----
|
||
$ python3 --version
|
||
----
|
||
|
||
on UNIX-like platforms 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.
|
||
|
||
[#ChToolsFlex]
|
||
|
||
=== Flex
|
||
|
||
Flex is a lexical analyzer generator used for Wireshark’s display filters, some
|
||
file formats, and other features.
|
||
|
||
[#ChToolsUnixFlex]
|
||
|
||
[discrete]
|
||
==== Unix
|
||
|
||
Flex is available for most UNIX and UNIX-like platforms. 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 https://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]
|
||
|
||
[discrete]
|
||
==== Windows
|
||
|
||
A native Windows version of flex is available in the _winflexbison3_
|
||
https://chocolatey.org/[Chocolatey] package. Note that the executable is named
|
||
_win_flex_.
|
||
|
||
[source,cmd]
|
||
----
|
||
PS:\> choco install winflexbison3
|
||
----
|
||
|
||
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]
|
||
|
||
[discrete]
|
||
==== Unix
|
||
|
||
Git is available for most UNIX and UNIX-like platforms. If Git isn't
|
||
already installed or available as a package for your platform, you can
|
||
get it at: https://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]
|
||
|
||
[discrete]
|
||
==== Windows
|
||
|
||
The Git command line tools for Windows can be found at
|
||
https://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
|
||
https://git-scm.com/downloads/guis[] for details.
|
||
|
||
// [[ChToolsUnixGitGUI]]
|
||
// XXX Add Gui client section
|
||
|
||
[#ChToolsPerl]
|
||
|
||
=== Perl (Optional)
|
||
|
||
https://www.perl.org[Perl] is an interpreted programming language.
|
||
Perl is used to convert various text files into usable source code and for various source code checks.
|
||
Perl version 5.6 and above should work fine.
|
||
|
||
[#ChToolsUnixPerl]
|
||
|
||
[discrete]
|
||
==== Unix
|
||
|
||
Perl is available for most UNIX and UNIX-like platforms. If it isn't
|
||
already installed or available as a package for your platform, you can
|
||
get it at https://www.perl.org/[].
|
||
|
||
After correct installation, typing at the
|
||
bash command line prompt:
|
||
|
||
[source,sh]
|
||
----
|
||
$ perl --version
|
||
----
|
||
|
||
should result in something like:
|
||
|
||
----
|
||
This is perl 5, version 26, subversion 0 (v5.26.0) built for x86_64-linux-gnu-thread-multi
|
||
(with 62 registered patches, see perl -V for more detail)
|
||
|
||
Copyright 1987-2017, 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.org/, the Perl Home Page.
|
||
----
|
||
|
||
However, the version string may vary.
|
||
|
||
[#ChToolsWindowsPerl]
|
||
|
||
[discrete]
|
||
==== Windows
|
||
|
||
A native Windows Perl package can be obtained from
|
||
http://strawberryperl.com/[Strawberry Perl] or
|
||
https://www.activestate.com[Active State]. The installation should be
|
||
straightforward.
|
||
|
||
You may also use Chocolatey to install either package:
|
||
|
||
----
|
||
PS:\> choco install strawberryperl
|
||
----
|
||
|
||
or
|
||
|
||
----
|
||
PS:\> choco install activeperl
|
||
----
|
||
|
||
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.
|
||
|
||
[#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 should
|
||
handle patches for you.
|
||
|
||
// You will find more instructions in <<ChSrcPatchApply>>on how to use the patch tool.
|
||
|
||
[#ChToolsUnixPatch]
|
||
|
||
[discrete]
|
||
==== Unix
|
||
|
||
Patch is available for most UNIX and UNIX-like platforms. If GNU patch
|
||
isn't already installed or available as a package for your platform, you
|
||
can get it at https://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]
|
||
|
||
[discrete]
|
||
==== Windows
|
||
|
||
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-win64-{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
|
||
https://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>>.
|
||
|
||
[#ChToolsWiX]
|
||
|
||
=== Windows: WiX Toolset (Optional)
|
||
|
||
The Wix Toolset can be used to generate Windows Installer (_.msi_) packages.
|
||
You can download it from the link:https://wixtoolset.org/[WiX web site] or install it using Chocolatey:
|
||
|
||
[source,cmd]
|
||
----
|
||
PS$> choco install wixtoolset
|
||
----
|
||
|
||
This also requires the Visual C++ redistributable merge modules, which can be installed by selecting “Individual Components -> {cpp} 2022 Redistributable MSMs” or “...2019 Redistributable MSMs” as appropriate for your compiler in the Visual Studio installer.
|
||
|
||
Wireshark’s .msi packaging is currently experimental and the generated packages may be incomplete.
|
||
|
||
[#ChToolsPortableApps]
|
||
=== Windows: PortableApps (Optional)
|
||
|
||
The PortableApps.com Installer is used to generate
|
||
_WiresharkPortable64-{wireshark-version}.paf.exe_ and
|
||
_WiresharkPortable32-{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
|
||
https://portableapps.com/[].
|
||
|
||
* Install the following applications in the PortableApps.com environment:
|
||
|
||
** PortableApps.com Installer
|
||
|
||
** PortableApps.com Launcher
|
||
|
||
You can find more instructions on using the PortableApps.com Installer in
|
||
<<ChSrcPortableApps>>.
|
||
|
||
// End of WSDG Chapter Tools
|
||
|
||
// vim: set syntax=asciidoc:
|