From the first program to a complete engineering setup.

#define XRT_IMPLEMENTATION
#include "xrt.h"
#include <stdio.h>

int main(void)
{
    printf("XRT %s\n", XRT_VERSION_TEXT);
    return 0;
}

cc -std=c11 -O2 main.c -o hello
./hello

gcc -std=c11 -O2 main.c -o hello.exe
.\hello.exe

Build system and verified examples

The network examples live in examples/ and the extensions' examples/, and pair with their test suites for learning calls and lifecycles. The unified build entry tools/build.py provides: SHA256-fingerprint incremental compilation, module dependency-closure expansion, and automatic response-file switching for long Windows command lines; the GCC / Clang / MSVC (including clang-cl) / TCC compiler families are interchangeable. build.bat and build.sh are thin wrappers around it.

git clone https://gitee.com/xywhsoft/xrt.git
cd xrt

# Default: build and run the kernel tests (build.bat on Windows, ./build.sh on Linux/macOS)
python tools/build.py

# Pick a suite: module name, comma combinations, or all; --jobs parallelizes, --start-test resumes from a failure
python tools/build.py --suite core,concurrency --jobs 4
python tools/build.py --suite all --start-test test_http_client

# Extension libraries: layer the extension manifest
python tools/build.py --manifest extlibs/xhttp/config/modules.json --suite xhttp_tests
python tools/build.py --manifest extlibs/xws/config/modules.json --suite xws_tests

# Package static / shared libraries and compile+run consumer programs to verify
python tools/package.py --kind static --verify
python tools/package.py --manifest extlibs/xhttp/config/modules.json --kind shared --verify

# Regenerate the single-header artifact (supports --manifest and --check drift verification)
python tools/amalgamate.py

Choose a release shape

Single header (fast integration)

/* single/xrt.h contains the full implementation; extensions likewise (e.g. extlibs/xhttp/single/xhttp.h) */
#define XRT_IMPLEMENTATION
#include "xrt.h"

Modular / library (engineering integration)

Use tools/package.py to produce static or shared libraries (with import libraries), or bring the kernel sources straight into your build — the module manifests already declare every source file's ownership and dependencies. Header paths are uniformly <xrt/xxx.h>. Choose by project boundary, not by jargon: single header for prototypes and tools, libraries for product builds.

Feature trimming system

Trimming works in units of module macros: after defining XRT_MODULE_<NAME>, include/xrt/features.h (generated from modules.json by tools/generate_features.py) automatically expands its dependency closure and sets the corresponding XRT_FEATURE_* macros; a missing dependency raises a direct #error in the header.

/* Just TCP networking and coroutines */
#define XRT_MODULE_NET_TCP
#define XRT_MODULE_COROUTINE
#include "xrt.h"

/* Enable everything */
/* #define XRT_MODULE_ALL */

Trimming correctness is guarded by two gates:

• Reverse trim verification (build.py --trim-only): for every module, its direct dependency macros are deliberately removed and compilation must fail, preventing missing guards.
• Symbol ban (measure_size.py): the minimal core trim artifact must not contain symbols with prefixes like xrtNet / xrtHttp / xrtWs / xrtTls / xrtRegex — binary-level prevention of feature creep.

Extensions have a parallel macro system (XHTTP_MODULE_*, XWS_MODULE_*…), generated by generate_extension_features.py, chaining kernel module macros as requirements.

Getting to know XRT

XRT is a systematic cross-platform C infrastructure library, aiming to provide a complete infrastructure loop with zero third-party runtime dependencies for the Internet + AI era. Since v2.0, the repository splits into two parts:

• Kernel (src/ + include/xrt/): concurrent coroutines, the five-backend network engine, TLS, the HTTP/WebSocket protocol core, memory and containers, files and processes, regex and pattern matching. 94 public headers; the module manifests declare 386 distinct feature macros.
• Extension libraries (extlibs/): five independent products split by domain — xhttp, xws, xruntime, xmail, xssh. Each is a self-contained mini-project (its own src / include / tests / examples / config / single) depending one-way on the kernel. The xregex library has been merged into the kernel regex module.

Two consumption shapes: modular sources / static library / shared library, or the self-contained single header (the kernel and every extension each ship one).

Repository tour

Concurrency models: pick by problem, use them all if you must — or not

Threads, coroutines, Channel, Future, task groups, and cancellation tokens each solve a different boundary. First decide whether the work needs true parallelism, I/O waiting, message passing, result composition, or a coordinated stop; then pick the smallest set of mechanisms.

Kernel module map

A quick lookup of modules grouped by system (public headers under include/xrt/; full per-API documentation in the API reference):

Extension library guide

Every extension shares one directory layout: src/ include/ tests/ examples/ bench/ config/modules.json single/ docs/. Public headers stay in the xrt/ namespace, stitching seamlessly with kernel headers.

How tests and examples are organized

Test file name suffixes encode the test dimension, and the same contract appears in several variants (e.g. test_http_client_iocp.c is one #define line + #include "test_http_client.c"):

The kernel and five extensions provide 680 example C files and 2,512 test C files. Use the module manifests to find sources and build entries, then follow call flows into the implementation.

Suggested learning path

1. Get the build running: python tools/build.py --suite core; watch fingerprint increments and test output.
2. Read examples: pick a main.c from examples/ for a module you care about; understand setup, calls, and resource wind-down.
3. Read tests: pair with assertions in tests/<module>/ to understand interface behavior and boundary conditions.
4. Try trimming: use XRT_MODULE_* macros to carve out your minimal set and verify with --trim-only.

Resource links

• Gitee repository — sources and issue tracking
• API reference — per-API docs for 96 modules
• Architecture overview — kernel + extensions layering