Skip to content

Commit bcc9ffd

Browse files
seladbseladb
authored
Add AGENTS.md (#2069)
1 parent ce34353 commit bcc9ffd

1 file changed

Lines changed: 275 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
# PcapPlusPlus Development Guide
2+
3+
This file provides guidance for AI coding agents (e.g. OpenAI Codex, Claude, GitHub Copilot
4+
Workspace, etc.) working inside the PcapPlusPlus repository. Read this before writing or
5+
modifying code.
6+
7+
---
8+
9+
## Project Overview
10+
11+
PcapPlusPlus is a **multiplatform C++ library** for capturing, parsing, and crafting network
12+
packets. It wraps popular packet-processing engines (libpcap, Npcap, WinPcap, DPDK, eBPF
13+
AF_XDP, WinDivert, PF_RING) behind a clean, modern C++ API.
14+
15+
The codebase is organized into three libraries:
16+
17+
| Library | Purpose |
18+
|------------|---------------------------------------------------------------------------|
19+
| `Common++` | Shared utilities used by both Packet++ and Pcap++ |
20+
| `Packet++` | Protocol parsing, editing, and crafting (standalone; no libpcap required) |
21+
| `Pcap++` | Packet capture/send via libpcap, Npcap, DPDK, etc. |
22+
23+
---
24+
25+
## Repository Layout
26+
27+
```
28+
PcapPlusPlus/
29+
├── Common++/ # Common++ library source & headers
30+
├── Packet++/ # Packet++ library source & headers
31+
├── Pcap++/ # Pcap++ library source & headers
32+
├── Tests/
33+
│ ├── Packet++Test/ # Unit tests for Packet++ (protocol parsing/crafting)
34+
│ ├── Pcap++Test/ # Unit tests for Pcap++ (live capture, file I/O, etc.)
35+
│ └── ExamplesTest/ # Python-based tests (written with pytest) for the example applications
36+
├── Examples/ # Example applications
37+
│ └── Tutorials/ # Tutorial source code
38+
├── cmake/ # CMake helper modules
39+
└── CMakeLists.txt # Top-level CMake build file
40+
```
41+
42+
---
43+
44+
## Building the Project
45+
46+
PcapPlusPlus uses **CMake** as its build system.
47+
48+
### Linux / macOS
49+
50+
Install the prerequisite (libpcap):
51+
```bash
52+
# Debian/Ubuntu
53+
sudo apt-get install libpcap-dev
54+
55+
# RHEL/Fedora
56+
sudo yum install libpcap-devel
57+
58+
# macOS (Xcode Command Line Tools already include libpcap)
59+
xcode-select --install
60+
```
61+
62+
Configure and build:
63+
```bash
64+
cmake -S . -B build
65+
cmake --build build
66+
```
67+
68+
Build outputs:
69+
- `build/Common++/libCommon++.a`
70+
- `build/Packet++/libPacket++.a`
71+
- `build/Pcap++/libPcap++.a`
72+
- `build/examples_bin/` — example binaries
73+
- `Tests/Packet++Test/Bin/Packet++Test`
74+
- `Tests/Pcap++Test/Bin/Pcap++Test`
75+
76+
### Key CMake Options
77+
78+
| Option | Default | Description |
79+
|-----------------------------------|---------|------------------------------------------------------|
80+
| `-DPCAPPP_BUILD_EXAMPLES=ON/OFF` | `ON` | Build example apps |
81+
| `-DPCAPPP_BUILD_TESTS=ON/OFF` | `ON` | Build unit tests |
82+
| `-DPCAPPP_BUILD_TUTORIALS=ON/OFF` | `OFF` | Build tutorial binaries |
83+
| `-DBUILD_SHARED_LIBS=ON/OFF` | `OFF` | Build shared instead of static libs |
84+
| `-DPCAPPP_USE_PCAP=ON/OFF` | `ON` | Enable libpcap/WinPcap/Npcap support |
85+
| `-DPCAPPP_USE_DPDK=ON/OFF` | `OFF` | Enable DPDK support |
86+
| `-DPCAPPP_USE_PF_RING=ON/OFF` | `OFF` | Enable PF_RING support |
87+
| `-DPCAPPP_USE_XDP=ON/OFF` | `OFF` | Enable AF_XDP support |
88+
| `-DPCAPPP_USE_WINDIVERT=ON/OFF` | `OFF` | Enable WinDivert support |
89+
| `-DPCAPPP_BUILD_PCAPPP=ON/OFF` | `ON` | Build Pcap++ (turn off for Packet++ & Common++ only) |
90+
| `-DLIGHT_PCAPNG_ZSTD=ON/OFF` | `OFF` | Enable Zstd PCAPNG compression |
91+
92+
### Windows (Visual Studio 2019/2022)
93+
94+
Download and install Npcap SDK (or WinPcap developer's pack) before configuring:
95+
```powershell
96+
cmake -S . -B build -G "Visual Studio 17 2022" -DPCAP_ROOT=<path_to_npcap_sdk>
97+
cmake --build build --config Release
98+
```
99+
100+
---
101+
102+
## Running Tests
103+
104+
**Always run tests from inside the test directory** — the test binaries rely on relative paths to
105+
fixture files.
106+
107+
### Packet++Test (protocol parsing/crafting — no network required)
108+
109+
```bash
110+
cd Tests/Packet++Test
111+
Bin/Packet++Test
112+
```
113+
114+
Run a subset by tag:
115+
```bash
116+
Bin/Packet++Test -t "eth;ipv4"
117+
```
118+
119+
Run a specific test case:
120+
```bash
121+
Bin/Packet++Test -t ArpPacketCreation
122+
```
123+
124+
Useful flags:
125+
126+
| Flag | Description |
127+
|------------------------------|----------------------------------------------------------------|
128+
| `-t / --include-tags` | Run only tests matching the given semicolon-separated tag list |
129+
| `-x / --exclude-tags` | Exclude tests matching the given semicolon-separated tag list |
130+
| `-m / --mem-verbose` | Verbose memory allocation output (leak debugging) |
131+
| `-s / --skip-mem-leak-check` | Skip the per-test memory leak check |
132+
133+
### Pcap++Test (live capture, file I/O, DPDK, etc.)
134+
135+
Requires `sudo` on Linux and macOS. Some tests need active network traffic on the specified interface.
136+
```bash
137+
cd Tests/Pcap++Test
138+
sudo Bin/Pcap++Test -i <interface_ip>
139+
```
140+
141+
To skip all tests that require live networking:
142+
```bash
143+
sudo Bin/Pcap++Test -n
144+
```
145+
146+
Run a subset by tag:
147+
```bash
148+
sudo Bin/Pcap++Test -i <interface_ip> -t "dpdk"
149+
```
150+
151+
Run a specific test case:
152+
```bash
153+
sudo Bin/Pcap++Test -i <interface_ip> -t TestSendPacket
154+
```
155+
156+
Useful flags:
157+
158+
| Flag | Description |
159+
|------------------------------|------------------------------------------------------------------------|
160+
| `-i / --use-ip` | IPv4 address of the interface to use (required for live-traffic tests) |
161+
| `-n / --no-networking` | Skip tests that require a live network interface |
162+
| `-k / --dpdk-port` | DPDK port number (required when built with DPDK) |
163+
| `-t / --include-tags` | Same tag filter mechanism as Packet++Test |
164+
| `-x / --exclude-tags` | Exclude tests matching the given semicolon-separated tag list |
165+
| `-d / --debug-mode` | Set log level to DEBUG for all tests |
166+
| `-s / --skip-mem-leak-check` | Skip per-test memory leak checks |
167+
168+
### Example tests (Python)
169+
170+
There is a Python-based test suite for the example applications under `Tests/ExamplesTests`.
171+
172+
Before running the tests:
173+
- Make sure all examples are built
174+
- Create a virtualenv with the dependencies defined in `ExamplesTest/requirements.txt`
175+
176+
Run the tests:
177+
178+
```bash
179+
cd Tests/ExamplesTest
180+
python3 -m pytest --interface <interface_name> --root-path=../../build/examples_bin
181+
```
182+
183+
---
184+
185+
## Writing Tests
186+
187+
- Tests live in `Tests/Packet++Test/` (Packet++) or `Tests/Pcap++Test/` (Pcap++).
188+
- Each test case is a function decorated with the `PTF_TEST_CASE` macro.
189+
- Register new tests in the `TestDefinition.h` and add `PTF_RUN_TEST(<TEST_NAME>)` in `main.cpp`, assigning meaningful tags.
190+
- Packet example files (`.pcap`, `.pcapng`) used as fixtures go in:
191+
- `Tests/Packet++Test/PacketExamples/`
192+
- `Tests/Pcap++Test/PcapExamples/`
193+
- Memory-leak checking via **MemPlumber** runs automatically for every test case. Ensure
194+
all heap allocations are properly freed.
195+
196+
Example skeleton:
197+
```cpp
198+
PTF_TEST_CASE(MyNewProtocolParseTest)
199+
{
200+
// Load a pcap file
201+
pcpp::PcapFileReaderDevice reader("PacketExamples/my_protocol.pcap");
202+
PTF_ASSERT_TRUE(reader.open());
203+
204+
pcpp::RawPacket rawPacket;
205+
PTF_ASSERT_TRUE(reader.getNextPacket(rawPacket));
206+
207+
pcpp::Packet parsedPacket(&rawPacket);
208+
auto* layer = parsedPacket.getLayerOfType<pcpp::MyProtocolLayer>();
209+
PTF_ASSERT_NOT_NULL(layer);
210+
211+
PTF_ASSERT_EQUAL(layer->getSomeField(), expectedValue);
212+
} // MyNewProtocolParseTest
213+
```
214+
215+
---
216+
217+
## Coding Conventions
218+
219+
- **Language standard:** C++14 (do not use C++17/20 features).
220+
- **Namespace:** All public API lives under the `pcpp` namespace.
221+
- **Header guards:** Use `#pragma once` (preferred in this codebase) or traditional include guards.
222+
- **Naming:**
223+
- Classes: `PascalCase` (e.g., `TcpLayer`, `PcapFileReaderDevice`)
224+
- Methods & functions: `camelCase` (e.g., `getNextPacket`, `parseNextLayer`)
225+
- Member variables: `m_PascalCase` (e.g., `m_Data`, `m_NextLayer`)
226+
- Constants / enums: `UPPER_CASE` or `PascalCase` depending on context
227+
- **Formatting:** Use `clang-format` version 19.1.6 (could be installed in Python via virtualenv). A `.clang-format` is present at the repository root. Format new code
228+
before committing:
229+
```bash
230+
clang-format -i -style=file <your_file.cpp> <your_file.h>
231+
```
232+
- **Documentation:** Public API classes, methods, and enums should have Doxygen-style comments using triple slashes (`///`).
233+
- **No raw `new`/`delete` without ownership clarity:** Prefer RAII. When a class owns heap
234+
memory, implement or explicitly delete the copy constructor and assignment operator.
235+
236+
---
237+
238+
## Adding a New Protocol Layer
239+
240+
1. Create `Packet++/header/MyProtocolLayer.h` and `Packet++/src/MyProtocolLayer.cpp`.
241+
2. Inherit from `pcpp::Layer` (or a more specific base as needed).
242+
3. Implement at minimum:
243+
- `parseNextLayer()` — identify and instantiate the next layer
244+
- `getHeaderLen()` — return the fixed or computed header size
245+
- `computeCalculateFields()` — recalculate checksums / length fields
246+
- `toString()` — human-readable summary
247+
4. Register the protocol in `parseNextLayer()` of the previous protocol (that could be `TcpLayer`, `UdpLayer`, `EthLayer`, etc., or sometimes multiple protocols)
248+
so the packet parser knows when to invoke your layer.
249+
5. Add your files to `Packet++/CMakeLists.txt`.
250+
6. Write test cases in `Tests/Packet++Test/` and add example pcap files to
251+
`Tests/Packet++Test/PacketExamples/`.
252+
253+
---
254+
255+
## Pull Request Checklist
256+
257+
Before submitting a PR, verify:
258+
259+
- [ ] Code compiles cleanly on Linux (and ideally on macOS/Windows if relevant).
260+
- [ ] All existing tests pass: `Bin/Packet++Test` and `Bin/Pcap++Test -n`.
261+
- [ ] New functionality is covered by new test cases.
262+
- [ ] New public API is documented with Doxygen comments.
263+
- [ ] Code is formatted with `clang-format` using the repository's `.clang-format` config.
264+
- [ ] No memory leaks detected (MemPlumber checks pass).
265+
- [ ] Example pcap/pcapng files added for any new protocol or feature tests.
266+
267+
---
268+
269+
## Useful Links
270+
271+
- **Documentation & website:** https://pcapplusplus.github.io/
272+
- **API reference:** https://pcapplusplus.github.io/docs/api
273+
- **Contribution guide:** https://pcapplusplus.github.io/community#contribute
274+
- **Issue tracker:** https://github.com/seladb/PcapPlusPlus/issues
275+
- **Releases:** https://github.com/seladb/PcapPlusPlus/releases

0 commit comments

Comments
 (0)