LEPTRIS

Getting started — the C core

Build libleptris v1.9.156 from source or vcpkg, link it into a C99 project, and parse your first document in under a minute.

Requirements

  • CMake ≥ 3.20 and a C99 compiler (GCC, Clang, MSVC, MinGW).
  • Optional: utf8proc (Unicode validation) and iconv (encoding conversion). Neither is required — builds without them have zero runtime dependencies.

Build from source

clone + release build
git clone https://github.com/leptris/leptris.git
cd leptris
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo cmake --install build --prefix /usr/local

LTO is enabled by default for Release andRelWithDebInfo builds. Disable it with-DLEPTRIS_ENABLE_LTO=OFF if your toolchain cannot link LTO objects.

Install from vcpkg

bash
git clone https://github.com/microsoft/vcpkg
./vcpkg/vcpkg install leptris

The repository ships a vcpkg.json manifest and aportfile.cmake template following the jemalloc convention. System packages (Homebrew, apt, apk, MSYS2) are pending — watch the changelog.

Link it

After installation the library is discoverable three ways:

CMake — the import target
cmake_minimum_required(VERSION 3.20)
project(myapp LANGUAGES C CXX)

find_package(leptris CONFIG REQUIRED)
target_link_libraries(myapp PRIVATE leptris::leptris)
Meson
leptris_dep = dependency('leptris')
executable('your_app', 'main.c', dependencies: leptris_dep)
pkg-config
gcc myapp.c $(pkg-config --cflags --libs leptris)

First program

hello-parse.c
#include <leptris.h>
#include <stdio.h>
#include <string.h>

int main(void) {
    const char* xml = "<root><item>hello</item></root>";

    LeptrisStatus status = LEPTRIS_OK;
    LeptrisDocument doc = leptris_parse_string(xml, strlen(xml), &status);
    if (!doc) {
        fprintf(stderr, "parse failed: %d\n", status);
        return 1;
    }

    LeptrisElement root = leptris_document_root(doc);
    printf("root element: %s\n", leptris_element_name(root));

    LeptrisXPathResult items = leptris_xpath_eval(doc, NULL, "//item");
    printf("item count: %zu\n", leptris_xpath_result_count(items));
    leptris_xpath_result_free(items);

    leptris_document_free(doc);  /* releases the entire pool */
    return 0;
}

Build options

optiondefaultdescription
BUILD_TESTINGONBuild the Google Test suite under test/.
LEPTRIS_BUILD_CLIONBuild the leptris command-line tool.
LEPTRIS_BUILD_BENCHMARKSOFFPerformance comparison targets (libxml2 / pugixml).
LEPTRIS_BUILD_MAN_PAGESOFFGenerate man pages from the AsciiDoc sources.
LEPTRIS_ENABLE_UTF8PROCONUTF-8 validation via utf8proc.
LEPTRIS_ENABLE_ICONVONEncoding conversion via iconv (ISO-8859-1, Shift-JIS, …).
LEPTRIS_ENABLE_ASANOFFBuild with AddressSanitizer.
LEPTRIS_ENABLE_FUZZINGOFFBuild the libFuzzer harness.
LEPTRIS_BUILD_DOCSOFFGenerate the Doxygen API reference.

Development builds

ASAN — memory safety
cmake -B build-asan -S . -DLEPTRIS_ENABLE_ASAN=ON -DBUILD_TESTING=ON
cmake --build build-asan
ASAN_OPTIONS=detect_leaks=1 ctest --test-dir build-asan
Fuzzer (requires LLVM clang)
brew install llvm   # macOS
export CC=/opt/homebrew/opt/llvm/bin/clang
cmake -B build-fuzz -S . -DLEPTRIS_ENABLE_FUZZING=ON
cmake --build build-fuzz --target fuzz_parse
./build-fuzz/fuzz_parse -max_total_time=600 corpus/
Doxygen API reference
brew install doxygen
cmake -B build -S . -DLEPTRIS_BUILD_DOCS=ON
cmake --build build --target docs
open build/docs/api-generated/html/index.html

Where next

This is the curated guide. The repositories are canonical: when this page and the repo disagree, the repo wins. Full documentation lives with the source.