Adding upstream version 4.2.2.upstream/4.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1043 insertions, 0 deletions

diff --git a/docbook/wsdg_src/wsdg_tools.adoc b/docbook/wsdg_src/wsdg_tools.adoc
new file mode 100644
index 00000000..f1d99e94
--- /dev/null
+++ b/docbook/wsdg_src/wsdg_tools.adoc
@@ -0,0 +1,1043 @@
+// 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.2.x: Microsoft Visual {cpp} 2022.
+* 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
+----
+
+If you wish to build Arm64 executables you must install the following components:
+
+Microsoft.VisualStudio.Component.VC.Tools.ARM64:: MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (Latest)
+
+Microsoft.VisualStudio.Component.VC.Runtimes.ARM64.Spectre:: MSVC v143 - VS 2022 C++ ARM64/ARM64EC Spectre-mitigated libs (Latest)
+
+==== 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   | V{cpp} | _MSC_VER
+| Visual Studio 2022 (17.4.2) | 14.34   | 1934
+|===
+
+A description of `_MSC_VER` and `_MSC_FULL_VER`, and their relation to Visual Studio and compiler versions,
+can be found at
+https://learn.microsoft.com/en-us/cpp/preprocessor/predefined-macros?view=msvc-170[Microsoft-specific predefined macros].
+
+Information on the V{cpp} version can be found in the file _wsutil/version_info.c_.
+
+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-{wireshark-version}-x64.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{underscore}{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: