Build From Source for Android

Prerequisites

In order to build PcapPlusPlus for Android please make sure you have the following prerequisites:

1. Android NDK should be installed
2. Pre-compiled libpcap library for Android + header files which can be downloaded from the libpcap-android GitHub repo (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
• 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

Assuming you want to build PcapPlusPlus into a build directory:

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" \
-DPCAP_INCLUDE_DIR="${LIBPCAP_DIR}/include/" \
-DPCAPPP_BUILD_TESTS=OFF \
-DPCAPPP_BUILD_EXAMPLES=OFF \
-S . -B build

NOTE

-DPCAPPP_BUILD_TESTS=OFF and -DPCAPPP_BUILD_EXAMPLES=OFF are not mandatory, but building PcapPlusPlus tests and examples for Android usually doesn't make sense.

And then initiate the build in one of two ways:

• Using CMake:

  cmake --build build
• Using make:

  cd build
  make

This process will build the PcapPlusPlus libs:

• build/Common++/libCommon++.a
• build/Packet++/libPacket++.a
• build/Pcap++/libPcap++.a

The following configuration options are available (on top of CMake's built-in options):

Option	Description
-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
-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 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
-DPCAPPP_BUILD_TESTS=<ON/OFF>	Build PcapPlusPlus tests, in most cases should be set to OFF
-DPCAPPP_BUILD_TUTORIALS=<ON/OFF>	Build PcapPlusPlus tutorials. This option is only available if DPCAPPP_BUILD_EXAMPLES=ON (default value is OFF)
-DPCAPPP_INSTALL=<ON/OFF>	Install PcapPlusPlus (default value is ON if building the project itself, otherwise OFF)
-DBUILD_SHARED_LIBS=<ON/OFF>	Build shared libs (default value is OFF)
-DPCAPPP_ENABLE_PCAP_IMMEDIATE_MODE=<ON/OFF>	Enable pcap immediate mode (default value is OFF)
-DPCAPPP_ENABLE_PCAP_SET_DIRECTION=<ON/OFF>	Enable set direction for capturing incoming or outgoing packets (default value is OFF)

Installation

When building for Android the build machine (host) is usually different from the target device (target), so you may want to gather the lib and header files in a directory in the host instead of installing it on it. You can use the following command in order to achieve this:

DESTDIR=<DIR> cmake --install build --prefix "/"

Do I need a rooted device in order to use PcapPlusPlus in my Android app?

The quick answer is no. A lot of PcapPlusPlus functionality will work on any device and any app. However, on non-rooted devices some of the features may not work. The main reason is that non-rooted devices do not allow access to the device's network interfaces and configuration. That means that capturing live network traffic using PcapLiveDevice may not work, as well as opening raw sockets with RawSocketDevice. You may also need your app to request additional permissions to read and write files in order to read and write pcap/pcapng files.

But other than that, most of the features should work including parsing and analyzing of network packets and the various protocols supported by PcapPlusPlus, which is what ToyVpn-PcapPlusPlus demonstrates.

If you do have a rooted device most of PcapPlusPlus features should work. Please feel free to open an issue if something is not working as expected.

Using PcapPlusPlus in my app

PcapPlusPlus is a native C++ library so in order to use it in an Android app you need to get familiar with Android NDK which is the toolset for using native code in Android apps.

ToyVpn-PcapPlusPlus is a good way to get started because it provides a very simple yet end-to-end example of writing PcapPlusPlus code and integrating it with the app. Here are a few links to parts in the code you might find interesting:

• pcapplusplus_interface.cpp - the C++ code that uses PcapPlusPlus. It exposes 2 JNI methods that are used within the app
• CMakeLists.txt - a CMake file to build the native code
• PcapPlusPlusInterface.kt - a Kotlin file that uses the native JNI methods

If you want to learn more we strongly recommend going over ToyVpn-PcapPlusPlus's README.md file as it contains very detail information of how PcapPlusPlus can be used in a real Android app.