leptris 1.9.201.2 → 1.9.201.4

data/vendor-src/libleptris/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+**libleptris** — pure C99 XML 1.0 parser, XPath 1.0 engine (W3C-conformant), and SAX parser. Ships as a static/shared library plus a `leptris` CLI. Zero required runtime deps; `utf8proc` (Unicode) and `iconv` (encoding conversion) are optional.
+
+## Build & Test
+
+CMake-based (CMake ≥ 3.20). The default build is a static lib + CLI + tests:
+
+```bash
+cmake -B build -S .
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+CI uses vcpkg for `utf8proc`, `iconv`, and `gtest` — pass `-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake` to use the same set.
+
+### CMake options worth knowing
+- `BUILD_TESTING` (ON) — builds the `test/` subdirectory with Google Test.
+- `LEPTRIS_BUILD_CLI` (ON) — builds the `leptris` executable.
+- `LEPTRIS_BUILD_BENCHMARKS` (OFF) — enables libxml2/pugixml comparison benchmarks under `benchmarks/`.
+- `LEPTRIS_BUILD_MAN_PAGES` (OFF) — generates man pages from `.adoc` via `cmake/modules/AdocMan.cmake`.
+- `LEPTRIS_ENABLE_UTF8PROC` / `LEPTRIS_ENABLE_ICONV` (ON/ON) — toggle Unicode/encoding features. Disabling compiles those `.c` files out via `LEPTRIS_HAS_*` macros.
+- `LEPTRIS_BUILD_STATIC` (ON) / `LEPTRIS_BUILD_SHARED` (OFF).
+
+### Useful targets
+- `leptris-cli` (output name `leptris`) — the CLI binary under `build/cli/`.
+- `leptris_static` / `leptris_shared` / alias `leptris::leptris`.
+- `benchmarks/dom_benchmark`, `benchmarks/bench_dom_pugixml` — when benchmarks are enabled.
+
+### Run a single test
+Tests are Google Test binaries under `build/test/`. Use `--gtest_filter`:
+```bash
+./build/test/c/test_dom --gtest_filter=TestName.TestCase
+./build/test/xpath/test_xpath --gtest_filter=Axes.*
+```
+
+### Full validation script
+`./scripts/validate.sh` does clean build → tests → CLI → DOM → XPath → benchmarks → memory leak check → element-size check (target ~96 bytes). Use this as a sanity check before claiming work is complete.
+
+### Memory leak checks
+- macOS: `leaks --atExit -- ./build/test/c/test_dom`
+- Linux: `valgrind --leak-check=full --error-exitcode=1 ./build/test/c/test_dom`
+
+## Architecture
+
+Three strict layers (top depends only on the layer below — never the reverse):
+
+```
+CLI (cli/)            →  argument parsing, output formatting, error reporting
+Public API (include/) →  leptris_parse_*, leptris_xpath_eval, leptris_document_*, ...
+Core (src/leptris/)    →  DOM, parser, XPath engine, SAX, DTD, encoding, memory
+```
+
+**The CLI never touches XML structures directly — it always goes through the public API in `src/include/leptris/`.** See `cli/CLI_ARCHITECTURE.md` for the design contract (MECE options, Open/Closed command registration, no `#ifdef` code guards — solve platform differences architecturally).
+
+### Core subsystems (`src/leptris/`)
+- `dom/` — node tree: `node`, `element`, `text`, `comment`, `cdata`, `pi`, `doctype`. **Compact architecture**: elements are ~96 bytes via compressed pointers; all node types begin with `LeptrisNode` so they're safely castable.
+- `parse/` — `parser_new.c` is the active parser; `compact_parser.c` is the compact-mode path. (Legacy `leptris_parse.c` / `parse_*.c` files at the subsystem root are older implementations — confirm which is wired in via `src/CMakeLists.txt` before editing.)
+- `xpath/` — split into `lexer`, `parser`, `evaluator` (with `_axes`, `_operators`, `_path`, `_types` companions), `functions`, and `xpath_variables`. The evaluator is the largest and most subtle piece; XPath 1.0 conformance is 438/438 against the W3C suite — don't regress it.
+- `sax/parser.c` — event-driven, no DOM construction.
+- `dtd/` — `parser`, `model`, `resolver`, `content_check`, `validator`. Phases 1–7 plus `#FIXED` are shipped: EMPTY/ANY/Mixed/Element content models, `#REQUIRED`/`#IMPLIED`/`#FIXED` attribute checking, attribute type validation. Phase 8 (ENTITY/ENTITIES attribute resolution, parameter entities, choice-model backtracking) is TODO 91.
+- `encoding/` — UTF-16 always compiled; `encoding.c` (iconv) only when `LEPTRIS_ENABLE_ICONV` is on.
+- `unicode/unicode.c` — only compiled when `LEPTRIS_ENABLE_UTF8PROC` is on.
+- `memory/` — `pool.c` (O(1) arena allocator used pervasively) and `compact_allocator.c`.
+- `xinclude/` — built and shipping. `parse="text"` with `xi:fallback` works end-to-end. `parse="xml"` and xpointer are TODO 92.
+
+### Public API surface (`src/include/leptris/`)
+The public contract. Don't break ABI without a major bump. Headers split by subsystem: `dom/{document,element,serialize}.h`, `xpath/xpath.h`, `sax/sax.h`, plus `types.h`, `error.h`, `dtd.h` at the top level. All handles are opaque typedefs (`LeptrisDocument`, `LeptrisElement`, `LeptrisNodeRef`, …); callers never see struct definitions.
+
+### Memory model
+- Pool allocator is the dominant allocation path — node creation should go through `leptris_node_create_pooled`.
+- Strings are stored as `StringView` (`common/string_view.{h,c}`) for zero-copy slicing during parse.
+- No reference counting; ownership is document-scoped — free via `leptris_document_free`.
+
+## Conventions
+
+- **C99, `-Wall -Wextra -Wno-unused-parameter`, warning-clean.** No GNU extensions (`C_EXTENSIONS OFF`). New warnings are bugs — fix them at the source, don't suppress.
+- Public types live in `src/include/leptris/types.h` (single canonical source); `leptris.h` includes it and adds the function declarations. See TODO 99.
+- Internal headers re-include `leptris/types.h` via `leptris_internal.h` → `memory/pool.h`; do not redeclare public typedefs locally.
+- Benchmarks are C++11.
+- Memory ownership in the public API is documented per-function in the headers (look for "Memory:" comments) — preserve these contracts. Strings returned as `const char*` from a `LeptrisDocument`-taking accessor are document-owned and live until `leptris_document_free`.
+- Error reporting goes through `LeptrisStatus` codes (`src/leptris/error.c`); the CLI wraps these via `cli/error.{h,c}`. Public-API entry points must write only public `LeptrisStatus` constants to their `LeptrisStatus*` out-params — the internal `leptris_error_code` enum is for `error.c`'s thread-local channel only (TODO 98).
+- Output formats in the CLI are MECE: XML / JSON / text — never mix. Adding a new command = new file in `cli/commands/` + registration in `main.c`. No changes to core infrastructure.
+- Man pages live under `cli/man/*.1.adoc` and `src/man/libleptris.5.adoc` and are only generated when `LEPTRIS_BUILD_MAN_PAGES=ON`.
+
+## Known repo state
+
+- `git log` is intentionally shallow on `main`; rely on `git log <path>` rather than expecting deep project history.
+- `test/` is a full Google Test tree (`dom`, `xpath`, `sax`, `dtd`, `xinclude`, `c14n`, `cli`, `abi`, `memory`, `parser`, `fuzz`). Add specs under the relevant subdirectory; CMake picks them up via `test/CMakeLists.txt`.
+
+## Where to look for context
+
+- `README.adoc` — exhaustive feature/API reference with examples (~2700 lines). The authoritative user-facing doc.
+- `cli/CLI_ARCHITECTURE.md` — CLI design contract (MECE, layers, extension points).
+- `cli/ARCHITECTURE_REVIEW.md` — review notes on the CLI design.
+- `docs/guide/building.md` — platform-specific build instructions.
+- `VALIDATION.md` — exact commands to run individual test suites and benchmarks, plus expected results.
+- `benchmarks/README.{md,adoc}` — benchmark methodology and reference comparisons.
+
+## Releasing — ALWAYS use the automated workflow
+
+**NEVER create git tags or GitHub releases manually.** No `git tag`, no
+`git push --tags`, no `gh release create`. These operations must go
+through the automated release workflow.
+
+### How to bump version and release
+
+1. Trigger the release workflow from the CLI:
+
+```bash
+# For a patch release (0.4.2 → 0.4.3):
+gh workflow run release.yml -f next_version=patch
+
+# For a minor release (0.4.2 → 0.5.0):
+gh workflow run release.yml -f next_version=minor
+
+# For a specific version:
+gh workflow run release.yml -f next_version=0.5.0
+```
+
+2. The workflow creates a `release/vX.Y.Z` branch with the version bump
+   (CMakeLists.txt, vcpkg.json, CHANGELOG.md) and opens a PR labeled
+   `release` + `automated`.
+
+3. Review the PR. Edit the CHANGELOG.md entry to add real release notes.
+   Merge the PR.
+
+4. When the PR is merged, the workflow automatically:
+   - Creates the git tag `vX.Y.Z`
+   - Publishes the GitHub Release with notes extracted from CHANGELOG.md
+
+### What the bump-version.sh script does
+
+`.github/scripts/bump-version.sh` reads the current version from git tags,
+calculates the next version, and updates three files:
+- `CMakeLists.txt` — `project(leptris VERSION ...)`
+- `vcpkg.json` — `"version"` field
+- `CHANGELOG.md` — new entry with template
+
+### Files that must stay in sync on version
+
+- `CMakeLists.txt` (project VERSION)
+- `vcpkg.json` (version field)
+- `CHANGELOG.md` (version header)
+
+The bump-version.sh script handles all three in one shot.

