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