Chapter 2. Setup and Build Instructions

Table of Contents

2.1. UN*X
2.1.1. Build environment setup
2.1.2. Building
2.1.3. Optional: Install
2.1.4. Optional: Create User’s and Developer’s Guide
2.1.5. Optional: Create an installable or source code package
2.1.6. Troubleshooting during the build and install on Unix
2.2. Windows: Using Microsoft Visual Studio
2.2.1. Recommended: Install Chocolatey
2.2.2. Install Microsoft Visual Studio
2.2.3. Install Qt
2.2.4. Install Python
2.2.5. Install Git
2.2.6. Install CMake
2.2.7. Install Asciidoctor, Xsltproc, And DocBook
2.2.8. Install winflexbison
2.2.9. Optional: Install Perl
2.2.10. Install and Prepare Sources
2.2.11. Open a Visual Studio Command Prompt
2.2.12. Generate the build files
2.2.13. Build Wireshark
2.2.14. Debug Environment Setup
2.2.15. Optional: Create User’s and Developer’s Guide
2.2.16. Optional: Create a Wireshark Installer
2.3. Windows: Using MinGW-w64 with MSYS2
2.3.1. Building from source
2.3.2. Building an .exe installer
2.3.3. Comparison with MSVC toolchain
2.4. Windows: Cross-compilation using Linux
2.4.1. Using Fedora Linux
2.4.2. Using Arch Linux

2.1. UN*X

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

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

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

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

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

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

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

2.1.2. Building

Before building:

On macOS, you will need to set the Qt installation directory in the environment:

WIRESHARK_QT6_PREFIX_PATH=~/Qt/6.5.3/macos
export WIRESHARK_QT6_PREFIX_PATH

If you want to append a custom string to the package version, run the command

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

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.

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

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

2.1.5. 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 in the top-level source directory to packaging/debian, then run dpkg-buildpackage.
RPM package
Build the wireshark_rpm target.
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.

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