data/vendor-src/libleptris/CMakeLists.txt

@@ -0,0 +1,379 @@
+# Leptris - Fast XML Parser and XPath Evaluator
+# Pure C library with Ruby bindings and CLI
+cmake_minimum_required(VERSION 3.20)
+
+project(leptris
+    VERSION 1.9.201
+    DESCRIPTION "Fast XML parser and XPath evaluator in pure C"
+    LANGUAGES C CXX
+)
+
+# C11 standard required (was C99; bumped for _Static_assert, which
+# MSVC's C99 mode doesn't recognize as a keyword. C11 makes it
+# standard. VS2019 16.8+ supports C11; older MSVC fails the
+# CMAKE_C_STANDARD_REQUIRED check rather than silently building.)
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+
+# C++11 standard for benchmarks
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Build options
+option(BUILD_SHARED_LIBS "Build shared libraries" OFF)  # Default to static
+option(BUILD_TESTING "Build tests" ON)
+option(BUILD_EXAMPLES "Build examples" OFF)
+option(LEPTRIS_BUILD_CLI "Build CLI tool" ON)
+option(LEPTRIS_BUILD_MAN_PAGES "Generate man pages with asciidoctor" OFF)
+option(LEPTRIS_BUILD_BENCHMARKS "Build performance benchmarks" OFF)
+option(LEPTRIS_ENABLE_UTF8PROC "Enable Unicode support via utf8proc" ON)
+option(LEPTRIS_ENABLE_ICONV "Enable encoding conversion via iconv" ON)
+option(LEPTRIS_ENABLE_ASAN "Enable AddressSanitizer (catches heap bugs at runtime)" OFF)
+option(LEPTRIS_ENABLE_FUZZING "Build libFuzzer harness" OFF)
+option(LEPTRIS_BUILD_DOCS "Build Doxygen API docs" OFF)
+
+# LTO default: ON for Release/RelWithDebInfo, OFF for Debug/empty.
+# The user can override with -DLEPTRIS_ENABLE_LTO=OFF.
+# LTO delivers 1.3-3.5x speedups on parse/SAX/DOM benchmarks — see
+# PR #74 for the benchmark data.  Downside: 5-30s longer link time.
+# CheckIPOSupported guards against unsupported toolchains.
+if(NOT DEFINED LEPTRIS_ENABLE_LTO)
+    if(CMAKE_BUILD_TYPE STREQUAL "Release" OR CMAKE_BUILD_TYPE STREQUAL "RelWithDebInfo")
+        set(LEPTRIS_ENABLE_LTO_DEFAULT ON)
+    else()
+        set(LEPTRIS_ENABLE_LTO_DEFAULT OFF)
+    endif()
+else()
+    set(LEPTRIS_ENABLE_LTO_DEFAULT ${LEPTRIS_ENABLE_LTO})
+endif()
+option(LEPTRIS_ENABLE_LTO "Enable link-time optimization (default ON for Release)" ${LEPTRIS_ENABLE_LTO_DEFAULT})
+
+# Optimization level (TODO 167 Phase A). CMake's default for Release is
+# -O2; -O3 enables more aggressive inlining, loop transforms, and
+# auto-vectorization. Trade-off: larger binary, longer compile, occasionally
+# exposes latent UB.
+#
+#   default      — use CMake's choice (-O2 for Release)
+#   aggressive   — force -O3 for Release/RelWithDebInfo
+set(LEPTRIS_OPT_LEVEL "default" CACHE STRING "Optimization level: default (-O2) or aggressive (-O3)")
+set_property(CACHE LEPTRIS_OPT_LEVEL PROPERTY STRINGS default aggressive)
+
+# Target architecture (TODO 167 Phase B). -march=native lets the compiler use
+# the host's full ISA (AVX2, AVX-512, BMI2, etc). The resulting binary is NOT
+# portable to older CPUs — keep opt-in.
+#
+#   default   — baseline (runs on any x86-64 / ARM64)
+#   native    — -march=native (gcc/clang) or /arch:AVX2 (MSVC)
+set(LEPTRIS_TARGET_ARCH "default" CACHE STRING "Target CPU arch: default (portable) or native (host ISA)")
+set_property(CACHE LEPTRIS_TARGET_ARCH PROPERTY STRINGS default native)
+
+# AddressSanitizer — see TODO 35.
+if(LEPTRIS_ENABLE_ASAN)
+    add_compile_options(-fsanitize=address -fno-omit-frame-pointer -g)
+    add_link_options(-fsanitize=address)
+    message(STATUS "AddressSanitizer: ENABLED")
+endif()
+
+# Link-time optimization (TODO 110).
+#
+# Lets the compiler inline across translation-unit boundaries.  Without
+# LTO, every "static inline" helper in element_modify.c / element_query.c
+# that crosses a TU boundary from a caller in another .c file is a real
+# function call — including leptris_pool_alloc, leptris_element_set_attribute,
+# the chartype table lookups, etc.  With LTO, the compiler sees the whole
+# program at link time and inlines aggressively.
+#
+# Off by default because:
+#   - LTO significantly increases link time (5-30s for leptris)
+#   - Some older toolchains have LTO bugs
+#   - Debug builds don't benefit
+#
+# Recommended for release builds where every cycle counts.
+if(LEPTRIS_ENABLE_LTO)
+    include(CheckIPOSupported)
+    check_ipo_supported(RESULT lto_supported OUTPUT lto_error)
+    if(lto_supported)
+        set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
+        message(STATUS "Link-time optimization: ENABLED")
+    else()
+        message(WARNING "LEPTRIS_ENABLE_LTO requested but not supported: ${lto_error}")
+    endif()
+endif()
+
+# Optimization level (TODO 167 Phase A).
+if(LEPTRIS_OPT_LEVEL STREQUAL "aggressive")
+    if(CMAKE_C_COMPILER_ID STREQUAL "GNU" OR CMAKE_C_COMPILER_ID STREQUAL "Clang"
+       OR CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+        # CMake sets -O2 by default for Release; -O3 replaces it.
+        # Apply to both C and CXX so benchmarks get the same flag.
+        foreach(_lang C CXX)
+            foreach(_cfg RELEASE RELWITHDEBINFO)
+                string(REPLACE "-O2" "-O3"
+                    CMAKE_${_lang}_FLAGS_${_cfg}
+                    "${CMAKE_${_lang}_FLAGS_${_cfg}}")
+                # If -O2 wasn't there (rare), append -O3 explicitly.
+                if(NOT CMAKE_${_lang}_FLAGS_${_cfg} MATCHES "-O3")
+                    set(CMAKE_${_lang}_FLAGS_${_cfg} "${CMAKE_${_lang}_FLAGS_${_cfg}} -O3")
+                endif()
+            endforeach()
+        endforeach()
+        message(STATUS "Optimization level: -O3 (aggressive)")
+    elseif(MSVC)
+        # /O2 is the Release default; /O3 doesn't exist as a separate flag in
+        # MSVC (the equivalent aggressiveness is /O2 + /GL + /Gw + /Gy). LTO
+        # already covers /GL. Add the others.
+        add_compile_options(/Gw /Gy)
+        message(STATUS "Optimization level: /O2 + /Gw + /Gy (MSVC aggressive)")
+    endif()
+else()
+    message(STATUS "Optimization level: default (-O2)")
+endif()
+
+# Target architecture (TODO 167 Phase B).
+if(LEPTRIS_TARGET_ARCH STREQUAL "native")
+    if(CMAKE_C_COMPILER_ID STREQUAL "GNU" OR CMAKE_C_COMPILER_ID STREQUAL "Clang"
+       OR CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+        add_compile_options(-march=native)
+        message(STATUS "Target architecture: native (-march=native)")
+    elseif(MSVC)
+        add_compile_options(/arch:AVX2)
+        message(STATUS "Target architecture: AVX2 (/arch:AVX2)")
+    endif()
+else()
+    message(STATUS "Target architecture: default (portable)")
+endif()
+
+# Check for compile flag support — must precede the first
+# check_c_compiler_flag use below (TODO 167 Phase C shared builds
+# failed to configure on Clang when it sat after it).
+include(CheckCCompilerFlag)
+
+# -fno-semantic-interposition for shared libs (TODO 167 Phase C).
+# Allows GCC/Clang to inline exported symbols into callers within the same
+# shared object, and lets LLVM's optimizer treat the public API as
+# non-interposable. ~5% on shared builds. No effect on static builds.
+if(BUILD_SHARED_LIBS)
+    if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+        add_compile_options(-fno-semantic-interposition)
+        message(STATUS "Semantic interposition: disabled (shared-lib build)")
+    elseif(CMAKE_C_COMPILER_ID STREQUAL "Clang" OR CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+        # Clang defaults to -fno-semantic-interposition behavior (it doesn't
+        # allow interposition of defined symbols anyway), but explicitly
+        # setting -fvisibility-no-protects the inlining decision.
+        # Apple Clang ignores the flag; suppress the warning.
+        check_c_compiler_flag("-fno-semantic-interposition" _leptris_fsi_supported)
+        if(_leptris_fsi_supported)
+            add_compile_options(-fno-semantic-interposition)
+            message(STATUS "Semantic interposition: disabled (shared-lib build)")
+        endif()
+    endif()
+endif()
+
+# libFuzzer — see TODO 40.  Implies ASAN.
+if(LEPTRIS_ENABLE_FUZZING)
+    add_compile_options(-fsanitize=fuzzer-no-link,address -fno-omit-frame-pointer -g)
+    add_link_options(-fsanitize=fuzzer,address)
+    message(STATUS "libFuzzer: ENABLED (implies ASAN)")
+endif()
+
+# Profile-guided optimization (TODO 159 Phase F).
+#
+# Three-step build process:
+#   1. cmake -B build-pgo -DLEPTRIS_ENABLE_PGO=GENERATE ...
+#      cmake --build build-pgo
+#   2. Run a representative workload against the instrumented binary
+#      (e.g. `ctest --test-dir build-pgo` or your app's test suite).
+#      For clang: `llvm-profdata merge build-pgo/pgo-data/*.profraw
+#      -o build-pgo/pgo-data/default.profdata` between steps 2 and 3.
+#      GCC and MSVC generate the profile directly.
+#   3. cmake -B build-pgo -DLEPTRIS_ENABLE_PGO=USE ...
+#      cmake --build build-pgo
+#
+# Closes the switch-dispatch gap vs computed-goto without GCC-isms.
+# Clang, GCC, and MSVC all support PGO.
+#
+# Defaults to OFF because it's a two-pass build and most users won't
+# bother. Distributions / packagers who want the last ~10-15% on the
+# XPath VM dispatch loop should enable it; on the DOM parse path the
+# measured gain is smaller (~1-2%, TODO 185 round 3).
+set(LEPTRIS_ENABLE_PGO "OFF" CACHE STRING "Profile-guided optimization phase: OFF, GENERATE, or USE")
+set_property(CACHE LEPTRIS_ENABLE_PGO PROPERTY STRINGS OFF GENERATE USE)
+set(LEPTRIS_PGO_DIR "${CMAKE_BINARY_DIR}/pgo-data" CACHE PATH "PGO profile directory")
+
+if(NOT LEPTRIS_ENABLE_PGO STREQUAL "OFF")
+    if(CMAKE_C_COMPILER_ID STREQUAL "Clang" OR CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+        if(LEPTRIS_ENABLE_PGO STREQUAL "GENERATE")
+            add_compile_options(-fprofile-instr-generate=${LEPTRIS_PGO_DIR}/default.profraw)
+            add_link_options(-fprofile-instr-generate=${LEPTRIS_PGO_DIR}/default.profraw)
+            file(MAKE_DIRECTORY ${LEPTRIS_PGO_DIR})
+            message(STATUS "PGO (clang): GENERATE → ${LEPTRIS_PGO_DIR}")
+        elseif(LEPTRIS_ENABLE_PGO STREQUAL "USE")
+            add_compile_options(-fprofile-instr-use=${LEPTRIS_PGO_DIR}/default.profdata)
+            message(STATUS "PGO (clang): USE ← ${LEPTRIS_PGO_DIR}/default.profdata")
+        endif()
+    elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+        if(LEPTRIS_ENABLE_PGO STREQUAL "GENERATE")
+            add_compile_options(-fprofile-generate=${LEPTRIS_PGO_DIR})
+            add_link_options(-fprofile-generate=${LEPTRIS_PGO_DIR})
+            file(MAKE_DIRECTORY ${LEPTRIS_PGO_DIR})
+            message(STATUS "PGO (gcc): GENERATE → ${LEPTRIS_PGO_DIR}")
+        elseif(LEPTRIS_ENABLE_PGO STREQUAL "USE")
+            add_compile_options(-fprofile-use=${LEPTRIS_PGO_DIR} -Wno-coverage-mismatch)
+            message(STATUS "PGO (gcc): USE ← ${LEPTRIS_PGO_DIR}")
+        endif()
+    elseif(MSVC)
+        if(LEPTRIS_ENABLE_PGO STREQUAL "GENERATE")
+            add_compile_options(/GL)
+            add_link_options(/GENPROFILE:${LEPTRIS_PGO_DIR} /LTCG)
+            file(MAKE_DIRECTORY ${LEPTRIS_PGO_DIR})
+            message(STATUS "PGO (MSVC): GENERATE → ${LEPTRIS_PGO_DIR}")
+        elseif(LEPTRIS_ENABLE_PGO STREQUAL "USE")
+            add_compile_options(/GL)
+            add_link_options(/USEPROFILE:${LEPTRIS_PGO_DIR} /LTCG)
+            message(STATUS "PGO (MSVC): USE ← ${LEPTRIS_PGO_DIR}")
+        endif()
+    else()
+        message(WARNING "LEPTRIS_ENABLE_PGO=${LEPTRIS_ENABLE_PGO} not supported for ${CMAKE_C_COMPILER_ID}; ignoring")
+    endif()
+endif()
+
+# Doxygen API docs — see TODO 63.
+if(LEPTRIS_BUILD_DOCS)
+    find_package(Doxygen)
+    if(DOXYGEN_FOUND)
+        add_custom_target(docs
+            COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_SOURCE_DIR}/docs/Doxyfile
+            WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/docs
+            COMMENT "Generating Doxygen API documentation")
+        message(STATUS "Doxygen: ENABLED (target: docs)")
+    else()
+        message(WARNING "LEPTRIS_BUILD_DOCS=ON but Doxygen not found; skipping")
+    endif()
+endif()
+
+# Position independent code for static libraries
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Hide all symbols by default; the public surface is exactly the
+# functions marked LEPTRIS_API. Cuts the shared-library export table
+# from ~445 entries down to the ~295 leptris_* symbols. See TODO 80.
+set(CMAKE_C_VISIBILITY_PRESET hidden)
+set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
+
+# Configuration
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# Add cmake modules path
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules")
+
+# Include AdocMan for man page generation
+if(LEPTRIS_BUILD_MAN_PAGES)
+    include(AdocMan)
+endif()
+
+# Add subdirectories
+add_subdirectory(src)
+
+if(LEPTRIS_BUILD_CLI)
+    add_subdirectory(cli)
+endif()
+
+if(BUILD_TESTING)
+    enable_testing()
+    add_subdirectory(test)
+endif()
+
+if(BUILD_EXAMPLES)
+    add_subdirectory(examples/c)
+endif()
+
+if(LEPTRIS_BUILD_BENCHMARKS)
+    add_subdirectory(benchmarks)
+endif()
+
+# Zero-copy test executable (disabled - not needed for benchmarks)
+# add_executable(test_zero_copy test_zero_copy.c)
+# target_link_libraries(test_zero_copy leptris)
+
+# Install CMake config files
+include(CMakePackageConfigHelpers)
+include(GNUInstallDirs)
+
+write_basic_package_version_file(
+    "${CMAKE_CURRENT_BINARY_DIR}/leptris-config-version.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+)
+
+configure_package_config_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/leptris-config.cmake.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/leptris-config.cmake"
+    INSTALL_DESTINATION lib/cmake/leptris
+)
+
+install(FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/leptris-config.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/leptris-config-version.cmake"
+    DESTINATION lib/cmake/leptris
+)
+
+
+# pkg-config file
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/leptris.pc.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/leptris.pc"
+    @ONLY
+)
+
+install(FILES "${CMAKE_CURRENT_BINARY_DIR}/leptris.pc"
+    DESTINATION lib/pkgconfig
+)
+
+# Generate and install man pages (when building CLI)
+if(LEPTRIS_BUILD_CLI AND LEPTRIS_BUILD_MAN_PAGES)
+    # Use AdocMan.cmake to generate man pages from AsciiDoc sources
+    # CLI man pages (section 1): cli/man/leptris.1.adoc, etc.
+    set(ADOC_MAN_SOURCES
+        cli/man/leptris.1.adoc
+        cli/man/leptris-parse.1.adoc
+        cli/man/leptris-xpath.1.adoc
+        cli/man/leptris-format.1.adoc
+    )
+
+    foreach(ADOC_SOURCE ${ADOC_MAN_SOURCES})
+        if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${ADOC_SOURCE}")
+            add_adoc_man("${CMAKE_CURRENT_SOURCE_DIR}/${ADOC_SOURCE}")
+        endif()
+    endforeach()
+endif()
+
+# Generate library API man page (section 5)
+if(LEPTRIS_BUILD_MAN_PAGES)
+    # Library man page (section 5): src/man/libleptris.5.adoc
+    set(LIB_MAN_SOURCE src/man/libleptris.5.adoc)
+
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${LIB_MAN_SOURCE}")
+        add_adoc_man("${CMAKE_CURRENT_SOURCE_DIR}/${LIB_MAN_SOURCE}")
+    endif()
+endif()
+
+# Summary
+message(STATUS "")
+message(STATUS "Leptris ${PROJECT_VERSION} Configuration:")
+message(STATUS "  C Compiler: ${CMAKE_C_COMPILER}")
+message(STATUS "  C Standard: C${CMAKE_C_STANDARD}")
+message(STATUS "  Build Type: ${CMAKE_BUILD_TYPE}")
+message(STATUS "  Optimization Level: ${LEPTRIS_OPT_LEVEL}")
+message(STATUS "  Target Architecture: ${LEPTRIS_TARGET_ARCH}")
+message(STATUS "  Shared Libraries: ${BUILD_SHARED_LIBS}")
+message(STATUS "  Build Tests: ${BUILD_TESTING}")
+message(STATUS "  Build Examples: ${BUILD_EXAMPLES}")
+message(STATUS "  Build CLI: ${LEPTRIS_BUILD_CLI}")
+message(STATUS "  Generate Man Pages: ${LEPTRIS_BUILD_MAN_PAGES}")
+message(STATUS "  Install Prefix: ${CMAKE_INSTALL_PREFIX}")
+message(STATUS "")
+# Update the summary to include benchmarks
+message(STATUS "  Build Benchmarks: ${LEPTRIS_BUILD_BENCHMARKS}")

data/vendor-src/libleptris/CMakePresets.json

@@ -0,0 +1,61 @@
+{
+  "version": 3,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 21,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "default",
+      "displayName": "Default portable Release build",
+      "binaryDir": "${sourceDir}/build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "fast",
+      "displayName": "Maximum single-machine throughput (non-portable)",
+      "description": "Bundles -O3, -march=native, LTO, and static linking. Use for production builds on the host CPU only.",
+      "binaryDir": "${sourceDir}/build-fast",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "LEPTRIS_OPT_LEVEL": "aggressive",
+        "LEPTRIS_TARGET_ARCH": "native",
+        "LEPTRIS_ENABLE_LTO": "ON",
+        "BUILD_SHARED_LIBS": "OFF"
+      }
+    },
+    {
+      "name": "pgo-generate",
+      "displayName": "PGO instrumentation pass",
+      "description": "Build with PGO instrumentation; run your workload, then re-configure with 'pgo-use'.",
+      "binaryDir": "${sourceDir}/build-pgo",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "LEPTRIS_ENABLE_PGO": "GENERATE"
+      }
+    },
+    {
+      "name": "pgo-use",
+      "displayName": "PGO optimized build",
+      "description": "Re-uses the profile generated by 'pgo-generate'. Run ctest or your app between the two passes.",
+      "binaryDir": "${sourceDir}/build-pgo",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release",
+        "LEPTRIS_ENABLE_PGO": "USE",
+        "LEPTRIS_ENABLE_LTO": "ON"
+      }
+    },
+    {
+      "name": "debug",
+      "displayName": "Debug build with ASAN",
+      "binaryDir": "${sourceDir}/build-debug",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "LEPTRIS_ENABLE_ASAN": "ON"
+      }
+    }
+  ]
+}