xref: /freebsd/contrib/libpcap/doc/README.windows.md (revision 56b17de1e8360fe131d425de20b5e75ff3ea897c)
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:
30
31  https://npcap.com
32
33The SDK is a ZIP archive; create a folder on your C: drive, e.g.
34C:\npcap-sdk, and put the contents of the ZIP archive into that folder.
35
36The WinPcap installer can be downloaded from
37
38  https://www.winpcap.org/install/default.htm
39
40and the WinPcap Developer's Kit can be downloaded from
41
42  https://www.winpcap.org/devel.htm
43
44Required build tools
45--------------------
46
47The Developer's Kit is a ZIP archive; it contains a folder named
48WpdPack, which you should place on your C: drive, e.g. C:\WpdPack.
49
50Building libpcap on Windows requires Visual Studio 2015 or later.  The
51Community Edition of Visual Studio can be downloaded at no cost from
52
53  https://visualstudio.microsoft.com
54
55Additional tools are also required.  Chocolatey is a package manager for
56Windows with which those tools, and other tools, can be installed; it
57can be downloaded from
58
59  https://chocolatey.org
60
61It is a command-line tool; a GUI tool, Chocolatey GUI, is provided as a
62Chocolatey package, which can be installed from the command line:
63
64	choco install chocolateygui
65
66For convenience, the "choco install" command can be run with the "-y"
67flag, forcing it to automatically answer all questions asked of the user
68with "yes":
69
70	choco install -y chocolateygui
71
72The required tools are:
73
74### CMake ###
75
76libpcap does not provide supported project files for Visual Studio
77(there are currently unsupported project files provided, but we do not
78guarantee that they will work or that we will continue to provide them).
79It does provide files for CMake, which is a cross-platform tool that
80runs on UN*Xes and on Windows and that can generate project files for
81UN*X Make, the Ninja build system, and Visual Studio, among other build
82systems.
83
84Visual Studio 2015 does not provide CMake; an installer can be
85downloaded from
86
87  https://cmake.org/download/
88
89When you run the installer, you should choose to add CMake to the system
90PATH for all users and to create the desktop icon.
91
92CMake can also be installed as the Chocolatey package "cmake":
93
94	choco install -y cmake
95
96Visual Studio 2017 and later provide CMake, so you will not need to
97install CMake if you have installed Visual Studio 2017 or later.  They
98include built-in support for CMake-based projects:
99
100  https://devblogs.microsoft.com/cppblog/cmake-support-in-visual-studio/
101
102For Visual Studio 2017, make sure "Visual C++ tools for CMake" is
103installed; for Visual Studio 2019, make sure "C++ CMake tools for
104Windows" is installed.
105
106### winflexbison ###
107
108libpcap uses the Flex lexical-analyzer generator and the Bison or
109Berkeley YACC parser generators to generate the parser for filter
110expressions.  Windows versions of Flex and Bison can be downloaded from
111
112  https://sourceforge.net/projects/winflexbison/
113
114The downloaded file is a ZIP archive; create a folder on your C: drive,
115e.g. C:\Program Files\winflexbison, and put the contents of the ZIP
116archive into that folder.  Then add that folder to the system PATH
117environment variable.
118
119Git
120---
121
122An optional tool, required only if you will be building from a Git
123repository rather than from a release source tarball, is Git.  Git is
124provided as an optional installation component, "Git for Windows", with
125Visual Studio 2017 and later.
126
127Building from the Visual Studio GUI
128-----------------------------------
129
130### Visual Studio 2017 ###
131
132Open the folder containing the libpcap source with Open > Folder.
133Visual Studio will run CMake; however, you will need to indicate where
134the Npcap or WinPcap SDK is installed.
135
136To do this, go to Project > "Change CMake Settings" > pcap and:
137
138Choose which configuration type to build, if you don't want the default
139Debug build.
140
141In the CMakeSettings.json tab, change cmakeCommandArgs to include
142
143	-DPacket_ROOT={path-to-sdk}
144
145where {path-to-sdk} is the path of the directory containing the Npcap or
146WinPcap SDK.  Note that backslashes in the path must be specified as two
147backslashes.
148
149Save the configuration changes with File > "Save CMakeSettings.json" or
150with control-S.
151
152Visual Studio will then re-run CMake.  If that completes without errors,
153you can build with CMake > "Build All".
154
155### Visual Studio 2019 ###
156
157Open the folder containing the libpcap source with Open > Folder.
158Visual Studio will run CMake; however, you will need to indicate where
159the Npcap or WinPcap SDK is installed.
160
161To do this, go to Project > "CMake Settings for pcap" and:
162
163Choose which configuration type to build, if you don't want the default
164Debug build.
165
166Scroll down to "Cmake variables and cache", scroll through the list
167looking for the entry for Packet_ROOT, and either type in the path of
168the directory containing the Npcap or WinPcap SDK or use the "Browse..."
169button to browse for that directory.
170
171Save the configuration changes with File > "Save CMakeSettings.json" or
172with control-S.
173
174Visual Studio will then re-run CMake.  If that completes without errors,
175you can build with Build > "Build All".
176
177Building from the command line
178------------------------------
179
180Start the appropriate Native Tools command line prompt.
181
182Change to the directory into which you want to build libpcap, possibly
183after creating it first.  One choice is to create it as a subdirectory
184of the libpcap source directory.
185
186Run the command
187
188	cmake "-DPacket_ROOT={path-to-sdk}" {path-to-libpcap-source}
189
190where {path-to-sdk} is the path of the directory containing the Npcap or
191WinPcap SDK and {path-to-libpcap-source} is the pathname of the
192top-level source directory for libpcap.
193
194Run the command
195
196	msbuild/m pcap.sln
197
198to compile libpcap.
199