dftd3-sys 0.1.2

Pinned static build of the simple-dftd3 (s-dftd3) Fortran library for the `dftd3` bindings
Documentation
//! Build-script-only support crate for the DFT-D3 dispersion correction.
//!
//! This crate contains no Rust API. Its `build.rs` provides the native
//! `s-dftd3` (and its `mctc-lib` dependency) as **static** archives and
//! emits the corresponding `cargo:rustc-link-lib` directives, so anything
//! depending on this crate links `libs-dftd3.a` + `libmctc-lib.a` directly
//! into the final binary — there is never a stray `libs-dftd3.so` to ship
//! or find at runtime.
//!
//! The Rust FFI bindings and the safe wrapper API come from the [`dftd3`]
//! crate (crates.io, RESTGroup/dftd3-rs), wired up without its
//! `dynamic_loading` feature (which would `dlopen` a shared library at
//! runtime). `fastatomstruct-simulation`'s `dftd3` cargo feature pulls in
//! both crates.
//!
//! [`dftd3`]: https://crates.io/crates/dftd3

/// The simple-dftd3 release this crate links. Referenced from
/// `fastatomstruct-simulation` (or any downstream user) so the crate is
/// part of every final link graph — rustc prunes unreferenced crates, and
/// with them the static-archive link flags emitted by this crate's build
/// script.
///
/// Derived from the `SDFTD3_TAG` pin in `build.rs` via
/// `cargo:rustc-env=SDFTD3_VERSION`, so it can never drift from the
/// library that was actually built (finding F0459).
pub const SDFTD3_VERSION: &str = env!("SDFTD3_VERSION");

#[cfg(test)]
mod tests {
    use super::SDFTD3_VERSION;

    /// Pinned simple-dftd3 version read from the `SDFTD3_TAG` const in
    /// `build.rs` (same `include_str!` parse the integration tests use,
    /// e.g. `tests/dftd3_dir_validation.rs`), without the leading `v`.
    fn pinned_version() -> &'static str {
        let version = include_str!("../build.rs")
            .split("const SDFTD3_TAG: &str = \"v")
            .nth(1)
            .expect("build.rs must define SDFTD3_TAG as a v-prefixed string literal");
        let version = version
            .split('"')
            .next()
            .expect("SDFTD3_TAG literal must be terminated by a quote");
        assert!(!version.is_empty(), "SDFTD3_TAG must not be empty");
        version
    }

    /// The `X.Y.Z` contract of `SDFTD3_VERSION`: exactly three
    /// dot-separated components, each non-empty and made only of ASCII
    /// digits (the `v`-prefixed tag minus its leading `v`).
    fn is_plain_semver(version: &str) -> bool {
        let mut parts = version.split('.');
        let is_component = |part: Option<&str>| {
            part.is_some_and(|p| !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit()))
        };
        is_component(parts.next())
            && is_component(parts.next())
            && is_component(parts.next())
            && parts.next().is_none()
    }

    #[test]
    fn pinned_version_is_plain_semver() {
        // Guards the build.rs `cargo:rustc-env` plumbing: the value must be
        // the tag minus its leading `v`, e.g. "1.4.0". The tie to the pin
        // itself is checked by `reported_version_matches_the_pinned_tag`.
        assert!(
            is_plain_semver(SDFTD3_VERSION),
            "SDFTD3_VERSION = {SDFTD3_VERSION:?} must be `X.Y.Z` (three non-empty \
             numeric components) derived from the v-prefixed tag"
        );
    }

    #[test]
    fn semver_check_rejects_malformed_and_non_numeric_versions() {
        // Regression test (nightly review 2026-10-27): the assertion used
        // to check only the *first* component for ASCII digits and the
        // remaining two for mere existence (`is_some()`), so every value
        // below passed `pinned_version_is_plain_semver` although none of
        // them is the promised `X.Y.Z` — e.g. an RC pin such as
        // `v1.4.0-rc1` would have yielded "1.4.0-rc1" unnoticed.
        const INVALID: &[&str] = &[
            "",             // nothing at all
            "1",            // single component
            "1.4",          // two components
            "1.4.0.5",      // four components
            "1..0",         // empty second component
            "1..",          // empty second and third components
            ".4.0",         // empty first component
            "1.beta.gamma", // non-numeric second and third components
            "v1.4.0",       // leading `v` not stripped from the tag
            "1.4.0-rc",     // release-candidate pin ("v1.4.0-rc")
            "1.4.0rc",      // unseparated pre-release suffix
            "1.4.0 ",       // trailing whitespace
        ];
        for version in INVALID {
            assert!(
                !is_plain_semver(version),
                "{version:?} is not `X.Y.Z` and must be rejected"
            );
        }
        for version in ["0.0.0", "0.5.1", "1.4.0", "10.20.30"] {
            assert!(
                is_plain_semver(version),
                "{version:?} is `X.Y.Z` and must be accepted"
            );
        }
    }

    #[test]
    fn reported_version_matches_the_pinned_tag() {
        // Ties the *value* of the constant to the raw `SDFTD3_TAG` pin,
        // mirroring what build.rs derives (`tag.trim_start_matches('v')`).
        // Without this, the shape-only check above accepts any X.Y.Z, so
        // replacing the tag-derived `cargo:rustc-env` emission with a
        // hand-duplicated literal — the F0459 regression class the
        // plumbing exists to prevent — would keep the suite green while
        // the constant reports a version that was never built (nightly
        // review 2026-10-27).
        assert_eq!(
            SDFTD3_VERSION,
            pinned_version(),
            "SDFTD3_VERSION must stay derived from the SDFTD3_TAG pin in build.rs"
        );
    }
}