diff options
Diffstat (limited to 'docbook/wsdg_src/WSDG_chapter_tools.adoc')
| -rw-r--r-- | docbook/wsdg_src/WSDG_chapter_tools.adoc | 1011 |
1 files changed, 0 insertions, 1011 deletions
diff --git a/docbook/wsdg_src/WSDG_chapter_tools.adoc b/docbook/wsdg_src/WSDG_chapter_tools.adoc deleted file mode 100644 index 3af774f5e1..0000000000 --- a/docbook/wsdg_src/WSDG_chapter_tools.adoc +++ /dev/null @@ -1,1011 +0,0 @@ -// 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 May 2020 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. Our Buildbot runs -CMake steps on Ubuntu, Win32, Win64, and macOS. In particular, the -macOS and Windows packages are built using CMake. - -Building with CMake typically includes creating a build directory and -specifying a *generator*, aka a build tool. For example, to build -Wireshark using Ninja in the directory _wireshark-ninja_ you might -run the following commands: - -[source,sh] ----- -# Starting from your Wireshark source directory, create a build directory -# alongside it. -$ cd .. -$ mkdir wireshark-ninja -$ cd wireshark-ninja -# Assumes your source directory is named "wireshark". -$ cmake -G Ninja ../wireshark -$ ninja (or cmake --build .) ----- - -Using CMake on Windows is described further in <<ChWin32Generate>>. - -Along with specifying a generator with the `-G` flag you can set variables -using the `-D` flag. Useful variables and generators include the following: - --DBUILD_wireshark=OFF:: Don't build the Wireshark GUI application. -Each command line utility has its own BUILD_xxx flag as well. For -example, you can use -DBUILD_mmdbresolve=OFF to disable mmdbresolve. - --DENABLE_CAP=OFF:: Disable the POSIX capabilities check - --DCMAKE_BUILD_TYPE=Debug:: Enable debugging symbols - --DCARES_INCLUDE_DIR=/your/custom/cares/include, -DCARES_LIBRARY=/your/custom/cares/lib/libcares.so:: -Let you set the path to a locally-compiled version of c-ares. Most -optional libraries have xxx_INCLUDE_DIR and xxx_LIB flags that let you -control their discovery. - --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`. - -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 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 -2019” 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} 2019 Community Edition - -IDE + Debugger?:: Yes - -SDK required for 64-bit builds?:: No - -CMake Generator: *`Visual Studio 16`* - -You can use Chocolatey to install Visual Studio, e.g: - -[source,cmd] ----- -PS:\> choco install visualstudiocommunity2019 visualstudio2019-workload-nativedesktop ----- - -==== cl.exe (C Compiler) - -The following table gives an overview of the possible -Microsoft toolchain variants and their specific C compiler -versions ordered by release date. - -|=== -|Compiler Package|cl.exe|_MSC_VER -|Visual Studio 2019|16.0.0|1920 -|Visual Studio 2019|16.1.2|1921 -|Visual Studio 2019|16.2.3|1922 -|Visual Studio 2019|16.3.2|1923 -|=== - -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 the compiler can be found at -https://docs.microsoft.com/en-us/cpp/build/reference/compiling-a-c-cpp-program?view=vs-2019[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 the linker can be found at -https://docs.microsoft.com/en-us/cpp/build/reference/linking?view=vs-2019[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 (_vcredist_x86.exe_ or -_vcredist_x64.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?view=vs-2019[Redistributing Visual {cpp} Files] - -In all cases where _vcredist_x86.exe_ or _vcredist_x64.exe_ is -downloaded it should be downloaded to the directory into which the -support libraries for Wireshark have been downloaded and installed. This -directory is specified by the `WIRESHARK_BASE_DIR` or -`WIRESHARK_LIB_DIR` environment variables. It need not, and should not, -be run after being downloaded. - -==== 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 currently 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.4 and later is required. Python 2.7 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. - -[[ChToolsPerl]] - -=== Perl - -Perl is an interpreted programming language. The -homepage of the Perl project is -https://www.perl.org[]. Perl is used to convert -various text files into usable source code. Perl version 5.6 -and above should work fine. - -[[ChToolsUnixPerl]] - -[discrete] -==== Unix - -Perl is available for most UNIX and UNIX-like platforms. If perl 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. - -[[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 - -[[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-win32-{wireshark-version}.exe_ from all the files -needed to be installed, including all required DLLs, plugins, and supporting -files. - -To install it, download the latest released version from -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} 2019 Redistributable MSMs” in the Visual Studio installer. - -Wireshark’s .msi packaging is currently experimental and the generated packages may be incomplete. - -[[ChToolsPortableApps]] -=== Windows: PortableApps (Optional) - -The PortableApps.com Installer is used to generate -_WiresharkPortable64-{wireshark-version}.paf.exe_ and -_WiresharkPortable32-{wireshark-version}.paf.exe_ from all the files -needed to be installed, including all required DLLs, plugins, and supporting -files. - -To install it, do the following: - -* Download the latest PortableApps.com Platform release from - https://portableapps.com/[]. - -* Install the following applications in the PortableApps.com environment: - -** PortableApps.com Installer - -** PortableApps.com Launcher - -You can find more instructions on using the PortableApps.com Installer in -<<ChSrcPortableApps>>. - -// End of WSDG Chapter Tools - -// vim: set syntax=asciidoc: |