diff options
Diffstat (limited to 'doc/wsdg_src/wsdg_tools.adoc')
| -rw-r--r-- | doc/wsdg_src/wsdg_tools.adoc | 1041 |
1 files changed, 1041 insertions, 0 deletions
diff --git a/doc/wsdg_src/wsdg_tools.adoc b/doc/wsdg_src/wsdg_tools.adoc new file mode 100644 index 00000000..09f1b576 --- /dev/null +++ b/doc/wsdg_src/wsdg_tools.adoc @@ -0,0 +1,1041 @@ +// 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 following 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, 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_. + +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: |