2.2. Windows: Using Microsoft Visual Studio

A quick setup guide for Windows development with recommended configurations.

[Warning]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:

  1. Not using the correct (x64 or x86) version of the Visual Studio command prompt.
  2. Not using a supported version of Windows. Please check here that your installed version is supported and updated.

2.2.1. Recommended: Install Chocolatey

Chocolatey is a native package manager for Windows. There are 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.

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

2.2.2. Install Microsoft Visual Studio

Download and install “Microsoft Visual Studio 2022 Community Edition”. If you prefer you can instead download and install “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 C++” and then uncheck all the optional components other than

  • “MSVC …​ VS 2022 C++” item with the “…​ build tools (Latest)”
  • “Windows 11 SDK”
  • “C++ CMake tools for Windows"

(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

You can use other Microsoft C compiler variants, but VS2022 is used to build the development releases and is the preferred option. It’s possible to compile Wireshark with a wide range of Microsoft C compiler variants. For details see Section 4.5, “Microsoft compiler toolchain (Windows native)”.

You may have to do this as Administrator.

Compiling with 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 Section 4.4, “GNU Compiler Toolchain (UNIX And UNIX-like Platforms)”. This may change in future as releases of Visual Studio add more cross-platform support.

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, so it will likely have fewer development-related problems.

2.2.3. Install Qt

The main Wireshark application uses the Qt windowing toolkit. To install Qt, go to the “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 6.5.3. 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\6.5.3\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.

2.2.4. 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\username\AppData\Local\Programs\Python\Python310, C:\Program Files\Python310, and C:\Python310.

Alternatively you can install Python using Chocolatey:

choco install -y python3

Chocolatey will likely install Python in one of the locations above, or possibly in C:\Tools\Python3.

2.2.5. 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 Section 3.4, “Obtaining The Wireshark Sources”. 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 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).

2.2.5.1. The Official Windows Installer

The official command-line installer is available at https://git-scm.com/download/win.

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

2.2.5.3. TortoiseGit

TortoiseGit is a native Windows graphical Git similar to TortoiseSVN. You can download the installer from https://tortoisegit.org/download/.

2.2.5.4. Command Line client via Chocolatey

The command line client can be installed (and updated) using Chocolatey:

choco install -y git

2.2.5.5. Others

A list of other GUI interfaces for Git can be found at https://git-scm.com/downloads/guis

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

Chocolatey ensures cmake.exe is on your path.

2.2.7. Install Asciidoctor, Xsltproc, And DocBook

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

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

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

2.2.10. 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:

  1. 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 ToolsSettings.
  2. 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.

  3. Click the Clone button. Git Extensions should start cloning the Wireshark repository.

2.2.11. Open a Visual Studio Command Prompt

From the Start Menu (or Start Screen), navigate to the “Visual Studio 2022” folder and choose the 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. Visual Studio 2022Visual Studio ToolsWindows Desktop Command Prompts.

You can set up a build environment in your own command prompt by running the appropriate vcvarsARCHITECTURE.bat command. See 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.

  1. Set environment variables to control the build.

    Set the following environment variables, using paths and values suitable for your installation:

    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\6.5.3\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 6.5.3.

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

    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 Section 2.2.12, “Generate the build files”.

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

2.2.13. Build Wireshark

Now it’s time to build Wireshark!

  1. If you’ve closed the Visual Studio Command Prompt prepare it again.
  2. Run

    msbuild /m /p:Configuration=RelWithDebInfo Wireshark.sln

    to build Wireshark.

  3. Wait for Wireshark to compile. This will take a while, and there will be a lot of text output in the command prompt window
  4. Run C:\Development\wsbuild64\run\RelWithDebInfo\Wireshark.exe and make sure it starts.
  5. Open HelpAbout. If it shows your "private" program version, e.g.: Version 4.3.0-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]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.

2.2.14. Debug Environment Setup

You can debug using the Visual Studio Debugger or WinDbg. See the section on using the Debugger Tools.

2.2.15. 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 docbook\README.adoc in the Wireshark sources.

2.2.16. Optional: Create a Wireshark Installer

Note: You should have successfully built Wireshark before doing the following.

If you want to build your own Wireshark-4.3.0-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 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.