feat: support pkg-config and version metadata

Author: xz-dev

.github/workflows/ci.yml

@@ -71,7 +71,7 @@ jobs:
       - run: cargo clippy --all-targets --all-features -- -D warnings
 
   test:
-    name: Test
+    name: Test (vendored)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -80,3 +80,23 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
       - run: sudo apt-get update && sudo apt-get install -y libclang-dev
       - run: cargo test
+
+  test-system:
+    name: Test (system libversion)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+      - uses: dtolnay/rust-toolchain@stable
+      - run: sudo apt-get update && sudo apt-get install -y cmake libclang-dev pkg-config
+      - name: Build and install libversion for pkg-config mode
+        run: |
+          cmake -S libversion -B "$RUNNER_TEMP/libversion-build" -DCMAKE_INSTALL_PREFIX="$RUNNER_TEMP/libversion-install"
+          cmake --build "$RUNNER_TEMP/libversion-build"
+          cmake --install "$RUNNER_TEMP/libversion-build"
+      - name: Test without vendored feature
+        run: cargo test --no-default-features
+        env:
+          PKG_CONFIG_PATH: ${{ runner.temp }}/libversion-install/lib/pkgconfig:${{ runner.temp }}/libversion-install/lib64/pkgconfig
+          LD_LIBRARY_PATH: ${{ runner.temp }}/libversion-install/lib:${{ runner.temp }}/libversion-install/lib64

Cargo.lock

@@ -9,8 +9,16 @@ license = "MIT"
 repository = "https://github.com/DUpdateSystem/libversion-sys"
 homepage = "https://github.com/DUpdateSystem/libversion-sys"
 documentation = "https://docs.rs/libversion-sys"
+readme = "README.md"
+keywords = ["ffi", "version", "comparison", "bindings"]
+categories = ["external-ffi-bindings", "algorithms"]
 exclude = [".github/", ".gitignore", ".gitmodules", "scripts/"]
 
+[features]
+default = ["vendored"]
+vendored = []
+
 [build-dependencies]
 cc = "1"
 bindgen = "0.72"
+pkg-config = "0.3"

Cargo.toml

