feat(capi): add xet_capi C ABI crate for hf-xet

.github/workflows/ci.yml

@@ -181,6 +181,35 @@ jobs:
           source .venv/bin/activate
           pip install pytest
           pytest hf_xet/tests/ -v
+  build_and_test-capi:
+    name: C API (xet_capi)
+    runs-on:
+      group: aws-general-8-plus
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: huggingface/hf-workflows/.github/actions/setup-hf-registry-proxies@21845492ef47d4e46b07a3b2a6e14fd4748c39cc  # main
+      - name: Install Rust 1.94
+        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9  # master
+        with:
+          toolchain: 1.94.1
+      - uses: ./.github/actions/cache-rust-build
+      - name: FFI tests (header up-to-date, ABI round-trip)
+        # Covers the Rust-side FFI suite: header freshness (cbindgen), smoke.c
+        # compilation against the committed header, and an end-to-end upload ->
+        # commit -> download round-trip over a local CAS (simulation feature, no
+        # network).
+        run: |
+          cargo test -p xet_capi --features simulation --verbose --no-fail-fast
+      - name: Link and run C smoke test against the built library
+        # The Rust c_smoke_compiles test only compiles the translation unit; here
+        # we link smoke.c against the actual cdylib and run it, exercising real
+        # ABI linkage end to end.
+        run: |
+          set -eux
+          cargo build -p xet_capi --release
+          cc xet_capi/tests/smoke.c -Ixet_capi/include -Ltarget/release -lxet_capi -o "$RUNNER_TEMP/xet_capi_smoke"
+          LD_LIBRARY_PATH=target/release "$RUNNER_TEMP/xet_capi_smoke"
   build_and_test-wasm:
     name: Build WASM
     runs-on:

.gitignore

@@ -22,3 +22,10 @@ venv
 **/*.env
 .worktrees/
 **/node_modules/
+
+# Swift toolchain installer artifacts (swiftly)
+/swiftly.pkg
+/.swift-version
+
+# Doxygen-generated API docs for xet_capi
+xet_capi/docs/

Cargo.toml

@@ -7,6 +7,7 @@ members = [
     "xet_client",
     "xet_data",
     "xet_pkg",
+    "xet_capi",
 
     # Top-level crates (not published as packages)
     "git_xet",

xet_capi/CMakeLists.txt

@@ -0,0 +1,78 @@
+# CMake integration for the hf_xet C/C++ API.
+#
+# Consumers add this directory and link the imported `xet_capi` target:
+#
+#   add_subdirectory(/path/to/xet-core/xet_capi xet_capi)
+#   target_link_libraries(my_target PRIVATE xet_capi)
+#
+# The target carries the include directory for `hf_xet.h` (C API). A
+# header-only C++ wrapper (`xet_session.hpp`, requires C++17) lives alongside
+# the C++ example in examples/cpp/.
+#
+# Requires a Rust toolchain; the library is built with `cargo build -p xet_capi`.
+# Linking is static by default (set XET_CAPI_SHARED=ON for the shared library).
+# CARGO_TARGET_DIR overrides are not supported; the workspace target directory
+# is assumed to be <xet-core>/target.
+
+cmake_minimum_required(VERSION 3.15)
+project(xet_capi LANGUAGES C)
+
+option(XET_CAPI_SHARED "Link the shared xet_capi library instead of the static one" OFF)
+
+find_program(XET_CAPI_CARGO cargo REQUIRED)
+
+set(XET_CAPI_CRATE_DIR  ${CMAKE_CURRENT_SOURCE_DIR})
+set(XET_CAPI_TARGET_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../target)
+
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+    set(XET_CAPI_PROFILE     debug)
+    set(XET_CAPI_CARGO_FLAGS "")
+else()
+    set(XET_CAPI_PROFILE     release)
+    set(XET_CAPI_CARGO_FLAGS --release)
+endif()
+
+if(XET_CAPI_SHARED)
+    set(XET_CAPI_LIB_FILE
+        ${XET_CAPI_TARGET_DIR}/${XET_CAPI_PROFILE}/${CMAKE_SHARED_LIBRARY_PREFIX}xet_capi${CMAKE_SHARED_LIBRARY_SUFFIX})
+else()
+    set(XET_CAPI_LIB_FILE
+        ${XET_CAPI_TARGET_DIR}/${XET_CAPI_PROFILE}/${CMAKE_STATIC_LIBRARY_PREFIX}xet_capi${CMAKE_STATIC_LIBRARY_SUFFIX})
+endif()
+
+# cargo tracks Rust source changes itself; run it on every build (no-op when fresh).
+add_custom_target(xet_capi_cargo
+    COMMAND ${XET_CAPI_CARGO} build -p xet_capi ${XET_CAPI_CARGO_FLAGS}
+    WORKING_DIRECTORY ${XET_CAPI_CRATE_DIR}
+    BYPRODUCTS ${XET_CAPI_LIB_FILE}
+    VERBATIM USES_TERMINAL
+    COMMENT "Building xet_capi with cargo (${XET_CAPI_PROFILE})"
+)
+
+if(XET_CAPI_SHARED)
+    add_library(xet_capi SHARED IMPORTED GLOBAL)
+else()
+    add_library(xet_capi STATIC IMPORTED GLOBAL)
+endif()
+add_dependencies(xet_capi xet_capi_cargo)
+
+set_target_properties(xet_capi PROPERTIES
+    IMPORTED_LOCATION             ${XET_CAPI_LIB_FILE}
+    INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+# System libraries required by the Rust static library
+# (from `cargo rustc -p xet_capi --release -- --print native-static-libs`).
+if(NOT XET_CAPI_SHARED)
+    if(APPLE)
+        set_property(TARGET xet_capi APPEND PROPERTY INTERFACE_LINK_LIBRARIES
+            "-framework Security" "-framework CoreFoundation" "-framework SystemConfiguration"
+            "-framework IOKit" objc iconv)
+    elseif(WIN32)
+        set_property(TARGET xet_capi APPEND PROPERTY INTERFACE_LINK_LIBRARIES
+            ws2_32 userenv bcrypt ntdll crypt32 secur32 ncrypt)
+    elseif(UNIX)
+        set_property(TARGET xet_capi APPEND PROPERTY INTERFACE_LINK_LIBRARIES
+            pthread dl m)
+    endif()
+endif()

xet_capi/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "xet_capi"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+description = "C ABI bindings for the Hugging Face Xet client (hf-xet)."
+
+[lib]
+name = "xet_capi"
+crate-type = ["cdylib", "staticlib", "rlib"]
+
+[dependencies]
+xet = { package = "hf-xet", version = "1.5.2", path = "../xet_pkg" }
+bytes = { workspace = true }
+
+[build-dependencies]
+cbindgen = "0.29"
+
+[dev-dependencies]
+cbindgen = "0.29"
+cc = "1"
+tempfile = { workspace = true }
+
+[features]
+simulation = ["xet/simulation"]
+
+[package.metadata.cargo-machete]
+ignored = ["xet"]