Skip to content

Change libpcap/WinPcap/Npcap to optional #217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
seladb merged 2 commits into from
Feb 7, 2026
Merged

Change libpcap/WinPcap/Npcap to optional #217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
01037ab
Make pcap optional
seladb Feb 7, 2026
d89b5a1
Fix formatting
seladb Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ int main(int argc, char* argv[])
if (parsedPacket.isPacketOfType(pcpp::IPv4))
{
// extract source and dest IPs
pcpp::IPv4Address srcIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getSrcIPv4Address();
pcpp::IPv4Address destIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getDstIPv4Address();
auto srcIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getSrcIPv4Address();
auto destIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getDstIPv4Address();

// print source and dest IPs
std::cout
Expand Down Expand Up @@ -171,6 +171,14 @@ while (reader->getNextPacket(rawPacket)) {
}
```

## libpcap / WinPcap / Npcap support

[libpcap](https://www.tcpdump.org/) is the most popular packet capture engine and is supported on multiple platforms including Linux, MacOS, Android and FreeBSD. [WinPcap](https://www.winpcap.org/) is the Windows version of libpcap but it is no longer maintained and has been replaced by [Npcap](https://npcap.com/) which is a fork of WinPcap with more features and better performance. Both WinPcap and Npcap are supported on Windows.

PcapPlusPlus provides a clean and simple C++ wrapper API for these engines and supports all of their main features such as live packet capture and sending packets to the network. In addition, PcapPlusPlus provides support for remote capture using WinPcap Remote Capture which allows you to capture packets from a remote machine running WinPcap.

These capture engines are required by default but you can choose to build PcapPlusPlus without them and use other capture engines instead (e.g. DPDK, AF_XDP, PF_RING, etc). To build without libpcap/WinPcap/Npcap support you can use the `-DPCAPPP_USE_PCAP=OFF` CMake option.

## DPDK support

The Data Plane Development Kit (DPDK) is a set of data plane libraries and network interface controller drivers for fast packet processing, currently managed as an open-source project under the Linux Foundation. The DPDK provides a programming framework for x86, ARM, and PowerPC processors and enables faster development of high speed data packet networking applications (taken from [Wikipedia](https://en.wikipedia.org/wiki/Data_Plane_Development_Kit)).
Expand Down
17 changes: 12 additions & 5 deletions docs/install/android.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,25 @@ title: Build for Android
In order to build PcapPlusPlus for Android please make sure you have the following prerequisites:

1. [Android NDK](https://developer.android.com/ndk) should be installed
2. Pre-compiled `libpcap` library for Android + header files which can be downloaded from [the `libpcap-android` GitHub repo](https://github.com/seladb/libpcap-android) (for Android API versions 21-30)
2. If you want to to use libpcap and have `-DPCAPPP_USE_PCAP=ON`, you'll need pre-compiled `libpcap` library for Android + header files which can be downloaded from [the `libpcap-android` GitHub repo](https://github.com/seladb/libpcap-android) (for Android API versions 21-30)

## Build

In order to build for Android a few parameters are needed:

- The path of Android NDK. Let's assume it's stored in `ANDROID_NDK`
- Android API version - must be between 21 and 30. Let's assume it's stored in `API_VERSIOM`
- Android API version - must be between 21 and 30. Let's assume it's stored in `API_VERSION`
- Target architecture which accepts the following values: `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. Let's assume it's stored in `ANDROID_ABI`
- The path of `libpcap` compiled for Android. Let's assume it's stored in `LIBPCAP_DIR`
- If you want to to use libpcap features: the path of `libpcap` compiled for Android. Let's assume it's stored in `LIBPCAP_DIR`

Assuming you want to build PcapPlusPlus into a `build` directory:

```shell
cmake \
-DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK}/build/cmake/android.toolchain.cmake" \
-DANDROID_PLATFORM="${API_VERSION}" \
-DANDROID_ABI="${ABI}" \
-DPCAP_LIBRARY="${LIBPCAP_DIR}/${ABI}/${API_VERSION}/libpcap.a" \
-DANDROID_ABI="${ANDROID_ABI}" \
-DPCAP_LIBRARY="${LIBPCAP_DIR}/${ANDROID_ABI}/${API_VERSION}/libpcap.a" \
-DPCAP_INCLUDE_DIR="${LIBPCAP_DIR}/include/" \
-DPCAPPP_BUILD_TESTS=OFF \
-DPCAPPP_BUILD_EXAMPLES=OFF \
Expand All @@ -40,6 +40,12 @@ cmake \

:::

:::tip NOTE 2

`-DPCAP_LIBRARY` and `-DPCAP_INCLUDE_DIR` are only needed if you want to use libpcap features. If you want to build without libpcap support you can use the `-DPCAPPP_USE_PCAP=OFF` CMake option and then you won't need to provide these parameters.

:::

And then initiate the build in one of two ways:

- Using CMake:
Expand All @@ -65,6 +71,7 @@ The following configuration options are available (on top of CMake's built-in op
| **`-DCMAKE_TOOLCHAIN_FILE=<PATH>`** | Android CMake toolchain file, usuaully resides in: `${ANDROID_NDK}/build/cmake/android.toolchain.cmake`. This is a mandatory option |
| **`-DANDROID_PLATFORM=<API_VERSION>`** | Android API version, must be between 21 and. . This is a mandatory option |
| **`-DANDROID_ABI=<TARGET_ARCH>`** | Android target architecture which accepts one of the following values: `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. This is a mandatory option |
| **`-DPCAPPP_USE_PCAP=<ON/OFF>`** | Build PcapPlusPlus with libpcap support (default value is `ON`). If you set it to `OFF` you won't need to provide `-DPCAP_LIBRARY` and `-DPCAP_INCLUDE_DIR` options and PcapPlusPlus will be built without libpcap support |
| **`-DPCAP_LIBRARY=<LIBPCAP_DIR>`** | The path of `libpcap.a` that is compiled for Android with the target architecture and API version, for example: `${LIBPCAP_DIR}/${ABI}/${API_VERSION}/libpcap.a`. This is a mandatory option |
| **`-DPCAP_INCLUDE_DIR=<LIBPCAP_INCLUDE_DIR>`** | The path of lipbpcap include files, for example: `${LIBPCAP_DIR}/include/`. This is a mandatory option |
| **`-DPCAPPP_BUILD_EXAMPLES=<ON/OFF>`** | Build PcapPlusPlus examples, in most cases should be set to `OFF`. If you want to run [PcapPlusPlus examples](../examples) on an Android device you need shell access, and for some of them you also need a rooted device. The examples will reside in `build/examples_bin` |
Expand Down
3 changes: 2 additions & 1 deletion docs/install/freebsd.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ In order to compile PcapPlusPlus on FreeBSD please make sure you have the follow

1. `git` (if not installed please run: `pkg install git`)
2. `CMake` (if not installed please run: `pkg install cmake`)
3. `libpcap` (if not installed please run: `pkg install libpcap`)
3. **Optional** `libpcap` if you want to use libpcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON` (if not installed please run: `pkg install libpcap`)

## Build

Expand Down Expand Up @@ -47,6 +47,7 @@ The following configuration options are available (on top of CMake's built-in op

| Option | Description |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`-DPCAPPP_USE_PCAP=<ON/OFF>`** | Build PcapPlusPlus with libpcap support (default value is `ON`) |
| **`-DPCAPPP_BUILD_EXAMPLES=<ON/OFF>`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TESTS=<ON/OFF>`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TUTORIALS=<ON/OFF>`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build/tutorials_bin` (default value is `OFF`) |
Expand Down
5 changes: 2 additions & 3 deletions docs/install/linux.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@ title: Build on Linux

## Prerequisites

In order to compile PcapPlusPlus on Linux please make sure you have the following components installed:

1. **libpcap developers pack** - contains the libpcap library PcapPlusPlus is linking with and relevant the header files. You can download it from [http://www.tcpdump.org/#latest-release](http://www.tcpdump.org/#latest-release) or through the standard Linux package managers such as `apt-get` or `yum`:
1. **OPTIONAL** - if you want to use libpcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON` , you'll need to install **libpcap developers pack** which contains the libpcap library PcapPlusPlus is linking with and relevant the header files. You can download it from [http://www.tcpdump.org/#latest-release](http://www.tcpdump.org/#latest-release) or through the standard Linux package managers such as `apt-get` or `yum`:

```bash
sudo apt-get install libpcap-dev
Expand Down Expand Up @@ -57,6 +55,7 @@ The following configuration options are available (on top of CMake's built-in op

| Option | Description |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`-DPCAPPP_USE_PCAP=<ON/OFF>`** | Build PcapPlusPlus with libpcap support (default value is `ON`) |
| **`-DPCAPPP_BUILD_EXAMPLES=<ON/OFF>`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TESTS=<ON/OFF>`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TUTORIALS=<ON/OFF>`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build/tutorials_bin` (default value is `OFF`) |
Expand Down
1 change: 1 addition & 0 deletions docs/install/macos.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ The following configuration options are available (on top of CMake's built-in op

| Option | Description |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`-DPCAPPP_USE_PCAP=<ON/OFF>`** | Build PcapPlusPlus with libpcap support (default value is `ON`) |
| **`-DPCAPPP_BUILD_EXAMPLES=<ON/OFF>`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TESTS=<ON/OFF>`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TUTORIALS=<ON/OFF>`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build/tutorials_bin` (default value is `OFF`) |
Expand Down
26 changes: 17 additions & 9 deletions docs/install/mingw.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,32 @@ In order to compile PcapPlusPlus on Windows using MinGW-w64 you need the followi
```shell
PATH=%PATH%;C:\mingw-w64\i686-8.1.0-posix-dwarf-rt_v6-rev0\mingw32\bin
```
4. Download and install [WinPcap](https://www.winpcap.org/install/) **OR** [Npcap](https://npcap.com/#download) on your system
:::tip Note for Npcap:
If you install **Npcap** please check the `Install Npcap in WinPcap API-compatilbility mode` option during installation:
4. **OPTIONAL** If you want to use WinPcap/Npcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON`:
1. Download and install [WinPcap](https://www.winpcap.org/install/) **OR** [Npcap](https://npcap.com/#download) on your system
:::tip Note for Npcap:
If you install **Npcap** please check the `Install Npcap in WinPcap API-compatilbility mode` option during installation:

![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png)
:::
![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png)
:::

5. [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/guide/npcap-devguide.html) - containing the `wpcap` library PcapPlusPlus is linking with plus relevant `.h` files.
1. WinPcap developer's pack can be downloaded from here: [https://www.winpcap.org/devel.htm](https://www.winpcap.org/devel.htm)
2. Npcap SDK can be downloaded from here: [https://nmap.org/npcap/#download](https://nmap.org/npcap/#download)
2. Download and install [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/#download) - containing the wpcap library PcapPlusPlus is linking with plus relevant `h` files.

## Build

Assuming you want to build PcapPlusPlus into a `build` directory:

With WinPcap/Npcap support:

```shell
cmake -G "MinGW Makefiles" -DPCAP_ROOT=<NpcapSDK_or_WinPcapDevPack_Directory> -S . -B build
```

Without WinPcap/Npcap support:

```shell
cmake -G "MinGW Makefiles" -DPCAPPP_USE_PCAP=OFF -S . -B build
```

And then initiate the build in one of two ways:

- Using CMake:
Expand Down Expand Up @@ -60,7 +67,8 @@ The following configuration options are available (on top of CMake's built-in op

| Option | Description |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`-DPCAP_ROOT=<DIR>`** | Npcap SDK or WinPcap developer pack directory (mandatory option) |
| **`-DPCAPPP_USE_PCAP=<ON/OFF>`** | Build PcapPlusPlus with WinPcap/Npcap support (default value is `ON`) |
| **`-DPCAP_ROOT=<DIR>`** | Npcap SDK or WinPcap developer pack directory (mandatory option if `-DPCAPPP_USE_PCAP=ON`) |
| **`-DPCAPPP_BUILD_EXAMPLES=<ON/OFF>`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TESTS=<ON/OFF>`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) |
| **`-DPCAPPP_BUILD_TUTORIALS=<ON/OFF>`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build\tutorials_bin` (default value is `OFF`) |
Expand Down
Loading