// 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 https://ninja-build.org/[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 (not recommended)
* `--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 (not recommended)
* `--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.

As with Windows we provide pre-built third party libraries which will be automatically installed if you set the WIRESHARK_BASE_DIR CMake variable to a directory that is writable by you, such as _wireshark-third-party_ at the same level as your Wireshark source code directory.
You can alternatively use two scripts to install the packages and libraries required to build Wireshark and its documentation:
`tools/macos-setup-brew.sh`, which will use the https://brew.sh/[Homebrew] package manager and `tools/macos-setup.sh`, which will build any required libraries and tools locally, except for Qt 6.

`tools/macos-setup-brew.sh` supports the following options:

* `--install-required` install third party libraries required to build Wireshark
* `--install-optional` install optional third party libraries
* `--install-dmg-deps` install packages required to build the .dmg file
* `--install-sparkle-deps` install the Sparkle automatic updater
* `--install-all` install everything
* `--install-stratoshark` install libraries required to build Stratoshark and the Falco Events plugin
* `[other]` other options are passed as-is to brew

`tools/macos-setup.sh` supports the following options:

* `-n` dry run; don't build or install any packages
* `-p` specify the installation prefix; _/usr/local_ is the default
* `-t` specify the minimum macOS target version
* `-u` uninstall packages

We recommend `tools/macos-setup-brew.sh` if you're using Homebrew and you don't need to worry about backward compatibility with older macOS releases.

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 {macos-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/{macos-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 `stratoshark_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 arm64) 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”].
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 {windows-qt6-lts-version}.
Select the following components:

* MSVC 2022 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}{windows-qt6-lts-version}\msvc2022_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.

====== Install Qt using AQt

If you don't want register for the Qt Online Installer for Windows, an alternate possibility can be to use https://github.com/miurahr/aqtinstall/releases[Another (unofficial) Qt CLI Installer].

To achieve the recommended configuration above, download the latest release and copy `aqt.exe` into _C:\Qt{backslash}_.

Then just run the following command to launch the installation.

[subs="attributes+"]
----
.\aqt.exe install-qt windows desktop {windows-qt6-lts-version} win64_msvc2022_64 -m qt5compat debug_info qtmultimedia
----

[#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.

[#ChSetupXsltproc]

===== Install Xsltproc

Asciidoctor, xsltproc, and DocBook are required to build the documentation.
CMake will download a pre-built version of Asciidoctor and DocBook on Windows, but xsltproc must be installed manually.
You can install it using Chocolatey:

----
choco install -y xsltproc
----

// 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.

===== Only if needed: Install Perl

As discussed in the <<ChToolsWindowsPerl,Tool Reference>>, you should avoid installing Perl on Windows unless you have a specific need for it.

If you do need Perl you can get an installer from
https://strawberryperl.com/
or
https://www.activestate.com/
and install it 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 `vcvarsall.bat` or `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.
If you're working from a PowerShell prompt you need to ensure that any environment variables set by the batch script are propagated back to your PowerShell environment:

// https://help.appveyor.com/discussions/questions/18777-how-to-use-vcvars64bat-from-powershell
// https://gitlab.kitware.com/cmake/cmake/-/blob/master/.gitlab/ci/vcvarsall.ps1
[subs="attributes+"]
----
cmd.exe /c "call `"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsarm64.bat`" && set" | Foreach-Object { if ($_ -match "^(.*?)=(.*)$") { Set-Content "env:\$($matches[1])" $matches[2] } }
----

[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}{windows-qt6-lts-version}\msvc2022_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
{windows-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 doc\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 ..
    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.


[#ChSetupWSL2]

==== Using WSL2 on a Windows Host (Beginner Friendly)

Using WSL2 on a Windows machine can provide a quick and easy way for beginners
to get started. This section will focus on using the official Debian
distribution installed from the `wsl` CLI command or Windows App Store.

This will allow for a quick and easy way to build Wireshark. Please note
that while this guide is sufficient for an environment to build and test minor changes,
some changes and enhancements will still need to be built and tested for Windows
as described in the sections above.

To install WSL2 for the first time and Debian via the CLI run (as administrator):

  wsl --install
  wsl --install -d Debian

https://learn.microsoft.com/en-us/windows/wsl/install[Please see the documentation on WSL for help with installation.]

From here following the build guide for Debian based Un*x systems should finish
the setup of the build environment. See <<ChSetupUNIX>> for
details on compiling, building, and running Wireshark on Debian. WSL2 supports
both X11 and Wayland to enable the use of GUI applications without any additional
requirements. Please see the https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-appsp[WSL2 reference of GUIs for more detail.]

[NOTE]
.For First Time Contributors
====
It is highly recommended to review the source control process before attempting
to build any changes.

Please see:

  - <<ChSrcGit>>
  - <<ChSrcGitUpdate>>
  - <<ChSrcContribute>>

For a description of the process.
====

[#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.

===== 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-libxml2
  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-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.