## 2.2. Win32/64: Step-by-Step Guide

A quick setup guide for Win32 and Win64 with recommended configuration.

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 (x86 or x64) version of the Visual Studio command prompt. Not copying/downloading the correct version of vcredist_xYY.exe.

### 2.2.1. Install Microsoft C compiler and SDK

You need to install, in exactly this order:

Select the "Custom" install and then uncheck all the optional components other than "Common Tools for Visual C++ 2015" (unless you want to use them for purposes other than Wireshark).

You can use Chocolatey to install Visual Studio, to correctly configure the installation, copy the deployment XML file msvc2015AdminDeployment.xml from the source code tools directory and pass the path the file to the chocolatey install command:

PS$>choco install -y VisualStudio2015Community --timeout 0 -package-parameters "--AdminFile path\to\msvc2015AdminDeployment.xml" You can use other Microsoft C compiler variants, but VS2015 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.5, “Ninja”. 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.5, “GNU compiler toolchain (UNIX and UNIX-like platforms only)”. 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, Visual Studio 2015 Community Edition is the only free (as in beer) versions that includes the Visual Studio integrated debugger. Visual Studio 2015 is also used to create official Wireshark builds, so it will likely have fewer development-related problems. ### 2.2.2. Install Qt The main Wireshark application uses the Qt windowing toolkit. To install Qt download the Qt Online Installer for Windows from the Qt Project "Download Open Source" page and select a component that matches your target system and compiler. For example, the “msvc2015 64-bit” component is used to build the official 64-bit packages. You can deselect all the Qt xxxx (e.g. Qt Charts) components as they aren’t required. Note that installation of separate Qt components are required for 32 bit and 64 bit builds, e.g. “msvc2015 32-bit” and “msvc2015 64-bit”. The environment variable QT5_BASE_DIR should be set as appropriate for your environment and should point to the Qt directory that contains the bin directory, e.g. C:\Qt\5.9.1\msvc2015_64 The Qt maintenance tool (C:\Qt\MaintenanceTool.exe) can be used to upgrade Qt to newer versions. ### 2.2.3. 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 and Cygwin. Chocolatey tends to install packages into its own path (%ChocolateyInstall%). In most cases this is OK, but in some instances (Python in particular) this might not be what you want. You can install Chocolatey packages using the command choco install. > rem Flex and Bison are required. > choco install -y winflexbison > rem Git, CMake, Perl, Python, etc are also required, but can be installed > rem via their respective installation packages. > choco install -y git cmake > rem Choose one of Strawberry... > choco install -y strawberryperl > rem ...or ActiveState Perl > choco install -y activeperl > rem This will likely install Python in a non-standard location, but > rem should otherwise work. > choco install -y python3 ### 2.2.4. Optional: Install Cygwin On 32-bit Windows, download the 32-bit Cygwin installer and start it. On 64-bit Windows, download the 64-bit Cygwin installer and start it. Cygwin is no longer required In the past the Wireshark development toolchain depended on Cygwin, but it it no longer required. Although you can often use the Cygwin version of a particular tool for Wireshark development that’s not always the case. At the "Select Packages" page, you’ll need to select some additional packages which are not installed by default. Navigate to the required Category/Package row and, if the package has a "Skip" item in the "New" column, click on the "Skip" item so it shows a version number for: • Devel/bison (or install Win flex-bison — see Chocolatey above) • Devel/flex (or install Win flex-bison — see Chocolatey above) • Devel/git (recommended, but it’s also available via Chocolatey — see the Git discussion below) • Interpreters/perl • Utils/patch (only if needed) (may be Devel/patch instead) • Text/docbook-xml45 (only needed if you’re building the documenation) You might also have to install • Interpreters/m4 if installing Devel/bison doesn’t provide a working version of Bison. If m4 is missing bison will fail. After clicking the button several times, the setup will then download and install the selected packages (this may take a while). Alternatively you can install Cygwin and its packages using Chocolatey: PS$>choco install -y cygwin
PS$>choco install -y cyg-get Chocolatey installs Cygwin in C:\tools\cygwin by default. You can directly download packages via cyg-get PS$>cyg-get docbook-xml45 [...]

### 2.2.5. Install Python

Get the Python 3.5 or 2.7 installer from http://python.org/download/ and install Python into the default location (C:\Python35 or C:\Python27).

Why is this recommended? Cygwin’s /usr/bin/python is a Cygwin-specific symbolic link which cannot be run from Windows. The native package is faster as well.

Alternatively you can install Python using Chocolatey:

PS$>choco install -y python3 or PS$>choco install -y python2

Chocolatey installs Python in C:\tools\python3 and C:\tools\python2 by default.

### 2.2.6. 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.3, “Obtain 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.6.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.6.4. Command Line client via Chocolatey

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

PS$> choco install -y git #### 2.2.6.5. Others A list of other GUI interfaces for Git can be found at https://git-scm.com/downloads/guis ### 2.2.7. Install CMake Get the CMake installer from https://cmake.org/download/ and install CMake into the default location. Ensure the directory containing cmake.exe is added to your path. Alternatively you can install CMake using Chocolatey: PS$>choco install -y cmake

