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-DPacket_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 Packet_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 163Start the appropriate Native Tools command line prompt. 164 165Change to the directory into which you want to build tcpdump, possibly 166after creating it first. One choice is to create it as a subdirectory 167of the tcpdump source directory. 168 169Run the command 170 171``` 172cmake "-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 176WinPcap SDK. 177 178`{generator}` is the string "Visual Studio N YYYY", where `N` is the 179version of Visual Studio and `YYYY` is the year number for that version; 180if you are building a 64-bit version of tcpdump, `YYYY` must be followed 181by a space and "Win64". For example, to build a 32-bit version of 182tcpdump with Visual Studio 2017, `{generator}` would be "Visual Studio 18315 2017" and to build a 64-bit version of tcpdump with Visual Studio 1842017, `{generator}` would be "Visual Studio 15 2017 Win64". 185 186`{path-to-tcpdump-source}` is the pathname of the top-level source 187directory for tcpdump. 188 189Run the command 190 191``` 192msbuild /m /nologo /p:Configuration={configuration} tcpdump.sln 193``` 194 195where `{configuration}` can be "Release", "Debug", or "RelWithDebInfo". 196 197Building with MinGW 198------------------- 199 200(XXX - this should be added) 201