Skip to content

Commit 7beff81

Browse files
orangeclaude
authored and
orange
committed
feat<kcp>: add KCP test executables and build support
- Add echo-server-kcp and echo-client-kcp executables to CMakeLists - Add test-kcp-simple executable for basic KCP testing - Update CMake minimum version to 3.5 for better compatibility - Add KCP test files: simple, minimal, debug, and bind variants - Update CLAUDE.md with project documentation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 87be6d8 commit 7beff81

File tree

7 files changed

+512
-2
lines changed

7 files changed

+512
-2
lines changed

‎CLAUDE.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is **libuvpp**, a fork of libuv with minimal changes for P2P networking. It extends the original libuv with additional transport protocols:
8+
9+
- **UDT (UDP-based Data Transfer)** - High-performance data transfer protocol
10+
- **KCP** - Fast and reliable ARQ protocol
11+
- **QUIC** - Modern transport protocol over UDP
12+
13+
This is part of a dual-component project with **nodejs-httpp** that enables HTTP over UDP-based transports.
14+
15+
## Build System
16+
17+
### CMake Build (Recommended)
18+
19+
```bash
20+
mkdir -p build
21+
(cd build && cmake .. -DBUILD_TESTING=ON)
22+
cmake --build build
23+
```
24+
25+
### Autotools Build (Unix-like systems)
26+
27+
```bash
28+
sh autogen.sh
29+
./configure
30+
make
31+
make check
32+
make install
33+
```
34+
35+
### Testing
36+
37+
Run all tests:
38+
```bash
39+
(cd build && ctest -C Debug --output-on-failure)
40+
```
41+
42+
Run specific test:
43+
```bash
44+
build/uv_run_tests_a TEST_NAME
45+
```
46+
47+
Run benchmarks:
48+
```bash
49+
build/uv_run_benchmarks_a
50+
```
51+
52+
Run UDT protocol tests:
53+
```bash
54+
build/echo-server-udt &
55+
build/echo-client-udt
56+
```
57+
58+
Run KCP protocol tests (must be built manually):
59+
```bash
60+
build/echo-server-kcp &
61+
build/echo-client-kcp
62+
```
63+
64+
For timing-sensitive tests on slow machines:
65+
```bash
66+
env UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests_a
67+
```
68+
69+
### Build Options
70+
71+
- `-DLIBUV_BUILD_SHARED=ON/OFF` - Build shared library (default: ON)
72+
- `-DASAN=ON` - Enable AddressSanitizer
73+
- `-DTSAN=ON` - Enable ThreadSanitizer
74+
- `-DUBSAN=ON` - Enable UndefinedBehaviorSanitizer
75+
- `-DQEMU=ON` - Build for QEMU
76+
77+
### Submodule Initialization
78+
79+
Protocol extensions are git submodules. Initialize them before building:
80+
```bash
81+
git submodule update --init --recursive
82+
```
83+
84+
**Note**: Current git status shows submodules have modifications. Check submodule status with:
85+
```bash
86+
git status -b .
87+
```
88+
89+
### Quick Build Verification
90+
91+
After building, verify protocol extensions are included:
92+
```bash
93+
nm build/libuv.a | grep -i udt
94+
nm build/libuv.a | grep -i kcp
95+
```
96+
97+
## Architecture
98+
99+
### Core Components
100+
101+
- **src/** - Core libuv implementation
102+
- `src/unix/` - Unix-specific implementations
103+
- `src/win/` - Windows-specific implementations
104+
- **include/** - Public API headers
105+
- `uv.h` - Main API header
106+
- **test/** - Test suite and benchmarks
107+
108+
### Extended Protocols
109+
110+
- **uvudt/** - UDT transport integration
111+
- `uvudt/UDT4/` - UDT v4 library
112+
- `uvudt/uvudt.c` - libuv UDT wrapper
113+
- `uvudt/udtstream.c` - UDT stream implementation
114+
115+
- **uvkcp/** - KCP transport integration
116+
- `uvkcp/kcp/` - KCP library
117+
- `uvkcp/uvkcp.c` - libuv KCP wrapper
118+
- `uvkcp/kcpstream.c` - KCP stream implementation
119+
120+
- **uvquic/** - QUIC transport integration
121+
- `uvquic/quic++.cpp` - QUIC++ implementation (currently empty)
122+
- `uvquic/uvquic.c` - libuv QUIC wrapper (currently empty)
123+
- `uvquic/quicstream.c` - QUIC stream implementation (currently empty)
124+
125+
### Platform Support
126+
127+
- **Windows**: Uses CMake only, requires Visual Studio Build Tools
128+
- **Unix-like**: Supports both CMake and autotools
129+
- **Cross-compilation**: Supported via CMake
130+
131+
## Development Notes
132+
133+
### Code Conventions
134+
135+
- C code follows C90 standard with GNU extensions
136+
- C++ code follows C++11 standard
137+
- Platform-specific code separated into `src/unix/` and `src/win/`
138+
- Public API defined in `include/uv.h`
139+
140+
### Testing
141+
142+
- Test list defined in `test/test-list.h`
143+
- Benchmarks defined in `test/benchmark-list.h`
144+
- Tests are timing-sensitive, use `UV_TEST_TIMEOUT_MULTIPLIER=2` on slow machines
145+
146+
### Protocol Extensions
147+
148+
Each protocol extension follows a similar pattern:
149+
- Protocol wrapper file (e.g., `uvudt.c`)
150+
- Stream implementation (e.g., `udtstream.c`)
151+
- Protocol library integration
152+
- Test executables in protocol-specific test directories
153+
154+
**Key Implementation Files**:
155+
- UDT: `uvudt/uvudt.c`, `uvudt/udtstream.c`, `uvudt/UDT4/src/*.cpp`
156+
- KCP: `uvkcp/uvkcp.c`, `uvkcp/kcpstream.c`, `uvkcp/kcp/ikcp.c`
157+
- QUIC: Files exist but are currently empty
158+
159+
### Important Build Flags
160+
161+
- `-fno-strict-aliasing` recommended for projects using libuv
162+
- Compiler-specific warnings and optimizations configured in CMakeLists.txt
163+
164+
## Common Development Tasks
165+
166+
### Adding New Tests
167+
168+
1. Add test file to `test/` directory
169+
2. Update `test/test-list.h` with test declaration
170+
3. Test will be automatically included in CMake build
171+
172+
### Building Protocol Extensions
173+
174+
Protocol extensions are automatically included in the main build. Each extension adds:
175+
- Source files to `uv_sources` list in CMakeLists.txt (lines 181-202)
176+
- Include directories for protocol headers
177+
- Test executables (e.g., `echo-server-udt`, `echo-server-kcp`)
178+
179+
**Build Integration**: All protocol sources are compiled directly into the main libuv library
180+
181+
### Debugging
182+
183+
Use fork-aware debugging tools:
184+
- GDB: `set follow-fork-mode child`
185+
- Valgrind: `--trace-children=yes`
186+
187+
## Important Notes
188+
189+
### Protocol Extension Status
190+
- **UDT**: Fully integrated with UDT4 library and test executables (`echo-server-udt`, `echo-client-udt`)
191+
- **KCP**: Integrated with KCP library, source files exist but test executables not built by default
192+
- **QUIC**: Basic structure in place but implementation files are currently empty
193+
194+
### Build Integration
195+
- Protocol extensions are compiled directly into the main libuv library
196+
- All protocol sources are included in `uv_sources` list in CMakeLists.txt
197+
- Protocol-specific headers are added to include directories
198+
- UDT4 library is compiled from source as part of the build
199+
200+
### Testing Protocol Extensions
201+
- UDT has dedicated test executables: `echo-server-udt` and `echo-client-udt`
202+
- KCP test executables (`echo-server-kcp`, `echo-client-kcp`) exist in source but are not built by default
203+
- Protocol tests follow the same pattern as core libuv tests
204+
205+
### Build Verification
206+
207+
After building, verify the library includes protocol extensions:
208+
```bash
209+
nm build/libuv.a | grep -i udt
210+
nm build/libuv.a | grep -i kcp
211+
```
212+
213+
**Note**: KCP test executables exist in source but are not built by default. To build them, ensure they are included in CMakeLists.txt.

‎CMakeLists.txt‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
cmake_minimum_required(VERSION 3.4)
1+
cmake_minimum_required(VERSION 3.5)
22

33
if(POLICY CMP0091)
44
cmake_policy(SET CMP0091 NEW) # Enable MSVC_RUNTIME_LIBRARY setting
@@ -764,6 +764,24 @@ add_executable(echo-client-udt uvudt/test/echo-client-udt.c)
764764
target_compile_definitions(echo-client-udt PRIVATE ${uv_defines} USING_UV_SHARED=1)
765765
target_compile_options(echo-client-udt PRIVATE ${uv_cflags})
766766
target_link_libraries(echo-client-udt uv)
767+
768+
### echo-server-kcp
769+
add_executable(echo-server-kcp uvkcp/test/echo-server-kcp.c)
770+
target_compile_definitions(echo-server-kcp PRIVATE ${uv_defines} USING_UV_SHARED=1)
771+
target_compile_options(echo-server-kcp PRIVATE ${uv_cflags})
772+
target_link_libraries(echo-server-kcp uv)
773+
774+
### echo-client-kcp
775+
add_executable(echo-client-kcp uvkcp/test/echo-client-kcp.c)
776+
target_compile_definitions(echo-client-kcp PRIVATE ${uv_defines} USING_UV_SHARED=1)
777+
target_compile_options(echo-client-kcp PRIVATE ${uv_cflags})
778+
target_link_libraries(echo-client-kcp uv)
779+
780+
### test-kcp-simple
781+
add_executable(test-kcp-simple test-kcp-simple.c)
782+
target_compile_definitions(test-kcp-simple PRIVATE ${uv_defines} USING_UV_SHARED=1)
783+
target_compile_options(test-kcp-simple PRIVATE ${uv_cflags})
784+
target_link_libraries(test-kcp-simple uv)
767785
####################################################################
768786

769787
# Now for some gibbering horrors from beyond the stars...

‎test-kcp-debug.c‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
#include "uvkcp.h"
2+
#include <stdio.h>
3+
#include <stdlib.h>
4+
#include <string.h>
5+
#include <errno.h>
6+
7+
static uv_loop_t* loop;
8+
9+
static void on_close(uv_handle_t* handle) {
10+
printf("KCP handle closed\n");
11+
}
12+
13+
static void test_bind() {
14+
uvkcp_t kcp;
15+
struct sockaddr_in addr;
16+
int r;
17+
18+
printf("Testing KCP bind...\n");
19+
20+
// Test initialization
21+
r = uvkcp_init(loop, &kcp);
22+
if (r != 0) {
23+
printf("ERROR: uvkcp_init failed: %d\n", r);
24+
return;
25+
}
26+
printf("uvkcp_init: OK\n");
27+
28+
// Test binding
29+
r = uv_ip4_addr("127.0.0.1", 51687, &addr);
30+
if (r != 0) {
31+
printf("ERROR: uv_ip4_addr failed: %d\n", r);
32+
return;
33+
}
34+
printf("uv_ip4_addr: OK\n");
35+
36+
printf("Attempting to bind to 127.0.0.1:51687\n");
37+
r = uvkcp_bind(&kcp, (const struct sockaddr*)&addr, 1, 1);
38+
if (r != 0) {
39+
printf("ERROR: uvkcp_bind failed: %d (errno: %d)\n", r, errno);
40+
printf("Error string: %s\n", uv_strerror(r));
41+
return;
42+
}
43+
printf("uvkcp_bind: OK\n");
44+
45+
printf("KCP bind test completed successfully\n");
46+
47+
// Cleanup
48+
uvkcp_close(&kcp, on_close);
49+
}
50+
51+
int main() {
52+
loop = uv_default_loop();
53+
54+
test_bind();
55+
56+
uv_run(loop, UV_RUN_DEFAULT);
57+
58+
return 0;
59+
}

0 commit comments

Comments
 (0)