The Tcpdump Group git mirrors - tcpdump/blob - doc/README.Win32.md

   1 Building tcpdump on Windows with Visual Studio
   2 ==============================================
   3
   4 Unlike the UN*Xes on which libpcap can capture network traffic, Windows
   5 has no network traffic capture mechanism that libpcap can use.
   6 Therefore, libpcap requires a driver, and a library to access the
   7 driver, provided by the Npcap or WinPcap projects.
   8
   9 Those projects include versions of libpcap built to use that driver and
  10 library; these instructions are for people who want to build libpcap
  11 source releases, or libpcap from the Git repository, as a replacement
  12 for the version provided with Npcap or WinPcap.
  13
  14 Npcap and WinPcap SDK
  15 ---------------------
  16
  17 In order to build tcpdump, you will need to download Npcap and its
  18 software development kit (SDK) or WinPcap and its software development
  19 kit.
  20
  21 Npcap is currently being developed and maintained, and offers many
  22 additional capabilities that WinPcap does not.
  23
  24 WinPcap is no longer being developed or maintained; it should be used
  25 only if there is some other requirement to use it rather than Npcap,
  26 such as a requirement to support versions of Windows earlier than
  27 Windows Vista, which is the earliest version supported by Npcap.
  28
  29 Npcap and its SDK can be downloaded from its [home page](https://npcap.org).
  30 The SDK is a ZIP archive; create a folder on your `C:` drive, e.g.
  31 `C:\npcap-sdk`, and put the contents of the ZIP archive into that folder.
  32
  33 The WinPcap installer can be downloaded from
  34 [here](https://www.winpcap.org/install/default.htm)
  35 and the WinPcap Developer's Kit can be downloaded from
  36 [here](https://www.winpcap.org/devel.htm).
  37
  38 Required build tools
  39 --------------------
  40
  41 The Developer's Kit is a ZIP archive; it contains a folder named
  42 `WpdPack`, which you should place on your `C:` drive, e.g. `C:\WpdPack`.
  43
  44 Building tcpdump on Windows requires Visual Studio 2015 or later.  The
  45 Community Edition of Visual Studio can be downloaded at no cost from
  46 [here](https://visualstudio.microsoft.com).
  47
  48 Additional tools are also required.  Chocolatey is a package manager for
  49 Windows with which those tools, and other tools, can be installed; it
  50 can be downloaded from [here](https://chocolatey.org).
  51
  52 It is a command-line tool; a GUI tool, Chocolatey GUI, is provided as a
  53 Chocolatey package, which can be installed from the command line:
  54
  55 ```
  56 choco install chocolateygui
  57 ```
  58
  59 For convenience, the `choco install` command can be run with the `-y`
  60 flag, forcing it to automatically answer all questions asked of the user
  61 with "yes":
  62
  63 ```
  64 choco install -y chocolateygui
  65 ```
  66
  67 The required tools are:
  68
  69 ### CMake ###
  70
  71 libpcap does not provide supported project files for Visual Studio
  72 (there are currently unsupported project files provided, but we do not
  73 guarantee that they will work or that we will continue to provide them).
  74 It does provide files for CMake, which is a cross-platform tool that
  75 runs on UN\*Xes and on Windows and that can generate project files for
  76 UN\*X Make, the Ninja build system, and Visual Studio, among other build
  77 systems.
  78
  79 Visual Studio 2015 does not provide CMake; an installer can be
  80 downloaded from [here](https://cmake.org/download/).
  81
  82 When you run the installer, you should choose to add CMake to the system
  83 `PATH` for all users and to create the desktop icon.
  84
  85 CMake can also be installed as the Chocolatey package `cmake`:
  86
  87 ```
  88 choco install -y cmake
  89 ```
  90
  91 Visual Studio 2017 and later provide CMake, so you will not need to
  92 install CMake if you have installed Visual Studio 2017 or later.  They
  93 include built-in support for CMake-based projects as described
  94 [here](https://devblogs.microsoft.com/cppblog/cmake-support-in-visual-studio/).
  95
  96 For Visual Studio 2017, make sure "Visual C++ tools for CMake" is
  97 installed; for Visual Studio 2019, make sure "C++ CMake tools for
  98 Windows" is intalled.
  99
 100 Git
 101 ---
 102
 103 An optional tool, required only if you will be building from a Git
 104 repository rather than from a release source tarball, is Git.  Git is
 105 provided as an optional installation component, "Git for Windows", with
 106 Visual Studio 2017 and later.
 107
 108 Building from the Visual Studio GUI
 109 -----------------------------------
 110
 111 ### Visual Studio 2017 ###
 112
 113 Open the folder containing the libpcap source with Open > Folder.
 114 Visual Studio will run CMake; however, you will need to indicate where
 115 the Npcap or WinPcap SDK is installed.
 116
 117 To do this, go to Project > "Change CMake Settings" > tcpdump and:
 118
 119 Choose which configuration type to build, if you don't want the default
 120 Debug build.
 121
 122 In the CMakeSettings.json tab, change cmakeCommandArgs to include
 123
 124 ```
 125 -DPacket_ROOT={path-to-sdk}
 126 ```
 127
 128 where `{path-to-sdk}` is the path of the directory containing the Npcap or
 129 WinPcap SDK.  Note that backslashes in the path must be specified as two
 130 backslashes.
 131
 132 Save the configuration changes with File > "Save CMakeSettings.json" or
 133 with Control-S.
 134
 135 Visual Studio will then re-run CMake.  If that completes without errors,
 136 you can build with CMake > "Build All".
 137
 138 ### Visual Studio 2019 ###
 139
 140 Open the folder containing the libpcap source with Open > Folder.
 141 Visual Studio will run CMake; however, you will need to indicate where
 142 the Npcap or WinPcap SDK is installed.
 143
 144 To do this, go to Project > "CMake Settings for tcpdump" and:
 145
 146 Choose which configuration type to build, if you don't want the default
 147 Debug build.
 148
 149 Scroll down to "Cmake variables and cache", scroll through the list
 150 looking for the entry for Packet_ROOT, and either type in the path of
 151 the directory containing the Npcap or WinPcap SDK or use the "Browse..."
 152 button to browse for that directory.
 153
 154 Save the configuration changes with File > "Save CMakeSettings.json" or
 155 with Control-S.
 156
 157 Visual Studio will then re-run CMake.  If that completes without errors,
 158 you can build with Build > "Build All".
 159
 160 Building from the command line
 161 ------------------------------
 162
 163 Start the appropriate Native Tools command line prompt.
 164
 165 Change to the directory into which you want to build tcpdump, possibly
 166 after creating it first.  One choice is to create it as a subdirectory
 167 of the tcpdump source directory.
 168
 169 Run the command
 170
 171 ```
 172 cmake "-DPacket_ROOT={path-to-sdk}" -G {generator} {path-to-tcpdump-source}
 173 ```
 174
 175 `{path-to-sdk}` is the path of the directory containing the Npcap or
 176 WinPcap SDK.
 177
 178 `{generator}` is the string "Visual Studio N YYYY", where `N` is the
 179 version of Visual Studio and `YYYY` is the year number for that version;
 180 if you are building a 64-bit version of tcpdump, `YYYY` must be followed
 181 by a space and "Win64".  For example, to build a 32-bit version of
 182 tcpdump with Visual Studio 2017, `{generator}` would be "Visual Studio
 183 15 2017" and to build a 64-bit version of tcpdump with Visual Studio
 184 2017, `{generator}` would be "Visual Studio 15 2017 Win64".
 185
 186 `{path-to-tcpdump-source}` is the pathname of the top-level source
 187 directory for tcpdump.
 188
 189 Run the command
 190
 191 ```
 192 msbuild /m /nologo /p:Configuration={configuration} tcpdump.sln
 193 ```
 194
 195 where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo".
 196
 197 Building with MinGW
 198 -------------------
 199
 200 (XXX - this should be added)