2.2. UN*X
Prev | Chapter 2. Setup and Build Instructions | Next

## 2.2. UN*X

### 2.2.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 (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

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

#### 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 /opt/wireshark-third-party or wireshark-libraries at the same level as your Wireshark source code directory. We recommend this instead of using Homebrew’s libraries, since it’s easy, it’s what we use to create the official packages, and our pre-built libraries are universal and support older versions of macOS.

You can use `tools/macos-setup-brew.sh` to install CMake, Ninja, and other tools required to build Wireshark using the Homebrew package manager, and optionally to install third party libraries as an alternative to setting `WIRESHARK_BASE_DIR`.

- `--install-required` install third party libraries required to build Wireshark. Not needed if you set `WIRESHARK_BASE_DIR`.
- `--install-optional` install optional third party libraries. Not needed if you set `WIRESHARK_BASE_DIR`.
- `--install-dmg-deps` install packages required to build the .dmg file
- `--install-sparkle-deps` install the Sparkle automatic updater. Not needed if you set `WIRESHARK_BASE_DIR`.
- `--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

Running `tools/macos-setup-brew.sh` with no options will install CMake, Ninja, pgkconf, and ccache.

In the past, `tools/macos-setup.sh` could be used to build third party libraries locally. It is now deprecated, and can only be used to install the tools required to build Wireshark or to remove any previously installed libraries. It supports the following options:

- `-n` dry run; don’t build or install any tools
- `-p` specify the installation prefix; /usr/local is the default
- `-u` uninstall packages

You will also have to 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 your desired Qt version. We recommend using the same Qt version used to build the official Wireshark packages, which at the time of this writing is Qt 6.10.3. Select the following components:

- Desktop
- Qt 5 Compatibility Module
- Qt Debug Information Files (contains dSYM files which can be used for debugging)

Optionally, under "Additional Libraries" also select the following components:

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

If you don’t want register for the Qt Online Installer for macOS, you can install Qt from the command line using Another (unofficial) Qt CLI Installer. The AQt command to install Qt and the modules recommended above would look something like the following:

    aqt install-qt mac desktop 6.10.3 clang_64 --modules qt5compat qtmultimedia debug_info

### 2.2.2. Building

Before building:

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

    CMAKE_PREFIX_PATH=/Users/your_username/Qt/6.10.3/macos
    export CMAKE_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.

| Tip
Wireshark ships a `CMakePresets.json` with a `ninja_ccache` preset that configures Ninja and ccache for you. Run `cmake --preset ninja_ccache` to use it. You can override the build directory or other settings by creating a `CMakeUserPresets.json` — see Section 4.3, “CMake” for details.

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. Some notable options include:

Option | Description
--- | ---
`-DCUSTOM_SLIDES_JSON=/path/to/slides.json` | Inject custom welcome page banner slides at build time. See Section 15.3, “Welcome Page Banner Slides”.

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.2.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.2.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 doc/README.documentation.adoc in the Wireshark sources.

### 2.2.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 named debian 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 `stratoshark_dmg` targets.

Installable packages typically require building Wireshark first.

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

Prev | Up | Next
Chapter 2. Setup and Build Instructions | Home | 2.3. Windows