Chocolatey ensures cmake.exe is on your path.

### 2.2.8. Install Asciidoctor, Xsltproc, And DocBook

Asciidoctor can be run directly as a Ruby script or via a Java wrapper (AsciidoctorJ). It is used in conjunction with Xsltproc and DocBook to generate the documenation you’re reading and the User’s Guide.

The easiest way to install them on Windows is via Chocolatey:

PS\$>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.9. Install and Prepare Sources

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.

Using the command line:

>cd C:\Development
>git clone https://code.wireshark.org/review/wireshark

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://code.wireshark.org/review/wireshark

Destination: Your top-level development directory, e.g. C:\Development.

Subdirectory to create: Anything you’d like. Usually wireshark.

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

### 2.2.10. Open a Visual Studio Command Prompt

From the Start Menu (or Start Screen), navigate to the ‘Visual Studio 2015’ folder and choose the Command Prompt appropriate for the build you wish to make, e.g. ‘VS2015 x64 Native Tools Command Prompt’ for a 64-bit version or ‘VS2015 x86 Native Tools Command Prompt’ for a 32-bit version. Depending on your version of Windows the Command Prompt list might be directly under ‘Visual Studio 2015’ or you might have to dig for it under multiple folders, e.g. ‘Visual Studio 2015 → Visual Studio Tools → Windows Desktop Command Prompts’.

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-win64-libs
> rem Set the Qt installation directory
> set QT5_BASE_DIR=C:\Qt\5.9.1\msvc2015_64
> rem Append a custom string to the package version. Optional.
> set WIRESHARK_VERSION_EXTRA=-YourExtraVersionInfo

If your Cygwin installation path is not automatically detected by CMake, you can explicitly specify it with the following environment variable:

> rem Chocolatey installs Cygwin in an odd location
> set WIRESHARK_CYGWIN_INSTALL_PATH=C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin

If you are using a version of Visual Studio earlier than VS2012 then you must set an additional env var, e.g. for VS2010 set the following:

> set VisualStudioVersion=10.0

Setting these variables could be added to a batch file to be run after you open the Visual Studio Tools Command Prompt.

Tip Qt 5.9 is a "long term support" branch of Qt5. We recommend using it to compile Wireshark on Windows.
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 to the source tree, leaving the source tree in a pristine state. 32 and 64 bit builds require a separate build directory. Create (if required) and change to the appropriate build directory.

> mkdir C:\Development\wsbuild32
> cd C:\Development\wsbuild32

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

### 2.2.11. 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 14 2015" ..\wireshark

Adjusting the paths as required to Python and the wireshark source tree. 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.

To build an x64 version, the -G parameter must have a Win64 suffix, e.g. -G "Visual Studio 14 2015 Win64":

> cmake -G "Visual Studio 14 2015 Win64" ..\wireshark

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

If you get any other output, there is an issue in your envirnment 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 QT5_BASE_DIR.

### 2.2.12. 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\wsbuild32\run\RelWithDebInfo\Wireshark.exe and make sure it starts.
5. Open HelpAbout. If it shows your "private" program version, e.g.: Version 2.9.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 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.13. Debug Environment Setup

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

### 2.2.14. Optional: Create User’s and Developer’s Guide

Detailed information to build these guides can be found in the file docbook\README.adoc in the Wireshark sources.

### 2.2.15. Optional: Create a Wireshark Installer

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

If you want to build your own Wireshark-win32-2.9.0-myprotocol123.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 32-bit and 64-bit versions of Wireshark. NSIS v3 is required.

Note: If you do not yet have a copy of vcredist_x86.exe or vcredist_x64.exe in ./wireshark-winXX-libs (where XX is 32 or 64) you will need to download the appropriate file and place it in ./wireshark-winXX-libs before starting this step.

If building an x86 version using a Visual Studio “Express” edition or an x64 version with any edition, then you must have the appropriate vcredist file for your compiler in the support libraries directory (vcredist_x86.exe in wireshark-32-libs or vcredist_x64.exe in wireshark-win64-libs).

The files can be located in the Visual Studio install directory for non-Express edition builds, or downloaded from Microsoft for Expresss edition builds.

Note you must use the correct version of vcredist for your compiler, unfortunately they all have the same name (vcredist_x86.exe or vcredist_x64.exe). You can use Windows Explorer and examine the ‘Properties → Details’ tab for a vcredist file to determine which compiler version the file is for use with.

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

Run

> msbuild /m /p:Configuration=RelWithDebInfo nsis_package_prep.vcxproj
> msbuild /m /p:Configuration=RelWithDebInfo nsis_package.vcxproj

to build a Wireshark installer. If you sign your executables you should do so between the “nsis_package_prep” and “nsis_package” steps.

Run

> packaging\nsis\wireshark-win64-{wireshark-version}-myprotocol123.exe

to test your new installer. It’s a good idea to test on a different machine than the developer machine. Note that if you’ve built an x86 version, the installer name will contain “win32”.