diff options
Diffstat (limited to 'doc/wsdg_src/wsdg_quick_setup.adoc')
| -rw-r--r-- | doc/wsdg_src/wsdg_quick_setup.adoc | 967 |
1 files changed, 967 insertions, 0 deletions
diff --git a/doc/wsdg_src/wsdg_quick_setup.adoc b/doc/wsdg_src/wsdg_quick_setup.adoc new file mode 100644 index 00000000..7cfc636b --- /dev/null +++ b/doc/wsdg_src/wsdg_quick_setup.adoc @@ -0,0 +1,967 @@ +// WSDG Chapter Setup + +[#ChapterSetup] + +== Setup and Build Instructions + +[#ChSetupUNIX] + +=== UN*X + +[#ChSetupUNIXBuildEnvironmentSetup] + +==== Build environment setup + +The following must be installed in order to build Wireshark: + +* a C compiler and a C++ compiler; +* the Flex lexical analyzer; +* Python 3; +* CMake; +* several required libraries. + +Either make or Ninja can be used to build Wireshark; at least one of +those must be installed. + +To build the manual pages, Developer's Guide and User's Guide, Asciidoctor, Xsltproc, and DocBook must be installed. + +Perl is required to generate some code and run some code analysis checks. + +Some features of Wireshark require additional libraries to be installed. +The processes for doing so on various UN*X families is shown here. + +There are shell scripts in the `tools` directory to install the packages +and libraries required to build Wireshark. Usage is available with the +`--help` option. `root` permission is required to run the scripts. +The available scripts and their options for a given family of UN*Xes are +shown in the section for that family. + +[discrete] +==== Alpine Linux + +The setup script is `tools/alpine-setup.sh`; its options are: + +* `--install-optional` install optional software as well +* `--install-all` install everything +* `[other]` other options are passed as-is to apk + +[discrete] +==== Arch Linux and pacman-based systems + +The setup script is `tools/arch-setup.sh`; its options are: + +* `--install-optional` install optional software as well +* `--install-test-deps` install packages required to run all tests +* `--install-all` install everything +* `[other]` other options are passed as-is to pacman + +[discrete] +==== BSD systems such as FreeBSD, NetBSD, OpenBSD, and DragonFly BSD + +The setup script is `tools/bsd-setup.sh`; its options are: + +* `--install-optional` install optional software as well +* `[other]` other options are passed as-is to pkg manager + +[discrete] +==== Debian, and Linux distributions based on Debian, such as Ubuntu + +The setup script is `tools/debian-setup.sh`; its options are: + +* `--install-optional` install optional software as well +* `--install-deb-deps` install packages required to build the .deb file +* `--install-test-deps` install packages required to run all tests +* `--install-qt5-deps` force installation of packages required to use Qt5 +* `--install-qt6-deps` force installation of packages required to use Qt6 +* `--install-all` install everything +* `[other]` other options are passed as-is to apt + +[discrete] +==== RPM-based Linux distributions such as Red Hat, Centos, Fedora, and openSUSE + + +The setup script is `tools/rpm-setup.sh`; its options are: + +* `--install-optional` install optional software as well +* `--install-rpm-deps` install packages required to build the .rpm file +* `--install-qt5-deps` force installation of packages required to use Qt5 +* `--install-qt6-deps` force installation of packages required to use Qt6 +* `--install-all` install everything +* `[other]` other options are passed as-is to the packet manager + +[discrete] +==== macOS + +You must first install Xcode. + +After installing Xcode, the setup script `tools/macos-setup.sh` will +install the rest of the tools and libraries required to build Wireshark, +except for Qt 6, as well as the additional tools required to build the +documentation and the libraries required for all Wireshark features. If +you're using Homebrew, the script `tools/macos-setup-brew.sh` will +install the same tools and libraries from Homebrew. + +If you will be building Wireshark with Qt 6, which is the default for +Wireshark 4.0 and later, you will also have to install Qt; the +`tools/macos-setup.sh` script will not install Qt 6. To install +Qt, go to the https://www.qt.io/download-qt-installer-oss[Download Qt +for open source use page], select “macOS” if it's not already selected, +and then select “Qt online installer for macOS“. This will download a +.dmg for the installer; launch the installer. It will require that you +log into your Qt account; if you don't have an account, select “Sign up“ +to create one. The next page will require you to accept the LGPL (Lesser +GNU Public License); do so. Continue to the “Installation Folder“ page +of the installer screen, and select the “Custom installation“ option. +On the “Select Components“ screen of the installer, select, for the +desired Qt version, the “macOS” component. For example, at the time of +this writing the Qt {qt6-lts-version} “macOS” component is used to build +the official packages. The “Qt Debug Information Files” component +contains dSYM files which can be used for debugging. You can deselect +all of the other the components such as “Qt Charts” or “Android xxxx” +as they aren’t required. + +Qt 6 needs the "Qt 5 Compatibility Module" to be installed as well. Additionally, the module +"Qt Multimedia" may be installed, to support advanced controls for playing back streams in the +RTP Player dialog. + +[#ChSetupUNIXBuild] + +==== Building + +Before building: + +On macOS, you will need to set the Qt installation directory in the +environment: + +[subs="attributes+"] +---- +WIRESHARK_QT6_PREFIX_PATH=~/Qt/{qt6-lts-version}/macos +export WIRESHARK_QT6_PREFIX_PATH +---- + +If you want to append a custom string to the package version, run the +command + +[subs="attributes+"] +---- +WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo +export WIRESHARK_VERSION_EXTRA +---- + +The recommended (and fastest) way to build Wireshark is with CMake +and Ninja. Building with make took nearly 2x time as Ninja in one +experiment. + +CMake builds are best done in a separate build directory, such as a +`build` subdirectory of the top-level source directory. + +If that directory is a subdirectory of the top-level source directory, +to generate the build files, change to the build directory and enter the +following command: + +---- +cmake .. +---- + +to use make as the build tool or + +---- +cmake -G Ninja .. +---- + +to use Ninja as the build tool. + +If you created the build directory in the +same directory that contains the top-level Wireshark source directory, +to generate the build files, change to the build directory and enter the +following command: + +---- +cmake ../{source directory} +---- + +to use make as the build tool or + +---- +cmake -G Ninja ../{source directory} +---- + +to use Ninja as the build tool. + +`{source directory}` is the name of the +top-level Wireshark source directory. + +If you need to build with a non-standard configuration, you can run + +[source,sh] +---- +cmake -LH ../{source directory} +---- + +to see what options you have. + +You can then run Ninja or make to build Wireshark. + +---- +ninja +# or +make +---- + +Once you have build Wireshark with `ninja` or `make` above, you should be able to test it +by entering `run/wireshark`. + +==== Optional: Install + +Install Wireshark in its final destination: + +---- +make install +---- + +Once you have installed Wireshark with `make install` above, you should be able +to run it by entering `wireshark`. + +==== Optional: Create User’s and Developer’s Guide + +To build the Wireshark User's Guide and the Wireshark Developer's Guide, +build the `all_guides` target, e.g. `make all_guides` or `ninja +all_guides`. Detailed information to build these guides can be found in +the file _doc/README.documentation.adoc_ in the Wireshark sources. + +==== Optional: Create an installable or source code package + +You can create packages using the following build targets and commands: + +Source code tarball:: + Build the `dist` target. + +deb (Debian) package:: + Create a symlink named _debian_ in the top-level source directory to _packaging/debian_, then run `dpkg-buildpackage`. + +RPM package:: + Build the `wireshark_rpm` target. + +https://appimage.org[AppImage] package:: + Build the `wireshark_appimage` target. + +macOS .dmg package containing an application bundle:: + Build the `wireshark_dmg` or `logray_dmg` targets. + +Installable packages typically require building Wireshark first. + +==== Troubleshooting during the build and install on Unix + +A number of errors can occur during the build and installation process. +Some hints on solving these are provided here. + +If the `cmake` stage fails you will need to find out why. You can check the +file `CMakeOutput.log` and `CMakeError.log` in the build directory to find +out what failed. The last few lines of this file should help in determining the +problem. + +The standard problems are that you do not have a required development package on +your system or that the development package isn’t new enough. Note that +installing a library package isn’t enough. You need to install its development +package as well. + +If you cannot determine what the problems are, send an email to the +_wireshark-dev_ mailing list explaining your problem. Include the output from +`cmake` and anything else you think is relevant such as a trace of the +`make` stage. + + +// Retain ChSetupWin32 for backward compatibility +[#ChSetupWindows] +=== Windows + +A quick setup guide for Windows development with recommended configurations. + +[#ChSetupWindowsMSVC] +==== Using Microsoft Visual Studio[[ChSetupWin32]] + +[WARNING] +==== +Unless you know exactly what you are doing, you +should strictly follow the recommendations below. They are known to work +and if the build breaks, please re-read this guide carefully. + +Known traps are: + +. Not using the correct (x64 or x86) version of the Visual Studio command prompt. + +. Not using a supported version of Windows. Please check + https://support.microsoft.com/en-gb/help/13853/windows-lifecycle-fact-sheet[here] + that your installed version is supported and updated. + +==== + +[#ChSetupChocolatey] + +===== Recommended: Install Chocolatey + +https://chocolatey.org/[Chocolatey] is a native package manager for +Windows. There are https://chocolatey.org/packages[packages] for most of +the software listed below. Along with traditional Windows packages it +supports the Python Package Index. + +Chocolatey tends to install packages into its own path (%ChocolateyInstall%), although packages are free to use their own preferences. +You can install Chocolatey packages using the command `choco install` (or its shorthand, `cinst`), e.g. + +[source,cmd] +---- +rem Flex is required. +choco install -y winflexbison3 +rem Git, CMake, Python, etc are also required, but can be installed +rem via their respective installation packages. +choco install -y git cmake python3 +---- + + +[#ChSetupMSVC] + +===== Install Microsoft Visual Studio + +Download and install https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=17[“Microsoft Visual Studio 2022 Community Edition”]. +If you prefer you can instead download and install https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=16[“Microsoft Visual Studio 2019 Community Edition”]. +The examples below are for Visual Studio 2022 but can be adapted for Visual Studio 2019. +These are small utilities that download all the other required parts (which are quite large). + +Check the checkbox for “Desktop development with {cpp}” and then uncheck +all the optional components other than + +* “MSVC ... VS 2022 {cpp}” item with the “... build tools (Latest)” +* “Windows 11 SDK” +* “{cpp} CMake tools for Windows” +* “MSVC ... Spectre-mitigated libs” (optional) + +(unless you want to use them for purposes other than Wireshark). + +You can alternatively use Chocolatey to install Visual Studio, using the Visual Studio Community and Native Desktop workload packages. +Note that this includes Visual Studio’s CMake component. + +---- +choco install -y visualstudio2022community visualstudio2022-workload-nativedesktop +---- + +// winget has basic VS 2022 and 2019 packages, but no native desktop workload packages. +// https://github.com/microsoft/winget-pkgs/tree/master/manifests/m/Microsoft/VisualStudio + +You can use other Microsoft C compiler variants, but VS2022 is used to +build the development releases for Windows and is the preferred option +on Windows. It’s possible to compile Wireshark with a wide range of +Microsoft C compiler variants. For details see <<ChToolsMSChain>>. + +You may have to do this as Administrator. + +It might be possible to build Wireshark using https://clang.llvm.org/docs/MSVCCompatibility.html[clang-cl], but this has not been tested. +Compiling with plain gcc or Clang is not recommended and will certainly not work (at least not without a lot of advanced tweaking). +For further details on this topic, see <<ChToolsGNUChain>>. This may change in future as releases of Visual Studio add more cross-platform support. + +// XXX - mention the compiler and PSDK web installers - +// which significantly reduce download size - and find out the +// required components + +Why is this recommended? +While this is a huge download, the Community Editions of Visual Studio are free (as in beer) and include the Visual Studio integrated debugger. +Visual Studio 2022 is also used to create official Wireshark builds for Windows, so it will likely have fewer development-related problems. + +[#ChSetupQt] + +===== Install Qt + +The main Wireshark application uses the Qt windowing toolkit. To install +Qt, go to the https://www.qt.io/download[“Download Qt” page], select +"Download open source", then "Download Qt Online Installer", and download +"*Qt Online Installer for Windows*". When executing it, sign up or log in, +and use Next button to proceed. When asked, select "*Custom installation*". + +In the "Select Components" page, select your desired Qt version. We recommend +the latest LTS version, and the stable Windows installers currently ship with Qt {qt6-lts-version}. +Select the following components: + +* MSVC 2019 64-bit +* Qt 5 Compatibility Module +* Qt Debug Information Files (contains PDB files which can be used for debugging) +* Under "Additional Libraries" select "Qt Multimedia" to support advanced +controls for playing back streams in the RTP Player dialog +* You can deselect all of the other the components +such as “Qt Charts” or “Android xxxx” as they aren’t required. + +The CMake variable CMAKE_PREFIX_PATH (see `https://doc.qt.io/qt-6/cmake-get-started.html`) should be set as appropriate for your environment and should point to the Qt installation directory, e.g. _C:\Qt{backslash}{qt6-lts-version}\msvc2019_64_ +Alternatively you can also use the environment variable WIRESHARK_QT6_PREFIX_PATH. + +Qt 6 is the default option for building Wireshark, but Wireshark has support for Qt 5.12 and later. To enable Wireshark to build with Qt 5 pass `-DUSE_qt6=OFF` +to cmake. + +[#ChSetupPython] + +===== Install Python + +Get a Python 3 installer from https://python.org/download/[] and install Python. +Its installation location varies depending on the options selected in the installer and on the version of Python that you are installing. +At the time of this writing the latest version of Python is 3.10, and common installation directories are +_C:\Users{backslash}**username**\AppData\Local\Programs\Python\Python310_, _C:\Program Files\Python310_, and _C:\Python310_. + +Alternatively you can install Python using Chocolatey: + +---- +choco install -y python3 +---- + +// Not sure how to document Chocolatey's installation location other than "could be anywhere, LOL" +// https://community.chocolatey.org/packages/python3/#discussion +Chocolatey will likely install Python in one of the locations above, or possibly in _C:\Tools\Python3_. + +// winget has Python 3 packages. +// https://github.com/microsoft/winget-pkgs/tree/master/manifests/p/Python/Python/3 + +[#ChSetupGit] + +===== Install Git + +Please note that the following is not required to build Wireshark but can be +quite helpful when working with the sources. + +Working with the Git source repositories is highly recommended, as described in +<<ChSrcObtain>>. It is much easier to update a personal source tree (local repository) with Git +rather than downloading a zip file and merging new sources into a personal +source tree by hand. It also makes first-time setup easy and enables the +Wireshark build process to determine your current source code revision. + +There are several ways in which Git can be installed. Most packages are +available at the URLs below or via https://chocolatey.org/[Chocolatey]. +Note that many of the GUI interfaces depend on the command line version. + +If installing the Windows version of git select the +_Use Git from the Windows Command Prompt_ (in chocolatey the _/GitOnlyOnPath_ +option). Do *not* select the _Use Git and optional Unix tools from the Windows Command Prompt_ +option (in chocolatey the _/GitAndUnixToolsOnPath_ option). + +====== The Official Windows Installer + +The official command-line installer is available at https://git-scm.com/download/win. + +====== Git Extensions + +Git Extensions is a native Windows graphical Git client for +Windows. You can download the installer from +https://github.com/gitextensions/gitextensions/releases/latest. + +====== TortoiseGit + +TortoiseGit is a native Windows graphical Git +similar to TortoiseSVN. You can download the installer from +https://tortoisegit.org/download/. + +====== Command Line client via Chocolatey + +The command line client can be installed (and updated) using Chocolatey: +---- +choco install -y git +---- + +// winget has git. +// https://github.com/microsoft/winget-pkgs/tree/master/manifests/g/Git/Git + +====== Others + +A list of other GUI interfaces for Git can be found at +https://git-scm.com/downloads/guis + + +[#ChSetupCMake] + +===== Install CMake + +While CMake is required to build Wireshark, it might have been installed as a component of either Visual Studio or Qt. +If that’s the case you can skip this step. +If you do want or need to install CMake, you can get it from https://cmake.org/download/[]. +Installing CMake into the default location is recommended. +Ensure the directory containing cmake.exe is added to your path. + +Alternatively you can install it using Chocolatey: + +---- +choco install -y cmake +---- + +// winget has CMake. +// https://github.com/microsoft/winget-pkgs/tree/master/manifests/k/Kitware/CMake + +Chocolatey ensures cmake.exe is on your path. + +[#ChSetupAsciidoctor] + +===== Install Asciidoctor, Xsltproc, And DocBook + +https://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby script or via a Java wrapper (AsciidoctorJ). +The JavaScript flavor (Asciidoctor.js) isn’t yet supported. +It is used in conjunction with Xsltproc and DocBook to generate the documentation you're reading and the User’s Guide. + +You can install AsciidoctorJ, Xsltproc, and DocBook using Chocolatey. +AsciidoctorJ requires a Java runtime and there are https://en.wikipedia.org/wiki/List_of_Java_virtual_machines[many to choose from]. +Chocolatey doesn't support alternative package dependencies at the present time, including dependencies on Java. +As a result, installing the asciidoctorj package won't automatically install a Java runtime -- you must install one separately. + +---- +choco install -y <your favorite Java runtime> +choco install -y asciidoctorj xsltproc docbook-bundle +---- + +Chocolatey ensures that asciidoctorj.exe and xsltproc.exe is on your +path and that xsltproc uses the DocBook catalog. + +// winget has no Asciidoctor, xsltproc, or DocBook packages. + +===== Install winflexbison + +Get the winFlexBison installer from +https://sourceforge.net/projects/winflexbison/ +and install into the default location. +Ensure the directory containing win_flex.exe is on your path. + +Alternatively you can install Winflexbison using Chocolatey: + +---- +choco install -y winflexbison3 +---- + +Chocolatey ensures win_flex.exe is on your path. + +// winget has no bison package. + +===== Optional: Install Perl + +If needed you can get a Perl installer from +http://strawberryperl.com/ +or +https://www.activestate.com/ +and install Perl into the default location. + +Alternatively you can install Perl using Chocolatey: + +---- +choco install -y strawberryperl +# ...or... +choco install -y activeperl +---- + +// winget has StrawberryPerl. +// https://github.com/microsoft/winget-pkgs/tree/master/manifests/s/StrawberryPerl/StrawberryPerl + +===== Install and Prepare Sources + +[TIP] +.Make sure everything works +==== +It’s a good idea to make sure Wireshark compiles and runs at least once before +you start hacking the Wireshark sources for your own project. This example uses +Git Extensions but any other Git client should work as well. +==== + +*Download sources* Download Wireshark sources into +_C:\Development\wireshark_ using either the command line or Git Extensions: + +Using the command line: + +---- +cd C:\Development +git clone https://gitlab.com/wireshark/wireshark.git +---- + +Using Git extensions: + +. Open the Git Extensions application. By default Git Extensions + will show a validation checklist at startup. If anything needs to + be fixed do so now. You can bring up the checklist at any time + via menu:Tools[Settings]. + +. In the main screen select _Clone repository_. Fill in the following: ++ +Repository to clone: *`https://gitlab.com/wireshark/wireshark.git`* ++ +Destination: Your top-level development directory, e.g. _C:\Development_. ++ +Subdirectory to create: Anything you’d like. Usually _wireshark_. ++ +[TIP] +.Check your paths +==== +Make sure your repository path doesn't contain spaces. +==== + +. Click the btn:[Clone] button. Git Extensions should start cloning the + Wireshark repository. + +[#ChSetupPrepareCommandCom] + +===== Open a Visual Studio Command Prompt + +From the Start Menu (or Start Screen), navigate to the “Visual Studio 2022” folder and choose the https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_prompt_shortcuts[Command Prompt] appropriate for the build you wish to make, e.g. “x64 Native Tools Command Prompt for VS 2022” for a 64-bit version. +Depending on your version of Windows the Command Prompt list might be directly under “Visual Studio 2022” or you might have to dig for it under multiple folders, e.g. menu:Visual Studio 2022[Visual Studio Tools,Windows Desktop Command Prompts]. + +You can set up a build environment in your own command prompt by running the appropriate `vcvars__ARCHITECTURE__.bat` command. +See https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#use-the-developer-tools-in-an-existing-command-window[Use the Microsoft C++ toolset from the command line] for details. + +[TIP] +.Pin the items to the Task Bar +==== +Pin the Command Prompt you use to the Task Bar for easy access. +==== + +All subsequent operations take place in this Command Prompt window. + +. Set environment variables to control the build. ++ +-- +Set the following environment variables, using paths and values suitable for your installation: + +[subs="attributes+"] +---- +rem Let CMake determine the library download directory name under +rem WIRESHARK_BASE_DIR or set it explicitly by using WIRESHARK_LIB_DIR. +rem Set *one* of these. +set WIRESHARK_BASE_DIR=C:\Development +rem set WIRESHARK_LIB_DIR=c:\wireshark-x64-libs +rem Set the Qt installation directory +set WIRESHARK_QT6_PREFIX_PATH=C:\Qt{backslash}{qt6-lts-version}\msvc2019_64 +rem Append a custom string to the package version. Optional. +set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo +---- + +Setting these variables could be added to a batch file to be run after you open +the Visual Studio Tools Command Prompt. + +[TIP] +.Use of Qt’s LTS branch +==== +It is generally recommended to use a LTS ("long term support") version for Qt. The current LTS version for Qt 6 is +{qt6-lts-version}. +==== + +-- + +. Create and change to the correct build directory. +CMake is best used in an out-of-tree build configuration where the build is done in a separate directory from the source tree, leaving the source tree in a pristine state. +64 and 32 bit builds require a separate build directory. +Create (if required) and change to the appropriate build directory. ++ +-- +// XXX Our CI builds are in-tree in <src dir>/build. +---- +mkdir C:\Development\wsbuild64 +cd C:\Development\wsbuild64 +---- +to create and jump into the build directory. + +The build directory can be deleted at any time and the build files regenerated as detailed in <<ChWindowsGenerate>>. +-- + +[#ChWindowsGenerate] + +===== Generate the build files + +CMake is used to process the CMakeLists.txt files in the source tree and produce build files appropriate +for your system. + +You can generate Visual Studio solution files to build either from within Visual Studio, or from the command +line with MSBuild. CMake can also generate other build types but they aren't supported. + +The initial generation step is only required the first time a build directory is created. Subsequent +builds will regenerate the build files as required. + +If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again. + +To generate the build files enter the following at the Visual Studio command prompt: +---- +cmake -G "Visual Studio 17 2022" -A x64 ..\wireshark +---- + +Adjusting the path to the Wireshark source tree as required. +To use a different generator modify the `-G` parameter. +`cmake -G` lists all the CMake supported generators, but only Visual Studio is supported for Wireshark builds. +32-bit builds are no longer supported. + +The CMake generation process will download the required 3rd party libraries (apart from Qt) +as required, then test each library for usability before generating the build files. + +At the end of the CMake generation process the following should be displayed: +---- +-- Configuring done +-- Generating done +-- Build files have been written to: C:/Development/wsbuild64 +---- + +If you get any other output, there is an issue in your environment that must be rectified before building. +Check the parameters passed to CMake, especially the `-G` option and the path to the Wireshark sources and +the environment variables `WIRESHARK_BASE_DIR` and `CMAKE_PREFIX_PATH`. + +[#ChWindowsBuild] + +===== Build Wireshark + +Now it’s time to build Wireshark! + +. If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again. + +. Run ++ +-- +---- +msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln +---- +to build Wireshark. +-- + +. Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the command prompt window + +. Run _C:\Development\wsbuild64\run\RelWithDebInfo\Wireshark.exe_ and make sure it starts. + +. Open menu:Help[About]. If it shows your "private" program +version, e.g.: Version {wireshark-version}-myprotocol123 +congratulations! You have compiled your own version of Wireshark! + +You may also open the Wireshark solution file (_Wireshark.sln_) in the Visual Studio IDE and build there. + +TIP: If compilation fails for suspicious reasons after you changed some source +files try to clean the build files by running `msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln /t:Clean` +and then building the solution again. + +The build files produced by CMake will regenerate themselves if required by changes in the source tree. + +===== Debug Environment Setup + +You can debug using the Visual Studio Debugger or WinDbg. See the section +on using the <<ChToolsDebugger, Debugger Tools>>. + +===== Optional: Create User’s and Developer’s Guide + +To build the Wireshark User's Guide and the Wireshark Developer's Guide, +build the `all_guides` target, e.g. `msbuild all_guides.vcxproj`. +Detailed information to build these guides can be found in the file +_doc\README.documentation.adoc_ in the Wireshark sources. + +===== Optional: Create a Wireshark Installer + +Note: You should have successfully built Wireshark +before doing the following. + +If you want to build your own +_Wireshark-{wireshark-version}-myprotocol123-x64.exe_, you'll need +NSIS. You can download it from http://nsis.sourceforge.net[]. + +Note that the 32-bit version of NSIS will work for both 64-bit and 32-bit versions of Wireshark. +NSIS version 3 is required. + +If you've closed the Visual Studio Command Prompt <<ChSetupPrepareCommandCom,prepare>> it again. Run + +---- +msbuild /m /p:Configuration=RelWithDebInfo wireshark_nsis_prep.vcxproj +msbuild /m /p:Configuration=RelWithDebInfo wireshark_nsis.vcxproj +---- + +to build a Wireshark installer. +If you sign your executables you should do so between the “wireshark_nsis_prep” and “wireshark_nsis” steps. +To sign your installer you should place the signing batch script on the path. It must be named "sign-wireshark.bat". +It should be autodetected by CMake, to always require signing set the -DENABLE_SIGNED_NSIS=On CMake option. + +Run + +---- +packaging\nsis\wireshark-{wireshark-version}-myprotocol123-x64.exe +---- + +to test your new installer. +It’s a good idea to test on a different machine than the developer machine. + +[#ChSetupMSYS2] + +==== Using MinGW-w64 with MSYS2 + +MSYS2 comes with different environments/subsystems and the first thing you +have to decide is which one to use. The differences among the environments +are mainly environment variables, default compilers/linkers, architecture, +system libraries used etc. If you are unsure, go with UCRT64. + +===== Building from source + +. Open the shell for the selected 64-bit environment. + +. Download the Wireshark source code using Git, if you haven't done so already, + and cd into that directory. + +. Install needed dependencies: + + tools/msys2-setup.sh --install-all + +. Build using CMake + Ninja: + + mkdir build && cd build + # Ninja generator is the default + cmake -DENABLE_CCACHE=On -DFETCH_lua=Yes .. + ninja + ninja test # optional, to run the test suite + ninja install # optional, install to the MSYS2 shell path + +The application should be launched using the same shell. + +===== Building an .exe installer + +. Follow the instructions above to compile Wireshark from source. + +. Build the NSIS installer target. + + ninja wireshark_nsis_prep + ninja wireshark_nsis + +If successful the installer can be found in `$CMAKE_BINARY_DIR/packaging/nsis`. + +Alternatively you can also use the PKGBUILD included in the Wireshark +source distribution to compile Wireshark into a binary package that can be +https://www.msys2.org/wiki/Creating-Packages/[installed using pacman]. + +===== Comparison with MSVC toolchain + +The official Wireshark Windows installer is compiled using Microsoft Visual +Studio (MSVC). Currently the MSYS2 build has the following limitations compared to +the build using MSVC: + +* Lua does not have https://github.com/Lekensteyn/lua-unicode[custom UTF-8 patches]. + +* The Event Tracing for Windows (ETW) extcap cannot be compiled using MinGW-w64. + +* Enhanced Kerberos dissection with decryption is not available. + +* AirPcap is not supported. + +[#ChSetupCross] + +==== Cross-compilation using Linux + +It is possible to compile Wireshark for Microsoft Windows using Linux and MinGW. +This way developers can deploy Wireshark on Windows systems without requiring +a Windows host machine. Building for Windows using a Linux host is also +easier for devs already familiar with Linux, the build itself is faster and it +uses a very mature C/C++ compiler (GCC) and debugger (GDB). + +===== Using Fedora Linux + +https://fedoraproject.org/[Fedora Linux] provides the best out-of-the-box +support for MinGW cross-compilation. Fedora is what the project uses to test +the build and it's what we recommend. While any other reasonably modern Linux +distribution can be used, that will make the process more time consuming and +involve some trial and error to setup. + +The build instructions on Fedora follow the familiar recipe for building Wireshark +using Linux. + +====== Building from source + +. Install needed dependencies: + + tools/mingw-rpm-setup.sh --install-all + +. Build using CMake + Ninja: + + mkdir build && cd build + mingw64-cmake -G Ninja -DENABLE_CCACHE=Yes -DFETCH_lua=Yes .. + ninja ++ +Note that currently it is not possible to run the test-suite when cross-compiling. + +. Build the NSIS installer + + ninja wireshark_nsis_prep + ninja wireshark_nsis + +If successful the installer can be found in `$CMAKE_BINARY_DIR/packaging/nsis`. + +====== Notes and comparison with MSVC builds + +* Only the MSVCRT C library for Microsoft Windows can be used. Support for the + UCRT (Universal C Runtime) library on Fedora Linux is in the initial stages of + deployment and not ready for prime-time (at the time of this writing). + +* Some optional dependencies are missing from Fedora repositories and must be + compiled from source if desired. An up-to-date complete list can be found in + the bug tracker (https://gitlab.com/wireshark/wireshark/-/issues/19108[issue 19108]). + +* Lua does not have https://github.com/Lekensteyn/lua-unicode[custom UTF-8 patches]. + +* The Event Tracing for Windows (ETW) extcap cannot be compiled using MinGW-w64. + +* Enhanced Kerberos dissection with decryption is not available. + +* AirPcap is not supported. + +===== Using Arch Linux + +https://archlinux.org/[Arch Linux] has good support for MinGW using packages +from the https://aur.archlinux.org/[AUR]. Note that the mingw-w64 AUR packages +sometimes break. If that happens you may be required to fix it or skip the +package until it is fixed by the maintainer, if it's an optional dependency. +You may also want to consider using an +https://wiki.archlinux.org/title/unofficial_user_repositories[unofficial user repository] +(such as the https://martchus.no-ip.biz/repo/arch/ownstuff/[ownstuff] repository) +to provide pre-compiled packages. This will greatly simplify the initial setup +and subsequent upgrades. + +CAUTION: AUR packages and unofficial user repositories are user-produced +content. These packages are completely unofficial and have not been thoroughly +vetted. It is your decision whether to trust their maintainers and you take +full responsibility for choosing to use them. + +You will need to install an https://wiki.archlinux.org/title/AUR_helpers[AUR helper]. +This guide assumes `paru` is being used. + +. Install required dependencies from official repositories: + + pacman -S mingw-w64 nsis lemon qt6-tools ccache + +. Install required dependencies from the AUR: + + paru -S mingw-w64-cmake + paru -S mingw-w64-glib2 + paru -S mingw-w64-libgcrypt + paru -S mingw-w64-c-ares + paru -S mingw-w64-speexdsp + paru -S mingw-w64-libpcap + +. Install Qt6: + + paru -S mingw-w64-qt6-base mingw-w64-qt6-5compat mingw-w64-qt6-multimedia + +. Install optional dependencies: + + paru -S mingw-w64-gnutls + paru -S mingw-w64-lz4 + paru -S mingw-w64-snappy + paru -S mingw-w64-opus + paru -S mingw-w64-opencore-amr + paru -S mingw-w64-libxml2 + paru -S mingw-w64-libnghttp2 + paru -S mingw-w64-libssh + paru -S mingw-w64-minizip ++ +Search the AUR for other dependencies not listed above. + +. Build Wireshark using CMake + Ninja. From the directory containing the + Wireshark source tree run: + + mkdir build && cd build + x86_64-w64-mingw32-cmake -G Ninja -DENABLE_CCACHE=Yes -DFETCH_lua=Yes \ + -DMINGW_SYSROOT=/usr/x86_64-w64-mingw32 .. + ninja ++ +This will automatically download and build Lua as a static library. ++ +To reconfigure the CMake build you may to do it explicitly by running +`x86_64-w64-mingw32-cmake .` in the build directory, +instead of letting `ninja` do it for you automatically. + +. Build the NSIS installer + + ninja wireshark_nsis_prep + ninja wireshark_nsis + +If everything goes well the installer can be found in `$CMAKE_BINARY_DIR/packaging/nsis`. + +The same notes as the build using Fedora apply. |