@@ -6,15 +6,29 @@
 
 Rust FFI bindings to [libversion](https://github.com/repology/libversion), an advanced version string comparison library.
 
-The C source is included and compiled from source via CMake -- no system-level installation of libversion is required.
+By default the crate vendors the C source and builds it directly, so no system-level installation of libversion is required. If you prefer linking an installed system copy, disable default features and make sure `pkg-config` can find `libversion`.
 
 ## Usage
 
 Add to `Cargo.toml`:
 
 ```toml
 [dependencies]
-libversion-sys = "0.1"
+libversion-sys = "0.2"
+```
+
+Use the default vendored build:
+
+```toml
+[dependencies]
+libversion-sys = "0.2"
+```
+
+Or link a system-installed `libversion`:
+
+```toml
+[dependencies]
+libversion-sys = { version = "0.2", default-features = false }
 ```
 
 ### Safe API
@@ -46,6 +60,13 @@ let result = unsafe { ffi::version_compare2(v1.as_ptr(), v2.as_ptr()) };
 assert_eq!(result, -1);
 ```
 
+### Version metadata
+
+```rust
+assert!(libversion_sys::version_atleast(3, 0, 0));
+assert!(!libversion_sys::version_string().is_empty());
+```
+
 ## Flags
 
 | Flag | Description |
@@ -58,16 +79,24 @@ assert_eq!(result, -1);
 ## Build requirements
 
 - Rust (stable)
-- CMake
-- C compiler (gcc/clang)
+- C compiler (gcc/clang) for the default vendored build
 - libclang (for bindgen)
+- `pkg-config` and a system `libversion` installation when building with `default-features = false`
 
 On Ubuntu/Debian:
 
 ```sh
-sudo apt-get install cmake libclang-dev
+sudo apt-get install libclang-dev
 ```
 
+For system linking:
+
+```sh
+sudo apt-get install pkg-config libversion-dev
+```
+
+`cmake` is only needed by maintainers when regenerating `generated/libversion/config.h` and `generated/libversion/export.h` after updating the vendored libversion source.
+
 ## License
 
 MIT -- see [LICENSE](LICENSE).

README.md

@@ -2,34 +2,57 @@ use std::env;
 use std::path::PathBuf;
 
 fn main() {
-    // Build libversion static library using cc.
-    // The cmake-generated headers (config.h, export.h) are pre-committed under
-    // generated/ — run `bash scripts/generate-headers.sh` to regenerate them
-    // whenever the libversion submodule is updated.
-    cc::Build::new()
-        .file("libversion/libversion/compare.c")
-        .file("libversion/libversion/private/compare.c")
-        .file("libversion/libversion/private/parse.c")
-        .include("libversion") // source headers (libversion/version.h, etc.)
-        .include("generated") // pre-generated headers (libversion/config.h, libversion/export.h)
-        .define("LIBVERSION_STATIC_DEFINE", None)
-        .compile("version");
+    let include_paths = if env::var_os("CARGO_FEATURE_VENDORED").is_some() {
+        build_vendored();
+        vec![PathBuf::from("generated"), PathBuf::from("libversion")]
+    } else {
+        find_system_lib()
+    };
 
-    // Generate FFI bindings via bindgen
-    let bindings = bindgen::Builder::default()
+    let mut bindings = bindgen::Builder::default()
         .header("wrapper.h")
-        .clang_arg("-Igenerated") // pre-generated config.h, export.h
-        .clang_arg("-Ilibversion") // source headers
-        .clang_arg("-DLIBVERSION_STATIC_DEFINE")
         .default_enum_style(bindgen::EnumVariation::Consts)
         .allowlist_function("version_compare.*")
         .allowlist_var("VERSIONFLAG_.*")
+        .allowlist_var("LIBVERSION_VERSION.*")
         .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
-        .generate()
-        .expect("Unable to generate bindings");
+        .clang_args(
+            include_paths
+                .iter()
+                .map(|path| format!("-I{}", path.display())),
+        );
+
+    if env::var_os("CARGO_FEATURE_VENDORED").is_some() {
+        bindings = bindings.clang_arg("-DLIBVERSION_STATIC_DEFINE");
+    }
+
+    let bindings = bindings.generate().expect("Unable to generate bindings");
 
     let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
     bindings
         .write_to_file(out_path.join("bindings.rs"))
         .expect("Couldn't write bindings!");
 }
+
+fn build_vendored() {
+    // Build libversion from vendored C sources. The cmake-generated headers
+    // (config.h, export.h) are pre-committed under generated/ so end users do
+    // not need cmake installed for the default build.
+    cc::Build::new()
+        .file("libversion/libversion/compare.c")
+        .file("libversion/libversion/private/compare.c")
+        .file("libversion/libversion/private/parse.c")
+        .include("libversion")
+        .include("generated")
+        .define("LIBVERSION_STATIC_DEFINE", None)
+        .compile("version");
+}
+
+fn find_system_lib() -> Vec<PathBuf> {
+    let library = pkg_config::Config::new()
+        .atleast_version("3.0.0")
+        .probe("libversion")
+        .expect("failed to find system libversion via pkg-config; enable the vendored feature or install libversion.pc");
+
+    library.include_paths
+}

build.rs

@@ -20,6 +20,7 @@ pub mod ffi {
 }
 
 pub use ffi::{
+    LIBVERSION_VERSION_MAJOR, LIBVERSION_VERSION_MINOR, LIBVERSION_VERSION_PATCH,
     VERSIONFLAG_ANY_IS_PATCH, VERSIONFLAG_LOWER_BOUND, VERSIONFLAG_P_IS_PATCH,
     VERSIONFLAG_UPPER_BOUND, version_compare2, version_compare4,
 };
@@ -79,6 +80,22 @@ pub fn compare_with_flags(v1: &str, v2: &str, v1_flags: u32, v2_flags: u32) -> O
     result.cmp(&0)
 }
 
+/// Returns the libversion release string from the headers used during build.
+pub fn version_string() -> &'static str {
+    std::str::from_utf8(&ffi::LIBVERSION_VERSION[..ffi::LIBVERSION_VERSION.len() - 1])
+        .expect("libversion version string is not valid UTF-8")
+}
+
+/// Rust equivalent of the `LIBVERSION_VERSION_ATLEAST` macro.
+#[allow(clippy::absurd_extreme_comparisons)]
+pub const fn version_atleast(major: u32, minor: u32, patch: u32) -> bool {
+    (LIBVERSION_VERSION_MAJOR > major)
+        || (LIBVERSION_VERSION_MAJOR == major && LIBVERSION_VERSION_MINOR > minor)
+        || (LIBVERSION_VERSION_MAJOR == major
+            && LIBVERSION_VERSION_MINOR == minor
+            && LIBVERSION_VERSION_PATCH >= patch)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -115,11 +132,89 @@ mod tests {
         );
     }
 
+    #[test]
+    fn any_is_patch_flag() {
+        assert_eq!(compare("1.0foopatchset1", "1.0"), Ordering::Less);
+        assert_eq!(
+            compare_with_flags("1.0foopatchset1", "1.0", VERSIONFLAG_ANY_IS_PATCH, 0),
+            Ordering::Greater,
+        );
+    }
+
+    #[test]
+    fn lower_bound_flag() {
+        assert_eq!(
+            compare_with_flags("1.0alpha1", "1.0", 0, VERSIONFLAG_LOWER_BOUND),
+            Ordering::Greater,
+        );
+        assert_eq!(
+            compare_with_flags("0.999", "1.0", 0, VERSIONFLAG_LOWER_BOUND),
+            Ordering::Less,
+        );
+    }
+
+    #[test]
+    fn upper_bound_flag() {
+        assert_eq!(
+            compare_with_flags("1.0.1", "1.0", 0, VERSIONFLAG_UPPER_BOUND),
+            Ordering::Less,
+        );
+        assert_eq!(
+            compare_with_flags("1.1", "1.0", 0, VERSIONFLAG_UPPER_BOUND),
+            Ordering::Greater,
+        );
+    }
+
+    #[test]
+    #[should_panic(expected = "v1 contains interior null byte")]
+    fn compare_rejects_interior_null() {
+        let _ = compare("1.0\0rc1", "1.0");
+    }
+
+    #[test]
+    #[should_panic(expected = "v2 contains interior null byte")]
+    fn compare_with_flags_rejects_interior_null() {
+        let _ = compare_with_flags("1.0", "1.0\0rc1", 0, 0);
+    }
+
+    #[test]
+    fn version_metadata() {
+        let parts = version_string()
+            .split('.')
+            .map(|part| part.parse::<u32>().unwrap())
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            parts,
+            vec![
+                LIBVERSION_VERSION_MAJOR,
+                LIBVERSION_VERSION_MINOR,
+                LIBVERSION_VERSION_PATCH,
+            ]
+        );
+        assert!(version_atleast(
+            LIBVERSION_VERSION_MAJOR,
+            LIBVERSION_VERSION_MINOR,
+            LIBVERSION_VERSION_PATCH,
+        ));
+        assert!(!version_string().is_empty());
+    }
+
     #[test]
     fn ffi_direct() {
         let v1 = CString::new("1.0").unwrap();
         let v2 = CString::new("2.0").unwrap();
         let result = unsafe { ffi::version_compare2(v1.as_ptr(), v2.as_ptr()) };
         assert_eq!(result, -1);
     }
+
+    #[test]
+    fn ffi_compare4_direct() {
+        let v1 = CString::new("1.0p1").unwrap();
+        let v2 = CString::new("1.0").unwrap();
+        let result = unsafe {
+            ffi::version_compare4(v1.as_ptr(), v2.as_ptr(), VERSIONFLAG_P_IS_PATCH as i32, 0)
+        };
+        assert_eq!(result, 1);
+    }
 }