1Building libpcap on Windows with Visual Studio 2============================================== 3 4Unlike the UN*Xes on which libpcap can capture network traffic, Windows 5has no network traffic capture mechanism that libpcap can use. 6Therefore, libpcap requires a driver, and a library to access the 7driver, provided by the Npcap or WinPcap projects. 8 9Those projects include versions of libpcap built to use that driver and 10library; these instructions are for people who want to build libpcap 11source releases, or libpcap from the Git repository, as a replacement 12for the version provided with Npcap or WinPcap. 13 14Npcap and WinPcap SDK 15--------------------- 16 17In order to build libpcap, you will need to download Npcap and its 18software development kit (SDK) or WinPcap and its software development 19kit. 20 21Npcap is currently being developed and maintained, and offers many 22additional capabilities that WinPcap does not. 23 24WinPcap is no longer being developed or maintained; it should be used 25only if there is some other requirement to use it rather than Npcap, 26such as a requirement to support versions of Windows earlier than 27Windows Vista, which is the earliest version supported by Npcap. 28 29Npcap and its SDK can be downloaded from its [home page](https://npcap.com). 30The 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 33The WinPcap installer can be downloaded from 34[here](https://www.winpcap.org/install/default.htm) 35and the WinPcap Developer's Kit can be downloaded from 36[here](https://www.winpcap.org/devel.htm). 37 38Required build tools 39-------------------- 40 41The 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 44Building libpcap on Windows requires Visual Studio 2015 or later. The 45Community Edition of Visual Studio can be downloaded at no cost from 46[here](https://visualstudio.microsoft.com). 47 48Additional tools are also required. Chocolatey is a package manager for 49Windows with which those tools, and other tools, can be installed; it 50can be downloaded from [here](https://chocolatey.org). 51 52It is a command-line tool; a GUI tool, Chocolatey GUI, is provided as a 53Chocolatey package, which can be installed from the command line: 54 55``` 56choco install chocolateygui 57``` 58 59For convenience, the `choco install` command can be run with the `-y` 60flag, forcing it to automatically answer all questions asked of the user 61with "yes": 62 63``` 64choco install -y chocolateygui 65``` 66 67The required tools are: 68 69### CMake ### 70 71libpcap does not provide supported project files for Visual Studio 72(there are currently unsupported project files provided, but we do not 73guarantee that they will work or that we will continue to provide them). 74It does provide files for CMake, which is a cross-platform tool that 75runs on UN\*Xes and on Windows and that can generate project files for 76UN\*X Make, the Ninja build system, and Visual Studio, among other build 77systems. 78 79Visual Studio 2015 does not provide CMake; an installer can be 80downloaded from [here](https://cmake.org/download/). 81 82When 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 85Visual Studio 2017, 2019, and 2022 provide CMake, so you will not need 86to install CMake if you have installed one of those versions of Visual 87Studio or later. They include built-in support for CMake-based projects 88as described 89[here](https://devblogs.microsoft.com/cppblog/cmake-support-in-visual-studio/). 90 91For Visual Studio 2017, make sure "Visual C++ tools for CMake" is 92installed; for Visual Studio 2019 and 2022, make sure "C++ CMake tools 93for Windows" is installed. 94 95CMake can also be installed as the Chocolatey package `cmake`: 96 97``` 98choco install -y cmake 99``` 100 101### winflexbison ### 102 103libpcap uses the Flex lexical-analyzer generator and the Bison or 104Berkeley YACC parser generators to generate the parser for filter 105expressions. Windows versions of Flex and Bison can be downloaded from 106 107 https://sourceforge.net/projects/winflexbison/ 108 109The downloaded file is a ZIP archive; create a folder on your C: drive, 110e.g. C:\Program Files\winflexbison, and put the contents of the ZIP 111archive into that folder. Then add that folder to the system PATH 112environment variable. 113 114Git 115--- 116 117An optional tool, required only if you will be building from a Git 118repository rather than from a release source tarball, is Git. Git is 119provided as an optional installation component, "Git for Windows", with 120Visual Studio 2017 and later. 121 122Building from the Visual Studio GUI 123----------------------------------- 124 125### Visual Studio 2017 ### 126 127Open the folder containing the libpcap source with Open > Folder. 128Visual Studio will run CMake; however, you will need to indicate where 129the Npcap or WinPcap SDK is installed. 130 131To do this, go to Project > "Change CMake Settings" > pcap and: 132 133Choose which configuration type to build, if you don't want the default 134Debug build. 135 136In the CMakeSettings.json tab, change cmakeCommandArgs to include 137 138``` 139-DPacket_ROOT={path-to-sdk} 140``` 141 142where `{path-to-sdk}` is the path of the directory containing the Npcap or 143WinPcap SDK. Note that backslashes in the path must be specified as two 144backslashes. 145 146Save the configuration changes with File > "Save CMakeSettings.json" or 147with Control-S. 148 149Visual Studio will then re-run CMake. If that completes without errors, 150you can build with CMake > "Build All". 151 152### Visual Studio 2019 and 2022 ### 153 154Open the folder containing the libpcap source with Open > Folder. 155Visual Studio will run CMake; however, you will need to indicate where 156the Npcap or WinPcap SDK is installed. 157 158To do this, go to Project > "CMake Settings for pcap" and: 159 160Choose which configuration type to build, if you don't want the default 161Debug build. 162 163Scroll down to "Cmake variables and cache", scroll through the list 164looking for the entry for Packet_ROOT, and either type in the path of 165the directory containing the Npcap or WinPcap SDK or use the "Browse..." 166button to browse for that directory. 167 168Save the configuration changes with File > "Save CMakeSettings.json" or 169with Control-S. 170 171Visual Studio will then re-run CMake. If that completes without errors, 172you can build with Build > "Build All". 173 174Building from the command line 175------------------------------ 176 177### Visual Studio 2017 ### 178 179Start the appropriate Native Tools command line prompt. 180 181Change to the directory into which you want to build libpcap, possibly 182after creating it first. One choice is to create it as a subdirectory 183of the libpcap source directory. 184 185Run the command 186 187``` 188cmake "-DPacket_ROOT={path-to-sdk}" -G {generator} {path-to-libpcap-source} 189``` 190 191`{path-to-sdk}` is the path of the directory containing the Npcap or 192WinPcap SDK. 193 194`{generator}` is the string "Visual Studio 15 2017" to build a 32-bit 195version of libpcap or the string "Visual Studio 15 2017 Win64" to build 196a 64-bit version of libpcap. 197 198`{path-to-libpcap-source}` is the pathname of the top-level source 199directory for libpcap. 200 201Run the command 202 203``` 204msbuild /m /nologo /p:Configuration={configuration} pcap.sln 205``` 206 207where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo". 208 209### Visual Studio 2019 ### 210 211Start the appropriate Native Tools command line prompt. 212 213Change to the directory into which you want to build libpcap, possibly 214after creating it first. One choice is to create it as a subdirectory 215of the libpcap source directory. 216 217Run the command 218 219``` 220cmake "-DPacket_ROOT={path-to-sdk}" -G "Visual Studio 16 2019" {platform} {path-to-libpcap-source} 221``` 222 223`{path-to-sdk}` is the path of the directory containing the Npcap or 224WinPcap SDK. 225 226`{platform}` is `-A Win32` to build a 32-bit version of libpcap or `-A 227x64` to build a 64-bit version of libpcap. 228 229`{path-to-libpcap-source}` is the pathname of the top-level source 230directory for libpcap. 231 232Run the command 233 234``` 235msbuild /m /nologo /p:Configuration={configuration} pcap.sln 236``` 237 238where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo". 239 240### Visual Studio 2022 ### 241 242Start the appropriate Native Tools command line prompt. 243 244Change to the directory into which you want to build libpcap, possibly 245after creating it first. One choice is to create it as a subdirectory 246of the libpcap source directory. 247 248Run the command 249 250``` 251cmake "-DPacket_ROOT={path-to-sdk}" -G "Visual Studio 17 2022" {platform} {path-to-libpcap-source} 252``` 253 254`{path-to-sdk}` is the path of the directory containing the Npcap or 255WinPcap SDK. 256 257`{platform}` is `-A Win32` to build a 32-bit version of libpcap or `-A 258x64` to build a 64-bit version of libpcap. 259 260`{path-to-libpcap-source}` is the pathname of the top-level source 261directory for libpcap. 262 263Run the command 264 265``` 266msbuild /m /nologo /p:Configuration={configuration} pcap.sln 267``` 268 269where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo". 270 271Building with MinGW 272------------------- 273 274MinGW is not supported because its snprintf(3) implementation is not suitable. 275 276Building with SSL/TLS support 277----------------------------- 278 279This is currently not implemented on Windows. 280