2.2. Win32: Step-by-Step Guide

A quick setup guide for Win32 with recommended configuration.

[Warning]Warning!

Unless you know exactly what you are doing, you should strictly follow the recommendations!

2.2.1. Install Microsoft C compiler and Platform SDK

You need to install:

  1. C compiler: Download and install "Microsoft Visual C++ 2008 Express Edition." (This is a very large download.)

Install MSVC the usual way. Don't forget to install vcvars32.bat or call it manually before building Wireshark. vcvars32.bat will set some required environment (e.g. the PATH) settings.

[Tip]You can use other Microsoft C compiler variants!

It's possible to compile Wireshark with a wide range of Microsoft C compiler variants. For details see Section 4.4, “Microsoft compiler toolchain (Win32 native)”!

[Warning]Don't use Cygwin's gcc!

Using cygwin's gcc is not recommended and will certainly not work (at least without a lot of advanced tweaking). For further details on this topic, see Section 4.3, “GNU compiler toolchain (UNIX or Win32 Cygwin)”.

XXX - mention the compiler and PSDK web installers - which significantly reduce download size - and find out the required components

Wireshark development depends on several environment variables, particularly PATH. You can use a batch script to fill these in, for example

          @echo off
echo Adding things to the path...
set PATH=%PATH%;.
set PATH=%PATH%;c:\cygwin\bin

echo Setting up Visual Studio environment...
call "c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat"

title Command Prompt (VC++ 2008)
        

Why is this recommended? While this is a huge download, the 2008 Express Edition is the only free (as in beer) version that includes the Visual Studio integrated debugger. Visual C++ 2008 is also used to create official Wireshark builds, so it will likely have fewer development-related problems.

2.2.2. Install Cygwin

Download the cygwin installer and start it.

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 click on the "Skip" item in the "New" column so it shows a version number for:

  • Archive/unzip

  • Devel/bison

  • Devel/flex

  • Interpreters/perl

  • Utils/patch

  • Web/wget

After clicking the Next button several times, the setup will then download and install the selected packages (this may take a while).

Why this is recommended: Cygwin's bash version is required, as no native Win32 version is available. As additional packages can easily be added, the perl and alike packages are also used.

2.2.3. Install Python

Get the python 2.6 installer from: http://python.org/download/ and install Python into the default location (C:/Python26).

Why this is recommended: Cygwin's Python package doesn't work on some machines, so the Win32 native package is recommended.

2.2.4. Install Subversion Client

Please note that the following is not required to build Wireshark, but can be quite helpful when working with the sources.

Why this is recommended: updating a personal source tree is significantly easier to do with Subversion than downloading a zip file and merging new sources into a personal source tree "by hand".

2.2.4.1. Subversion

If you want to work with the Wireshark Subversion source repositories (which is highly recommended, see Section 3.3, “Obtain the Wireshark sources”), it's recommended to install Subversion. This makes the first time setup easy and enables the Wireshark build process to determine your current source code revision. You can download the setup from http://subversion.tigris.org/ and simply install it.

2.2.4.2. TortoiseSVN

If you want to work with the Wireshark Subversion source repositories (which is highly recommended, see Section 3.3, “Obtain the Wireshark sources”), it's recommended to use TortoiseSVN for your everyday work. You can download the setup from http://tortoisesvn.tigris.org/ and simply install it.

2.2.5. Install and Prepare Sources

[Tip]Tip

