The Tcpdump Group git mirrors - tcpdump/blob - doc/README.windows.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.com).
  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 Visual Studio 2017, 2019, and 2022 provide CMake, so you will not need
  86 to install CMake if you have installed one of those versions of Visual
  87 Studio.  They include built-in support for CMake-based projects as
  88 described
  89 [here](https://devblogs.microsoft.com/cppblog/cmake-support-in-visual-studio/).
  90
  91 For Visual Studio 2017, make sure "Visual C++ tools for CMake" is
  92 installed; for Visual Studio 2019 and 2022, make sure "C++ CMake tools
  93 for Windows" is installed.
  94
  95 CMake can also be installed as the Chocolatey package `cmake`:
  96
  97 ```
  98 choco install -y cmake
  99 ```
 100
 101 Git
 102 ---
 103
 104 An optional tool, required only if you will be building from a Git
 105 repository rather than from a release source tarball, is Git.  Git is
 106 provided as an optional installation component, "Git for Windows", with
 107 Visual Studio 2017 and later.
 108
 109 Building from the Visual Studio GUI
 110 -----------------------------------
 111
 112 ### Visual Studio 2017 ###
 113
 114 Open the folder containing the libpcap source with Open > Folder.
 115 Visual Studio will run CMake; however, you will need to indicate where
 116 the Npcap or WinPcap SDK is installed.
 117
 118 To do this, go to Project > "Change CMake Settings" > tcpdump and:
 119
 120 Choose which configuration type to build, if you don't want the default
 121 Debug build.
 122
 123 In the CMakeSettings.json tab, change cmakeCommandArgs to include
 124
 125 ```
 126 -DPCAP_ROOT={path-to-sdk}
 127 ```
 128
 129 where `{path-to-sdk}` is the path of the directory containing the Npcap or
 130 WinPcap SDK.  Note that backslashes in the path must be specified as two
 131 backslashes.
 132
 133 Save the configuration changes with File > "Save CMakeSettings.json" or
 134 with Control-S.
 135
 136 Visual Studio will then re-run CMake.  If that completes without errors,
 137 you can build with CMake > "Build All".
 138
 139 ### Visual Studio 2019 and 2022 ###
 140
 141 Open the folder containing the libpcap source with Open > Folder.
 142 Visual Studio will run CMake; however, you will need to indicate where
 143 the Npcap or WinPcap SDK is installed.
 144
 145 To do this, go to Project > "CMake Settings for tcpdump" and:
 146
 147 Choose which configuration type to build, if you don't want the default
 148 Debug build.
 149
 150 Scroll down to "Cmake variables and cache", scroll through the list
 151 looking for the entry for PCAP_ROOT, and either type in the path of
 152 the directory containing the Npcap or WinPcap SDK or use the "Browse..."
 153 button to browse for that directory.
 154
 155 Save the configuration changes with File > "Save CMakeSettings.json" or
 156 with Control-S.
 157
 158 Visual Studio will then re-run CMake.  If that completes without errors,
 159 you can build with Build > "Build All".
 160
 161 Building from the command line
 162 ------------------------------
 163
 164 ### Visual Studio 2017 ###
 165
 166 Start the appropriate Native Tools command line prompt.
 167
 168 Change to the directory into which you want to build tcpdump, possibly
 169 after creating it first.  One choice is to create it as a subdirectory
 170 of the tcpdump source directory.
 171
 172 Run the command
 173
 174 ```
 175 cmake "-DPCAP_ROOT={path-to-sdk}" -G {generator} {path-to-tcpdump-source}
 176 ```
 177
 178 `{path-to-sdk}` is the path of the directory containing the Npcap or
 179 WinPcap SDK.
 180
 181 `{generator}` is the string "Visual Studio 15 2017" to build a 32-bit
 182 version of tcpdump or the string "Visual Studio 15 2017 Win64" to build
 183 a 64-bit version of tcpdump.
 184
 185 `{path-to-tcpdump-source}` is the pathname of the top-level source
 186 directory for tcpdump.
 187
 188 Run the command
 189
 190 ```
 191 msbuild /m /nologo /p:Configuration={configuration} tcpdump.sln
 192 ```
 193
 194 where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo".
 195
 196 ### Visual Studio 2019 ###
 197
 198 Start the appropriate Native Tools command line prompt.
 199
 200 Change to the directory into which you want to build tcpdump, possibly
 201 after creating it first.  One choice is to create it as a subdirectory
 202 of the tcpdump source directory.
 203
 204 Run the command
 205
 206 ```
 207 cmake "-DPCAP_ROOT={path-to-sdk}" -G "Visual Studio 16 2019" {platform} {path-to-tcpdump-source}
 208 ```
 209
 210 `{path-to-sdk}` is the path of the directory containing the Npcap or
 211 WinPcap SDK.
 212
 213 `{platform}` is `-A Win32` to build a 32-bit version of tcpdump or `-A
 214 x64` to build a 64-bit version of tcpdump.
 215
 216 `{path-to-tcpdump-source}` is the pathname of the top-level source
 217 directory for tcpdump.
 218
 219 Run the command
 220
 221 ```
 222 msbuild /m /nologo /p:Configuration={configuration} tcpdump.sln
 223 ```
 224
 225 where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo".
 226
 227 ### Visual Studio 2022 ###
 228
 229 Start the appropriate Native Tools command line prompt.
 230
 231 Change to the directory into which you want to build tcpdump, possibly
 232 after creating it first.  One choice is to create it as a subdirectory
 233 of the tcpdump source directory.
 234
 235 Run the command
 236
 237 ```
 238 cmake "-DPCAP_ROOT={path-to-sdk}" -G "Visual Studio 17 2022" {platform} {path-to-tcpdump-source}
 239 ```
 240
 241 `{path-to-sdk}` is the path of the directory containing the Npcap or
 242 WinPcap SDK.
 243
 244 `{platform}` is `-A Win32` to build a 32-bit version of tcpdump or `-A
 245 x64` to build a 64-bit version of tcpdump.
 246
 247 `{path-to-tcpdump-source}` is the pathname of the top-level source
 248 directory for tcpdump.
 249
 250 Run the command
 251
 252 ```
 253 msbuild /m /nologo /p:Configuration={configuration} tcpdump.sln
 254 ```
 255
 256 where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo".
 257
 258 Building with MinGW
 259 -------------------
 260
 261 (XXX - this should be added)