1// WSDG Chapter Tools 2 3[[ChapterTools]] 4 5== Tool Reference 6 7[[ChToolsIntro]] 8 9=== Introduction 10 11This chapter will provide you with information about the various tools 12needed for Wireshark development. None of the tools mentioned in this 13chapter are needed to run Wireshark. They are only needed to build it. 14 15Most of these tools have their roots on UNIX or UNIX-like platforms such 16as Linux, but Windows ports are also available. Therefore the tools are 17available in different "flavours": 18 19* UNIX and UNIX-like platforms: The tools should be commonly available 20 on the supported UNIX and UNIX-like platforms. Cygwin is unsupported. 21* Windows native: Some tools are available as native Windows tools, no 22 special emulation is required. Many of these tools can be installed 23 (and updated) using https://chocolatey.org[Chocolatey], a Windows 24 package manager similar to the Linux package managers apt-get or yum. 25 26[WARNING] 27.Follow the directions 28==== 29Unless you know exactly what you are doing, you should strictly follow the recommendations given in <<ChapterSetup>>. 30==== 31 32The following sections give a very brief description of 33what a particular tool is doing, how it is used in the 34Wireshark project and how it can be installed and 35tested. 36 37Documentation for these tools is outside the scope of this document. If you need 38further information on using a specific tool you should find lots of useful 39information on the web, as these tools are commonly used. You can also get help 40for the UNIX based tools with `**toolname** --help` or the man page via `man 41**toolname**`. 42 43You will find explanations of the tool usage for some of the specific 44development tasks in <<ChapterSources>>. 45 46[[ChToolsChocolatey]] 47=== Chocolatey 48 49Chocolatey is a Windows package manager that can be used to install (and update) 50many of the packages required for Wireshark development. Chocolatey can be 51obtained from the https://chocolatey.org[website] or from a Command Prompt: 52 53[source,cmd] 54---- 55C:\>@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin 56---- 57 58or a Powershell prompt: 59 60[source,cmd] 61---- 62PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_)) 63---- 64 65Chocolatey sometimes installs packages in unexpected locations. Python 66is a notable example. While it's typically installed in a top-level 67directory, e.g. _C:\Python37_ or in %PROGRAMFILES%, e.g. _C:\Program 68Files\Python37_, Chocolatey tends to install it under 69_C:\ProgramData\chocolatey_ or _C:\Tools_. If you want to avoid this 70behavior you'll probably want to install Python using the packages from 71python.org. 72 73Other package managers for Windows include the https://docs.microsoft.com/en-us/windows/package-manager/[Windows Package Manager (winget)] and https://scoop.sh/[Scoop]. 74As of May 2020 neither option provides all of the packages we require, but that might change in the future. 75 76[[ChToolsCMake]] 77 78=== CMake 79 80Wireshark’s build environment can be configured using CMake on various 81UNIX-like platforms, including Linux, macOS, and *BSD, and on Windows. 82CMake is designed to support out-of-tree builds - so much so that 83in-tree builds do not work properly in all cases. Along with being 84cross-platform, CMake supports many build tools and environments 85including traditional make, Ninja, and MSBuild. Our Buildbot runs 86CMake steps on Ubuntu, Win32, Win64, and macOS. In particular, the 87macOS and Windows packages are built using CMake. 88 89Building with CMake typically includes creating a build directory and 90specifying a *generator*, aka a build tool. For example, to build 91Wireshark using Ninja in the directory _wireshark-ninja_ you might 92run the following commands: 93 94[source,sh] 95---- 96# Starting from your Wireshark source directory, create a build directory 97# alongside it. 98$ cd .. 99$ mkdir wireshark-ninja 100$ cd wireshark-ninja 101# Assumes your source directory is named "wireshark". 102$ cmake -G Ninja ../wireshark 103$ ninja (or cmake --build .) 104---- 105 106Using CMake on Windows is described further in <<ChWin32Generate>>. 107 108Along with specifying a generator with the `-G` flag you can set variables 109using the `-D` flag. Useful variables and generators include the following: 110 111-DBUILD_wireshark=OFF:: Don't build the Wireshark GUI application. 112Each command line utility has its own BUILD_xxx flag as well. For 113example, you can use -DBUILD_mmdbresolve=OFF to disable mmdbresolve. 114 115-DENABLE_CAP=OFF:: Disable the POSIX capabilities check 116 117-DCMAKE_BUILD_TYPE=Debug:: Enable debugging symbols 118 119-DCARES_INCLUDE_DIR=/your/custom/cares/include, -DCARES_LIBRARY=/your/custom/cares/lib/libcares.so:: 120Let you set the path to a locally-compiled version of c-ares. Most 121optional libraries have xxx_INCLUDE_DIR and xxx_LIB flags that let you 122control their discovery. 123 124-DCMAKE_OSX_DEPLOYMENT_TARGET=10.12:: 125Specify the minimum macOS version for Wireshark and each command line utility. 126Note that this doesn’t affect the minimum target for third-party libraries. 127For 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`. 128 129-DENABLE_APPLICATION_BUNDLE=OFF:: Disable building an application bundle (Wireshark.app) on macOS 130 131You can list all build variables (with help) by running `cmake -LH [options] 132../<Name_of_WS_source_dir>`. This lists the cache of build variables 133after the cmake run. To only view the current cache, add option `-N`. 134 135After running cmake, you can always run `make help` to see a list of all possible make targets. 136 137Note that CMake honors user umask for creating directories as of now. You should set 138the umask explicitly before running the `install` target. 139 140CMake links: 141 142The home page of the CMake project: https://cmake.org/ 143 144Official documentation: https://cmake.org/documentation/ 145 146About CMake in general and why KDE4 uses it: https://lwn.net/Articles/188693/ 147 148Useful variables: https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/Useful-Variables 149 150Frequently Asked Questions: https://gitlab.kitware.com/cmake/community/wikis/FAQ 151 152[[ChToolsGNUChain]] 153 154=== GNU Compiler Toolchain (UNIX And UNIX-like Platforms) 155 156[[ChToolsGCC]] 157 158==== gcc (GNU Compiler Collection) 159 160The GCC C compiler is available for most UNIX and UNIX-like operating 161systems. 162 163If GCC isn't already installed or available 164as a package for your platform, you can get it at: 165https://gcc.gnu.org/[]. 166 167After correct installation, typing at the 168bash command line prompt: 169 170[source,sh] 171---- 172$ gcc --version 173---- 174 175should result in something like 176 177---- 178gcc (Ubuntu 4.9.1-16ubuntu6) 4.9.1 179Copyright (C) 2014 Free Software Foundation, Inc. 180This is free software; see the source for copying conditions. There is NO 181warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 182---- 183 184Your version string may vary, of course. 185 186[[ChToolsGDB]] 187 188==== gdb (GNU Project Debugger) 189 190GDB is the debugger for the GCC compiler. It is 191available for many (if not all) UNIX-like platforms. 192 193If you don't like debugging using the command line, many 194https://sourceware.org/gdb/wiki/GDB%20Front%20Ends[GUI frontends for it 195available], including Qt Creator, CLion, and Eclipse. 196 197If gdb isn't already installed or available 198as a package for your platform, you can get it at: 199https://www.gnu.org/software/gdb/gdb.html[]. 200 201After correct installation: 202 203[source,sh] 204---- 205$ gdb --version 206---- 207 208should result in something like: 209 210---- 211GNU gdb (GDB) 8.3 212Copyright (C) 2019 Free Software Foundation, Inc. 213License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 214This is free software: you are free to change and redistribute it. 215There is NO WARRANTY, to the extent permitted by law. 216---- 217 218Your version string may vary, of course. 219 220[[ChToolsGNUmake]] 221 222==== make (GNU Make) 223 224[NOTE] 225.GNU make isn't supported either for Windows 226 227GNU Make is available for most of the UNIX-like 228platforms. 229 230If GNU Make isn't already installed or 231available as a package for your platform, you can get it at: 232https://www.gnu.org/software/make/[]. 233 234After correct installation: 235 236[source,sh] 237---- 238$ make --version 239---- 240 241should result in something like: 242 243---- 244GNU Make 4.0 245Built for x86_64-pc-linux-gnu 246Copyright (C) 1988-2013 Free Software Foundation, Inc. 247Licence GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 248This is free software: you are free to change and redistribute it. 249There is NO WARRANTY, to the extent permitted by law. 250---- 251 252Your version string may vary, of course. 253 254==== Ninja 255 256Ninja is an alternative to make, and is available for many of the 257UNIX-like platforms. It runs builds faster than make does. 258 259It is designed to have its build files generated by tools such as CMake; 260to generate build files for Ninja, run CMake with the `-G Ninja` flag. 261 262If Ninja isn't already installed, see the list of suggestions for Ninja 263packages at: 264https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages. 265 266If Ninja isn't already installed and isn't 267available as a package for your platform, you can get it from: 268https://ninja-build.org. You can download the source code or binaries 269for Linux, macOS, and Windows (we have not tested Ninja on Windows). 270 271[[ChToolsMSChain]] 272 273=== Microsoft compiler toolchain (Windows native) 274 275To compile Wireshark on Windows using the Microsoft C/{cpp} 276compiler (MSVC), you'll need: 277 278. C compiler (_cl.exe_) 279 280. Assembler (_ml.exe_ for 32-bit targets and _ml64.exe_ for 64-bit targets) 281 282. Linker (_link.exe_) 283 284. Resource Compiler (_rc.exe_) 285 286. C runtime headers and libraries (e.g. _stdio.h_, _vcruntime140.lib_) 287 288. Windows platform headers and libraries (e.g. 289_windows.h_, _WS2_32.lib_) 290 291==== Official Toolchain Packages And Alternatives 292 293Official releases are or were built with the following Visual {cpp} versions: 294 295* Wireshark 3.4.x: Microsoft Visual {cpp} 2019. 296* Wireshark 3.2.x: Microsoft Visual {cpp} 2019. 297* Wireshark 3.0.x: Microsoft Visual {cpp} 2017. 298* Wireshark 2.6.x: Microsoft Visual {cpp} 2017. 299* Wireshark 2.4.x: Microsoft Visual {cpp} 2015. 300* Wireshark 2.2.x: Microsoft Visual {cpp} 2013. 301* Wireshark 2.0.x: Microsoft Visual {cpp} 2013. 302* Wireshark 1.12.x: Microsoft Visual {cpp} 2010 SP1. 303* Wireshark 1.10.x: Microsoft Visual {cpp} 2010 SP1. 304* Wireshark 1.8.x: Microsoft Visual {cpp} 2010 SP1. 305* Wireshark 1.6.x: Microsoft Visual {cpp} 2008 SP1. 306* Wireshark 1.4.x: Microsoft Visual {cpp} 2008 SP1. 307* Wireshark 1.2.x: Microsoft Visual {cpp} 2008 SP1. 308* Wireshark 1.0.x and earlier: Microsoft Visual {cpp} 6.0. 309 310Using the release compilers is recommended for Wireshark development work. 311 312“Community” editions of Visual Studio such as “Visual Studio Community 3132019” can be used to compile Wireshark but any PortableApps packages you 314create with them might require the installation of a separate Visual 315{cpp} Redistributable package on any machine on which the PortableApps 316package is to be used. See <<msvc-runtime-redistributable>> below for 317more details. 318 319However, you might already have a different Microsoft {cpp} compiler 320installed. It should be possible to use any of the following with the 321considerations listed. You will need to sign up for a 322https://visualstudio.microsoft.com/dev-essentials/[Visual Studio Dev 323Essentials] account if you don't have a Visual Studio (MSDN) 324subscription. The older versions can be downloaded from 325https://visualstudio.microsoft.com/vs/older-downloads/[]. 326 327.Visual {cpp} 2019 Community Edition 328 329IDE + Debugger?:: Yes 330 331SDK required for 64-bit builds?:: No 332 333CMake Generator: *`Visual Studio 16`* 334 335You can use Chocolatey to install Visual Studio, e.g: 336 337[source,cmd] 338---- 339PS:\> choco install visualstudiocommunity2019 visualstudio2019-workload-nativedesktop 340---- 341 342==== cl.exe (C Compiler) 343 344The following table gives an overview of the possible 345Microsoft toolchain variants and their specific C compiler 346versions ordered by release date. 347 348|=== 349|Compiler Package|cl.exe|_MSC_VER 350|Visual Studio 2019|16.0.0|1920 351|Visual Studio 2019|16.1.2|1921 352|Visual Studio 2019|16.2.3|1922 353|Visual Studio 2019|16.3.2|1923 354|=== 355 356After correct installation of the toolchain, typing 357at the Visual Studio Command line prompt (cmd.exe): 358 359[source,cmd] 360---- 361> cl 362---- 363 364should result in something like: 365 366---- 367Microsoft (R) C/C++ Optimizing Compiler Version 19.23.28106.4 for x64 368Copyright (C) Microsoft Corporation. All rights reserved. 369 370usage: cl [ option... ] filename... [ /link linkoption... ] 371---- 372 373However, the version string may vary. 374 375Documentation on the compiler can be found at 376https://docs.microsoft.com/en-us/cpp/build/reference/compiling-a-c-cpp-program?view=vs-2019[Microsoft Docs] 377 378==== link.exe (Linker) 379 380After correct installation, typing at the Visual Studio Command line prompt (cmd.exe): 381 382[source,cmd] 383---- 384> link 385---- 386 387should result in something like: 388 389---- 390Microsoft (R) Incremental Linker Version 14.23.28106.4 391Copyright (C) Microsoft Corporation. All rights reserved. 392 393 usage: LINK [options] [files] [@commandfile] 394 ... 395---- 396 397However, the version string may vary. 398 399Documentation on the linker can be found at 400https://docs.microsoft.com/en-us/cpp/build/reference/linking?view=vs-2019[Microsoft Docs] 401 402[[msvc-runtime-redistributable]] 403 404==== Visual {cpp} Runtime “Redistributable” Files 405 406Please note: The following is not legal advice. Ask your preferred 407lawyer instead. It’s the authors view and this view might be wrong. 408 409Wireshark and its libraries depend on POSIX functions such as fopen() 410and malloc(). On Windows, these functions are provided by the Microsoft 411Visual {cpp} C Runtime (CRT). There are many different versions of the CRT and 412Visual {cpp} 2015 and later use the _Universal CRT_ (UCRT). 413 414The Universal CRT comes standard with Windows 10 and is installed as part 415of Windows Update on earlier versions of Windows. The Wireshark .exe 416installers include redistributables (_vcredist_x86.exe_ or 417_vcredist_x64.exe_) which ensure that the Universal CRT is installed and 418up to date. 419 420[NOTE] 421.Make sure you're allowed to distribute this file 422==== 423The files to redistribute must be mentioned in the 424redist.txt file of the compiler package. Otherwise it 425can't be legally redistributed by third parties like 426us. 427==== 428 429The following Microsoft Docs link is recommended for the 430interested reader: 431 432https://docs.microsoft.com/en-us/cpp/windows/redistributing-visual-cpp-files?view=vs-2019[Redistributing Visual {cpp} Files] 433 434In all cases where _vcredist_x86.exe_ or _vcredist_x64.exe_ is 435downloaded it should be downloaded to the directory into which the 436support libraries for Wireshark have been downloaded and installed. This 437directory is specified by the `WIRESHARK_BASE_DIR` or 438`WIRESHARK_LIB_DIR` environment variables. It need not, and should not, 439be run after being downloaded. 440 441==== Windows Platform SDK 442 443The Windows Platform SDK (PSDK) or Windows SDK is a free 444(as in beer) download and contains platform specific headers and 445libraries (e.g. _windows.h_, _WSock32.lib_, etc.). As new Windows 446features evolve in time, updated SDKs become available that 447include new and updated APIs. 448 449When you purchase a commercial Visual Studio or use the Community 450Edition, it will include an SDK. 451 452[[ChToolsDocumentationToolchain]] 453=== Documentation Toolchain 454 455Wireshark’s documentation is split across two directories. 456The `doc` directory contains man pages written in Asciidoctor markup. 457The `docbook` directory contains the User’s Guide, Developer’s Guide, and the release notes, which are also written in Asciidoctor markup. 458The split is for historical reasons (described below), and the documentation will likely be consolidated into one directory in the future. 459 460Our various output formats are generated using the following tools. 461Intermediate formats are in _italics_. 462 463Man page roff:: Asciidoctor 464Man page HTML:: Asciidoctor 465 466Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL 467Guide PDF:: Asciidoctor 468 469Release notes HTML:: Asciidoctor 470Release notes text:: Asciidoctor → _HTML_ → html2text.py 471 472==== Asciidoctor 473 474https://asciidoctor.org/[Asciidoctor] comes in several flavors: a Ruby gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled JavaScript (Asciidoctor.js). 475The 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. 476// We need docbook5, PDF & EPUB output and macros 477 478The guides and release notes were originally written in DocBook (hence the directory name). 479They were later converted to AsciiDoc and then migrated to Asciidoctor. 480The man pages were originally in Perl’s POD (Plain Old Documentation) format and were later converted to Asciidoctor. 481We currently use Asciidoctor’s modern (>= 1.5.0) syntax. 482 483PDF output requires Asciidoctor’s PDF backend. 484It is included with AsciidoctorJ but _not_ with Asciidoctor. 485 486==== DocBook XML and XSL 487 488Converting from DocBook to HTML requires the DocBook DTD 489(http://www.sagehill.net/docbookxsl/ToolsSetup.html) 490and DocBook stylesheets 491(http://www.sagehill.net/docbookxsl/InstallStylesheets.html). 492These are available via installable packages on most Linux distributions, Chocolatey, and Homebrew. 493 494==== xsltproc 495 496http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various formats based on XSL stylesheets. 497It either ships as part of the operating system or is available via an installable package on most Linux distributions, Chocolatey, and Homebrew. 498 499[[ChToolsDebugger]] 500 501=== Debugger 502 503Using a good debugger can save you a lot of development time. 504 505The debugger you use must match the C compiler Wireshark was compiled with, 506otherwise the debugger will simply fail or you will only see a lot of garbage. 507 508[[ChToolsMSVCDebugger]] 509 510==== Visual Studio Integrated Debugger 511 512You can use the integrated debugger of Visual Studio if your toolchain includes 513it. Open the solution in your build directory and build and debug as normal 514with a Visual Studio solution. 515 516To set the correct paths for Visual Studio when running Wireshark under the 517debugger, add the build output directory to the path before opening Visual 518Studio from the same command prompt, e.g. 519 520[source,cmd] 521---- 522C:\Development\wsbuild64>set PATH="%PATH%;C:\Development\wsbuild64\run\RelwithDebInfo" 523C:\Development\wsbuild64>wireshark.sln 524---- 525 526for PowerShell use 527 528[source,cmd] 529---- 530PS C:\Development\wsbuild64>$env:PATH += ";$(Convert-Path run\RelWithDebInfo)" 531PS C:\Development\wsbuild64>wireshark.sln 532---- 533 534When Visual Studio has finished loading the solution, set the executable to 535be run in the debugger, e.g. Executables\Wireshark, by right clicking it in 536the Solution Explorer window and selecting "Set as StartUp Project". Also 537set the Solution Configuration (usually RelWithDebInfo) from the droplist on 538the toolbar. 539 540NOTE: Currently Visual Studio regards a command line build as incomplete, so 541will report that some items need to be built when starting the debugger. These 542can either be rebuilt or ignored as you wish. 543 544 545The normal build is an optimised release version so debugging can be a bit 546difficult as variables are optimised out into registers and the execution 547order of statements can jump around. 548 549If you require a non-optimised version, then build using a debug configuration. 550 551[[ChToolsMSDebuggingTools]] 552 553==== Debugging Tools For Windows 554 555You can also use the Microsoft Debugging Tools for Windows toolkit, which is a 556standalone GUI debugger. Although it’s not that comfortable compared to 557debugging with the Visual Studio integrated debugger it can be helpful if you 558have to debug on a machine where an integrated debugger is not available. 559 560You can get it free of charge from Microsoft in several ways, see the 561https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/[Debugging tools for Windows] page. 562 563You can also use Chocolatey to install WinDbg: 564 565[source,cmd] 566---- 567PS:\> choco install windbg 568---- 569 570To debug Wireshark using WinDbg, open the built copy of Wireshark using 571the File -> Open Executable... menu, 572i.e. C:\Development\wsbuild64\run\RelWithDebInfo\Wireshark.exe. To set a 573breakpoint open the required source file using the File -> Open Source File... 574menu and then click on the required line and press F9. To run the program, 575press F5. 576 577If you require a non-optimised version, then build using a debug configuration, e.g. 578*`msbuild /m /p:Configuration=Debug Wireshark.sln`*. The build products will be found 579in C:\Development\wsbuild64\run\Debug\. 580 581[[ChToolsBash]] 582 583=== bash 584 585The bash shell is needed to run several shell scripts. 586 587[[ChToolsGNUBash]] 588 589[discrete] 590==== Unix 591 592Bash (the GNU Bourne-Again SHell) is available for most UNIX and 593UNIX-like platforms. If it isn't already installed or available as a 594package for your platform, you can get it at 595https://www.gnu.org/software/bash/bash.html[]. 596 597After correct installation, typing at the bash command line prompt: 598 599[source,sh] 600---- 601$ bash --version 602---- 603 604should result in something like: 605 606---- 607GNU bash, version 4.4.12(1)-release (x86_64-pc-linux-gnu) 608Copyright (C) 2016 Free Software Foundation, Inc. 609---- 610 611Your version string will likely vary. 612 613[[ChToolsPython]] 614 615=== Python 616 617https://python.org/[Python] is an interpreted programming language. It is 618used to generate some source files, documentation, testing and other tasks. 619Python 3.4 and later is required. Python 2.7 is no longer supported. 620 621Python is either included or available as a package on most UNIX-like platforms. 622Windows packages and source are available at https://python.org/download/[]. 623 624You can also use Chocolatey to install Python: 625 626[source,cmd] 627---- 628PS:\> choco install python3 629---- 630 631Chocolatey installs Python into _C:\Python37_ by 632default. You can verify your Python version by running 633 634[source,sh] 635---- 636$ python3 --version 637---- 638 639on UNIX-like platforms and 640 641[source,cmd] 642---- 643rem Official package 644C:> cd python35 645C:Python35> python --version 646 647rem Chocolatey 648C:> cd \tools\python3 649C:\tools\python3> python --version 650---- 651 652on Windows. You should see something like 653 654---- 655Python 3.5.1 656---- 657 658Your version string may vary of course. 659 660[[ChToolsPerl]] 661 662=== Perl 663 664Perl is an interpreted programming language. The 665homepage of the Perl project is 666https://www.perl.org[]. Perl is used to convert 667various text files into usable source code. Perl version 5.6 668and above should work fine. 669 670[[ChToolsUnixPerl]] 671 672[discrete] 673==== Unix 674 675Perl is available for most UNIX and UNIX-like platforms. If perl isn't 676already installed or available as a package for your platform, you can 677get it at https://www.perl.org/[]. 678 679After correct installation, typing at the 680bash command line prompt: 681 682[source,sh] 683---- 684$ perl --version 685---- 686 687should result in something like: 688 689---- 690This is perl 5, version 26, subversion 0 (v5.26.0) built for x86_64-linux-gnu-thread-multi 691(with 62 registered patches, see perl -V for more detail) 692 693Copyright 1987-2017, Larry Wall 694 695Perl may be copied only under the terms of either the Artistic License or the 696GNU General Public License, which may be found in the Perl 5 source kit. 697 698Complete documentation for Perl, including FAQ lists, should be found on 699this system using "man perl" or "perldoc perl". If you have access to the 700Internet, point your browser at http://www.perl.org/, the Perl Home Page. 701---- 702 703However, the version string may vary. 704 705[[ChToolsWindowsPerl]] 706 707[discrete] 708==== Windows 709 710A native Windows Perl package can be obtained from 711http://strawberryperl.com/[Strawberry Perl] or 712https://www.activestate.com[Active State]. The installation should be 713straightforward. 714 715You may also use Chocolatey to install either package: 716 717---- 718PS:\> choco install strawberryperl 719---- 720 721or 722 723---- 724PS:\> choco install activeperl 725---- 726 727After correct installation, typing at the command 728line prompt (cmd.exe): 729 730---- 731> perl -v 732---- 733 734should result in something like: 735 736---- 737This is perl, v5.8.0 built for MSWin32-x86-multi-thread 738(with 1 registered patch, see perl -V for more detail) 739 740Copyright 1987-2002, Larry Wall 741 742Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com 743Built 18:08:02 Feb 4 2003 744... 745---- 746 747However, the version string may vary. 748 749[[ChToolsFlex]] 750 751=== Flex 752 753Flex is a lexical analyzer generator used for Wireshark’s display filters, some 754file formats, and other features. 755 756[[ChToolsUnixFlex]] 757 758[discrete] 759==== Unix 760 761Flex is available for most UNIX and UNIX-like platforms. See the next 762section for native Windows options. 763 764If GNU flex isn't already installed or available as a package for your platform 765you can get it at https://www.gnu.org/software/flex/[]. 766 767After correct installation running the following 768 769[source,sh] 770---- 771$ flex --version 772---- 773 774should result in something like: 775 776---- 777flex version 2.5.4 778---- 779 780Your version string may vary. 781 782[[ChToolsWindowsFlex]] 783 784[discrete] 785==== Windows 786 787A native Windows version of flex is available in the _winflexbison3_ 788https://chocolatey.org/[Chocolatey] package. Note that the executable is named 789_win_flex_. 790 791[source,cmd] 792---- 793PS:\> choco install winflexbison3 794---- 795 796Native packages are available from other sources such as 797http://gnuwin32.sourceforge.net/packages/flex.htm[GnuWin]. They aren't 798officially supported but _should_ work. 799 800[[ChToolsGit]] 801 802=== Git client 803 804The Wireshark project uses its own Git repository to keep track of all 805the changes done to the source code. Details about the usage of Git in 806the Wireshark project can be found in <<ChSrcGitRepository>>. 807 808If you want to work with the source code and are planning to commit your 809changes back to the Wireshark community, it is recommended to use a Git 810client to get the latest source files. For detailed information about 811the different ways to obtain the Wireshark sources, see <<ChSrcObtain>>. 812 813You will find more instructions in <<ChSrcGit>> on how to use the Git 814client. 815 816[[ChToolsUnixGit]] 817 818[discrete] 819==== Unix 820 821Git is available for most UNIX and UNIX-like platforms. If Git isn't 822already installed or available as a package for your platform, you can 823get it at: https://git-scm.com/[]. 824 825After correct installation, typing at the bash command line prompt: 826 827[source,sh] 828---- 829$ git --version 830---- 831 832should result in something like: 833 834---- 835git version 2.14.1 836---- 837 838Your version will likely be different. 839 840[[ChToolsWindowsGit]] 841 842[discrete] 843==== Windows 844 845The Git command line tools for Windows can be found at 846https://git-scm.com/download/win[] and can also be installed using Chocolatey: 847 848[source,cmd] 849---- 850PS:\> choco install git 851---- 852 853After correct installation, typing at the command 854line prompt (cmd.exe): 855 856[source,cmd] 857---- 858> git --version 859---- 860 861should result in something like: 862 863---- 864git version 2.16.1.windows.1 865---- 866 867However, the version string may vary. 868 869[[ChToolsGitPowerShellExtensions]] 870 871=== Git Powershell Extensions (Optional) 872 873A useful tool for command line git on Windows is https://github.com/dahlbyk/posh-git[PoshGit]. 874Poshgit provides git command completion and alters the prompt to indicate the local working 875copy status. You can install it using Chocolatey: 876 877[source,cmd] 878---- 879PS:\> choco install poshgit 880---- 881 882[[ChToolsGitGUI]] 883 884=== Git GUI Client (Optional) 885 886Along with the traditional command-line client, several 887GUI clients are available for a number of platforms. See 888https://git-scm.com/downloads/guis[] for details. 889 890// [[ChToolsUnixGitGUI]] 891// XXX Add Gui client section 892 893[[ChToolsPatch]] 894 895=== patch (Optional) 896 897The patch utility is used to merge a diff file into your own source tree. This 898tool is only needed, if you want to apply a patch (diff file) from someone else 899(probably from the developer mailing list) to try out in your own private source 900tree. 901 902It most cases you may not need the patch tool installed. Git should 903handle patches for you. 904 905// You will find more instructions in <<ChSrcPatchApply>>on how to use the patch tool. 906 907[[ChToolsUnixPatch]] 908 909[discrete] 910==== Unix 911 912Patch is available for most UNIX and UNIX-like platforms. If GNU patch 913isn't already installed or available as a package for your platform, you 914can get it at https://www.gnu.org/software/patch/patch.html[]. 915 916After correct installation, typing at the 917bash command line prompt: 918 919[source,sh] 920---- 921$ patch --version 922---- 923 924should result in something like: 925 926---- 927patch 2.5.8 928Copyright (C) 1988 Larry Wall 929Copyright (C) 2002 Free Software Foundation, Inc. 930 931This program comes with NO WARRANTY, to the extent permitted by law. 932You may redistribute copies of this program 933under the terms of the GNU General Public License. 934For more information about these matters, see the file named COPYING. 935 936written by Larry Wall and Paul Eggert 937---- 938 939However, the version string may vary. 940 941[[ChToolsWindowsPatch]] 942 943[discrete] 944==== Windows 945 946The Windows native Git tools provide patch. A native Windows patch package can be obtained from 947http://gnuwin32.sourceforge.net/[]. The 948installation should be straightforward. 949 950[[ChToolsNSIS]] 951 952=== Windows: NSIS (Optional) 953 954The NSIS (Nullsoft Scriptable Install System) is used to generate 955_Wireshark-win32-{wireshark-version}.exe_ from all the files 956needed to be installed, including all required DLLs, plugins, and supporting 957files. 958 959To install it, download the latest released version from 960https://nsis.sourceforge.net[]. NSIS v3 is required. You can also install 961it using Chocolatey: 962 963[source,cmd] 964---- 965PS$> choco install nsis 966---- 967 968You can find more instructions on using NSIS in <<ChSrcNSIS>>. 969 970[[ChToolsWiX]] 971 972=== Windows: WiX Toolset (Optional) 973 974The Wix Toolset can be used to generate Windows Installer (_.msi_) packages. 975You can download it from the link:https://wixtoolset.org/[WiX web site] or install it using Chocolatey: 976 977[source,cmd] 978---- 979PS$> choco install wixtoolset 980---- 981 982This also requires the Visual C++ redistributable merge modules, which can be installed by selecting “Individual Components -> {cpp} 2019 Redistributable MSMs” in the Visual Studio installer. 983 984Wireshark’s .msi packaging is currently experimental and the generated packages may be incomplete. 985 986[[ChToolsPortableApps]] 987=== Windows: PortableApps (Optional) 988 989The PortableApps.com Installer is used to generate 990_WiresharkPortable64-{wireshark-version}.paf.exe_ and 991_WiresharkPortable32-{wireshark-version}.paf.exe_ from all the files 992needed to be installed, including all required DLLs, plugins, and supporting 993files. 994 995To install it, do the following: 996 997* Download the latest PortableApps.com Platform release from 998 https://portableapps.com/[]. 999 1000* Install the following applications in the PortableApps.com environment: 1001 1002** PortableApps.com Installer 1003 1004** PortableApps.com Launcher 1005 1006You can find more instructions on using the PortableApps.com Installer in 1007<<ChSrcPortableApps>>. 1008 1009// End of WSDG Chapter Tools 1010 1011// vim: set syntax=asciidoc: 1012