It's a good idea to successfully compile and run Wireshark at least once before you start hacking the Wireshark sources for your own project!

  1. Download sources : Download Wireshark sources into: C:\wireshark using TortoiseSVN

    1. right click on the C:\ drive in Windows Explorer

    2. in the upcoming context menu select "SVN checkout..." and then set:

      1. URL of repository: " http://anonsvn.wireshark.org/wireshark/trunk/"

      2. Checkout directory: "C:\wireshark"

    3. TortoiseSVN might ask you to create this directory - say yes

    4. TortoiseSVN starts downloading the sources

    5. if the download fails you may be behind a restrictive firewall, see Section 3.3, “Obtain the Wireshark sources”for alternative download methods

  2. Edit config.nmake: edit the settings in C:\wireshark\config.nmake, especially:

    1. VERSION_EXTRA : Give Wireshark your "private" version info, e.g.: -myprotocol123 - to distinguish it from an official release!

    2. PROGRAM_FILES : Where your programs reside, usually just keep the default: C:/Program Files 2

    3. MSVC_VARIANT : Make sure the variant for your compiler is uncommented, and that all others are commented out. For example, if you're using Visual C++ 2005 Express Edition, find the line

                        #MSVC_VARIANT=MSVC2005EE
                      

      and remove the comment character (#) from the beginning of the line. Then, find the line

                        MSVC_VARIANT=MSVC2008
                      

      and comment it out. 1

1Compiler dependent: This step depends on the compiler you are using. For compilers other than Visual C++ 2008, see the table at Section 4.4, “Microsoft compiler toolchain (Win32 native)”.

2International Windows might use different values here, e.g. a German version uses C:/Programme - take this also in account where C:\Program Files appears elsewhere

2.2.6. Prepare cmd.exe

Prepare cmd.exe - set environment and current dir.

  1. start cmd.exe

  2. call C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat to set environment variables of Visual C++ 2008 Express Edition 1,2

  3. cd C:\wireshark to jump into the source directory

1Compiler dependent: This step depends on the compiler variant used, for other variants than the recommended Visual C++ 2008 Express Edition see the table at Section 4.4, “Microsoft compiler toolchain (Win32 native)”!

2International Windows might use different values here, e.g. a German version uses C:/Programme - take this also in account where C:\Program Files appears elsewhere. Note: You need to repeat steps 1 - 4 each time you open a new cmd.exe!

2.2.7. Verify installed tools

After you've installed the Wireshark sources (see Section 3.3, “Obtain the Wireshark sources”), you can check the correct installation of all tools by using the verify_tools target of the Makefile.nmake from the source package.

[Warning]Warning!

You will need the Wireshark sources and some tools (nmake, bash) installed, before this verification is able to work.

Enter at the command line (cmd.exe, not Cygwin's bash!):

> nmake -f Makefile.nmake verify_tools

This will check for the various tools needed to build Wireshark:

          Checking for required applications:
        cl: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/cl
        link: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/link
        nmake: /cygdrive/c/Programme/Microsoft Visual Studio 8/VC/BIN/nmake
        bash: /usr/bin/bash
        bison: /usr/bin/bison
        flex: /usr/bin/flex
        env: /usr/bin/env
        grep: /usr/bin/grep
        /usr/bin/find: /usr/bin/find
        perl: /usr/bin/perl
        env: /usr/bin/env
        C:/python26/python.exe: /cygdrive/c/python26/python.exe
        sed: /usr/bin/sed
        unzip: /usr/bin/unzip
        wget: /usr/bin/wget

If you have problems with all the first three items (cl, link, nmake), check if you called vcvars32/SetEnv as mentioned in Section 2.2.6, “Prepare cmd.exe” (which will "fix" your PATH settings). However, the exact text will be slightly different depending on the MSVC version used.

Unfortunately, the link command is defined both in cygwin and in MSVC each with completely different functionality; you'll need the MSVC link. If your link command looks something like: /usr/bin/link, the link command of cygwin takes precedence over the MSVC one. To fix this, you can change your PATH environment setting or simply rename the link.exe in cygwin. If you rename it, make sure to remember that a cygwin update may provide a new version of it.

2.2.8. Install Libraries

  1. If you've closed cmd.exe in the meantime, prepare cmd.exe again

  2. nmake -f Makefile.nmake setup downloads libraries using wget and installs them - this may take a while ...

  3. If the download fails you may be behind a restrictive firewall, see the proxy comment in Section 4.15, “Win32: GNU wget (optional)”.

2.2.9. Distclean Sources

The released Wireshark sources contain files that are prepared for a UNIX build (e.g. config.h).

You must distclean your sources before building the first time!

  1. If you've closed cmd.exe in the meantime, prepare cmd.exe again

  2. nmake -f Makefile.nmake distclean to cleanup the Wireshark sources

2.2.10. Build Wireshark

Now it's time to build Wireshark ...

  1. If you've closed cmd.exe in the meantime, prepare cmd.exe again

  2. nmake -f Makefile.nmake all to build Wireshark

  3. wait for Wireshark to compile - this may take a while!

  4. run C:\wireshark\wireshark-gtk2\wireshark.exe and check if it starts

  5. check Help/About if it shows your "private" program version, e.g.: Version 0.99.4-myprotocol123 - you might run a release version previously installed!

Tip: If compilation fails for suspicious reasons after you changed some source files try to distclean the sources and make "all" again

2.2.11. Debug Environment Setup (XXX)

XXX - debug needs to be written, e.g. an idea is the create a simple MSVC 6 workspace/project(s) to ease Visual Studio debugging

2.2.12. Optional: Create User's and Developer's Guide

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

2.2.13. Optional: Create a Wireshark Installer

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

If you want to build your own wireshark-setup.exe, you'll need NSIS.

  1. NSIS: Download and install NSIS

    You may check the MAKENSIS setting in the file config.nmake of the Wireshark sources.

  2. vcredist_x86.exe : Download the C-Runtime redistributable for Visual C++ 2008 Express Edition (vcredist_x86.exe) and copy it into C:\wireshark-win32-libs 1

    [Warning]Beware of Visual Studio Service Packs!

    If you have installed the Visual Studio Service Pack 1, you need a different vcredist_x86.exe version! See Section 4.4, “Microsoft compiler toolchain (Win32 native)”for details!

  3. If you've closed cmd.exe in the meantime, prepare cmd.exe again

  4. nmake -f Makefile.nmake packaging build Wireshark installer

  5. run C:\wireshark\packaging\nsis\wireshark-setup-<version>.exe and test it - it's a good idea to test also on a different machine than the developer machine.

1Compiler dependent: This step depends on the compiler variant used, for other variants than the recommended Visual C++ 2008 Express Edition see the table at Section 4.4, “Microsoft compiler toolchain (Win32 native)”!