|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to agents when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +libhv is a cross-platform C/C++ network library providing event-loop with non-blocking IO and timer. Core is C99, high-level wrappers are C++11. Compatible with gcc4.8+, MSVC2015+, clang. Supports Linux, Windows, macOS, Android, iOS, BSD, Solaris. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +### Makefile (primary, Unix) |
| 12 | +```bash |
| 13 | +./configure --with-openssl --with-http --with-mqtt --with-kcp # configure options |
| 14 | +make libhv # build library only (shared + static) |
| 15 | +make # build library + examples |
| 16 | +make examples # build all example programs |
| 17 | +make unittest # compile unit tests |
| 18 | +make evpp # build C++ evpp tests (requires libhv built first) |
| 19 | +make clean # clean build artifacts |
| 20 | +sudo make install # install to /usr/local/include/hv and /usr/local/lib |
| 21 | +``` |
| 22 | + |
| 23 | +### CMake (cross-platform) |
| 24 | +```bash |
| 25 | +mkdir build && cd build |
| 26 | +cmake .. -DWITH_OPENSSL=ON -DWITH_HTTP=ON -DBUILD_EXAMPLES=ON |
| 27 | +cmake --build . |
| 28 | +# Windows: cmake .. -G "Visual Studio 17 2022" -A x64 |
| 29 | +``` |
| 30 | + |
| 31 | +### Bazel |
| 32 | +```bash |
| 33 | +bazel build libhv |
| 34 | +``` |
| 35 | + |
| 36 | +### Package Managers |
| 37 | +```bash |
| 38 | +vcpkg install libhv # vcpkg |
| 39 | +xrepo install libhv # xmake |
| 40 | +``` |
| 41 | + |
| 42 | +## Testing |
| 43 | + |
| 44 | +```bash |
| 45 | +make unittest # compile all unit tests |
| 46 | +make run-unittest # compile and run unit tests (calls scripts/unittest.sh) |
| 47 | +bash scripts/unittest.sh # run pre-built unit tests |
| 48 | +make check # integration test: builds httpd, runs HTTP checks (scripts/check.sh) |
| 49 | +``` |
| 50 | + |
| 51 | +Run a single unit test directly: |
| 52 | +```bash |
| 53 | +bin/rbtree_test # or any test binary in bin/ |
| 54 | +``` |
| 55 | + |
| 56 | +Run evpp C++ tests (link against libhv): |
| 57 | +```bash |
| 58 | +make evpp |
| 59 | +bin/TcpServer_test |
| 60 | +bin/EventLoop_test |
| 61 | +``` |
| 62 | + |
| 63 | +## Key Configuration Options |
| 64 | + |
| 65 | +Build flags via `./configure` or CMake `-D` options (see `config.ini` for defaults): |
| 66 | + |
| 67 | +| Makefile flag | CMake flag | Purpose | |
| 68 | +|---|---|---| |
| 69 | +| `--with-openssl` | `-DWITH_OPENSSL=ON` | SSL/TLS via OpenSSL | |
| 70 | +| `--with-gnutls` | `-DWITH_GNUTLS=ON` | SSL/TLS via GnuTLS | |
| 71 | +| `--with-mbedtls` | `-DWITH_MBEDTLS=ON` | SSL/TLS via mbedTLS | |
| 72 | +| `--with-nghttp2` | `-DWITH_NGHTTP2=ON` | HTTP/2 support | |
| 73 | +| `--with-kcp` | `-DWITH_KCP=ON` | KCP reliable UDP | |
| 74 | +| `--with-mqtt` | `-DWITH_MQTT=ON` | MQTT client | |
| 75 | +| `--with-protocol` | `-DWITH_PROTOCOL=ON` | ICMP, DNS, FTP, SMTP | |
| 76 | +| `--with-evpp` | `-DWITH_EVPP=ON` | C++ wrappers (default: yes) | |
| 77 | +| `--without-evpp` | `-DWITH_EVPP=OFF` | Pure C build, no C++ | |
| 78 | +| `--enable-uds` | `-DENABLE_UDS=ON` | Unix Domain Socket | |
| 79 | +| `--with-io-uring` | `-DWITH_IO_URING=ON` | io_uring event backend (Linux 5.1+) | |
| 80 | + |
| 81 | +## Architecture |
| 82 | + |
| 83 | +``` |
| 84 | +Application / Examples |
| 85 | + │ |
| 86 | + ├── http/server, http/client HTTP/WebSocket/gRPC (C++) |
| 87 | + ├── mqtt/ MQTT client (C) |
| 88 | + ├── protocol/ ICMP, DNS, FTP, SMTP (C) |
| 89 | + │ |
| 90 | + ├── evpp/ C++ wrappers: TcpServer, TcpClient, UdpServer, EventLoop |
| 91 | + │ |
| 92 | + ├── event/ Core event loop: hloop, hio, htimer |
| 93 | + │ └── backends: epoll (Linux), kqueue (macOS/BSD), iocp/wepoll (Windows), io_uring (Linux 5.1+), select (fallback) |
| 94 | + │ └── kcp/ KCP reliable UDP transport |
| 95 | + │ |
| 96 | + ├── ssl/ Unified SSL interface (OpenSSL / GnuTLS / mbedTLS / platform) |
| 97 | + │ |
| 98 | + ├── base/ Platform abstraction, sockets, threads, logging, data structures |
| 99 | + ├── util/ C utilities (base64, md5, sha1) |
| 100 | + └── cpputil/ C++ utilities (string, path, file, json, threadpool, ini parser) |
| 101 | +``` |
| 102 | + |
| 103 | +**Layering rules**: `base/` has no dependencies on other modules. `event/` depends on `base/` and `ssl/`. `evpp/` wraps `event/`. `http/` depends on `evpp/`. Higher layers are optional and controlled by build flags. |
| 104 | + |
| 105 | +**Public API entry point**: `hv.h` includes all base headers. Module-specific headers (e.g., `HttpServer.h`, `TcpServer.h`, `mqtt_client.h`) are the primary include for each feature. Installed headers go to `include/hv/`. |
| 106 | + |
| 107 | +**Key types**: `hloop_t` (event loop), `hio_t` (IO handle), `htimer_t` (timer) in the C API. `EventLoop`, `TcpServer`, `TcpClient`, `Channel` in the C++ API. `HttpRequest`, `HttpResponse`, `HttpService` for HTTP. |
| 108 | + |
| 109 | +## Code Style |
| 110 | + |
| 111 | +- **Formatting**: `.clang-format` — LLVM-based, 4-space indent, 160 column limit, pointer right-aligned, `catch`/`else` on new line (custom brace wrapping), no include sorting. |
| 112 | +- **C API naming**: `h` prefix for functions (`hloop_new`, `hio_read`), `_t` suffix for types (`hloop_t`, `hio_t`), UPPERCASE macros (`HV_EXPORT`). |
| 113 | +- **C++ API naming**: PascalCase classes (`EventLoop`, `TcpServer`), `hv` namespace. |
| 114 | +- **File naming**: lowercase with underscores (`.c` for C, `.cpp` for C++). |
| 115 | +- **Platform-specific code**: isolated via `hplatform.h` and `#ifdef` conditional compilation. |
| 116 | + |
| 117 | +## CI |
| 118 | + |
| 119 | +GitHub Actions (`.github/workflows/CI.yml`): builds and tests on Linux (with OpenSSL+nghttp2+KCP+MQTT), Windows (CMake + VS2022), macOS, Android (NDK cross-compile), iOS (Xcode cross-compile). Benchmark workflow runs echo-server throughput and HTTP performance comparisons. |
0 commit comments