4.3. CMake
Prev | Chapter 4. Tool Reference | Next

## 4.3. CMake

Wireshark’s build environment can be configured using CMake on various UNIX-like platforms, including Linux, macOS, and *BSD, and on Windows. CMake is designed to support out-of-tree builds - so much so that in-tree builds do not work properly in all cases. Along with being cross-platform, CMake supports many build tools and environments including traditional make, Ninja, and MSBuild.

Building with CMake typically includes creating a build directory and specifying a generator, aka a build tool. For example, to build Wireshark using Ninja in the directory wireshark-ninja you might run the following commands:

    # Starting from your Wireshark source directory, create a build directory
    # alongside it.
    $ cd ..
    $ mkdir wireshark-ninja
    $ cd wireshark-ninja
    # Assumes your source directory is named "wireshark".
    $ cmake -G Ninja ../wireshark
    $ ninja (or cmake --build .)

Using CMake on Windows is described further in Section 2.3.1.9, “Generate the build files”.

Along with specifying a generator with the `-G` flag you can set variables using the `-D` flag. Useful variables and generators include the following:

-DBUILD_wireshark=OFF
  Don’t build the Wireshark GUI application. Each command line utility has its own BUILD_xxx flag as well. For example, you can use -DBUILD_mmdbresolve=OFF to disable mmdbresolve.
-DENABLE_CCACHE=ON
  Build using the ccache compiler cache.
-DENABLE_CAP=OFF
  Disable the POSIX capabilities check
-DCMAKE_BUILD_TYPE=Debug
  Enable debugging symbols
-DCARES_INCLUDE_DIR=/your/custom/cares/include, -DCARES_LIBRARY=/your/custom/cares/lib/libcares.so
  Let you set the path to a locally-compiled version of c-ares. Most optional libraries have xxx_INCLUDE_DIR and xxx_LIB flags that let you control their discovery.
-DCMAKE_OSX_DEPLOYMENT_TARGET=12.0
  Specify the minimum macOS version for Wireshark and each command line utility. Note that this doesn’t affect the minimum target for third-party libraries.
-DENABLE_APPLICATION_BUNDLE=OFF
  Disable building an application bundle (Wireshark.app) on macOS

You can list all build variables (with help) by running `cmake -LH [options] ../<Name_of_WS_source_dir>`. This lists the cache of build variables after the cmake run. To only view the current cache, add option `-N`.

Depending on your needs, it might be useful to save your CMake configuration options in a file outside your build directory. CMake supports this via its presets option.

Wireshark ships a `CMakePresets.json` with a predefined `ninja_ccache` preset that uses Ninja as the generator and enables ccache. This preset sets the build directory to `${sourceDir}/build`. You can use it directly:

    cmake --preset ninja_ccache
    cmake --build build

To customize the build directory or other settings without modifying the shared `CMakePresets.json`, create a `CMakeUserPresets.json` file in the source root (it is already listed in `.gitignore`). Use `inherits` to extend the shipped preset and override only what you need.

For example, on macOS or Linux, to use an out-of-tree build directory, enable ccache and set a custom Qt path:

    {
      "version": 4,
      "configurePresets": [
        {
          "name": "mydev",
          "displayName": "Local development",
          "inherits": "ninja_ccache",
          "binaryDir": "${sourceDir}/../build",
          "cacheVariables": {
            "ENABLE_CCACHE": "ON"
          },
          "environment": {
            "CMAKE_PREFIX_PATH": "/usr/local/Qt6"
          }
        }
      ]
    }

On Windows, you might want to use the Visual Studio generator and a different build directory instead. The `inherits` field still pulls in cache variables like `ENABLE_CCACHE` from the base preset, while letting you override the generator and build path:

    {
      "version": 4,
      "configurePresets": [
        {
          "name": "vs-dev",
          "displayName": "Visual Studio development",
          "inherits": "ninja_ccache",
          "generator": "Visual Studio 18 2026",
          "binaryDir": "C:/build"
        }
      ]
    }

Then configure and build using your preset:

    cmake --preset mydev
    cmake --build ../build

If you use VSCode with the CMake Tools extension, select your preset via the command palette (CMake: Select Configure Preset) or set it in `.vscode/settings.json`:

    {
      "cmake.configurePreset": "mydev"
    }

| Note
When a configure preset is active, CMake Tools uses the preset’s `binaryDir` and ignores the `cmake.buildDirectory` setting.

After running cmake, you can always run `make help` to see a list of all possible make targets.

Note that CMake honors user umask for creating directories as of now. You should set the umask explicitly before running the `install` target.

CMake links:

The home page of the CMake project: https://cmake.org/

Official documentation: https://cmake.org/documentation/

About CMake in general and why KDE4 uses it: https://lwn.net/Articles/188693/

Useful variables: https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/Useful-Variables

Frequently Asked Questions: https://gitlab.kitware.com/cmake/community/wikis/FAQ

### 4.3.1. CMake Idioms

If you will be creating or editing CMake files, you will need to be aware of some idioms in use in the Wireshark source code.

| When in doubt, check the source
As with most open-source software, this documentation can fall behind what’s actually in use. Check the root CMakeLists.txt file and the files in cmake/modules/ to see the most current information.

Library dependencies. Most dependencies are imported via the CMake find_package() command. The mechanics of finding a particular package foo are often specified in the relevant cmake/modules/FindFoo.cmake file, but they will usually define a variable FOO_INCLUDE_DIRS for helping future CMake commands find the foo header files, along with a FOO_LIBRARIES variable listing the compiled library files for linking. Both variables will be empty if the corresponding dependency is not found.

Most dependencies are intuitively named, but there are some exceptions:

- Lib prefix: Most libraries do not have any added prefix to their names. LIBXML2 and LIBSSH are two notable exceptions.
- Mathematics: The name of this library is simply M (M_INCLUDE_DIRS, M_LIBRARIES).
- Netlink: The name of this library is NL.

Prev | Up | Next
4.2. Chocolatey | Home | 4.4. GNU Compiler Toolchain (UNIX And UNIX-like Platforms)