Skip to main content

dftd3_sys/
lib.rs

1//! Build-script-only support crate for the DFT-D3 dispersion correction.
2//!
3//! This crate contains no Rust API. Its `build.rs` provides the native
4//! `s-dftd3` (and its `mctc-lib` dependency) as **static** archives and
5//! emits the corresponding `cargo:rustc-link-lib` directives, so anything
6//! depending on this crate links `libs-dftd3.a` + `libmctc-lib.a` directly
7//! into the final binary — there is never a stray `libs-dftd3.so` to ship
8//! or find at runtime.
9//!
10//! The Rust FFI bindings and the safe wrapper API come from the [`dftd3`]
11//! crate (crates.io, RESTGroup/dftd3-rs), wired up without its
12//! `dynamic_loading` feature (which would `dlopen` a shared library at
13//! runtime). `fastatomstruct-simulation`'s `dftd3` cargo feature pulls in
14//! both crates.
15//!
16//! [`dftd3`]: https://crates.io/crates/dftd3
17
18/// The simple-dftd3 release this crate links. Referenced from
19/// `fastatomstruct-simulation` (or any downstream user) so the crate is
20/// part of every final link graph — rustc prunes unreferenced crates, and
21/// with them the static-archive link flags emitted by this crate's build
22/// script.
23///
24/// Derived from the `SDFTD3_TAG` pin in `build.rs` via
25/// `cargo:rustc-env=SDFTD3_VERSION`, so it can never drift from the
26/// library that was actually built (finding F0459).
27pub const SDFTD3_VERSION: &str = env!("SDFTD3_VERSION");
28
29#[cfg(test)]
30mod tests {
31    use super::SDFTD3_VERSION;
32
33    /// Pinned simple-dftd3 version read from the `SDFTD3_TAG` const in
34    /// `build.rs` (same `include_str!` parse the integration tests use,
35    /// e.g. `tests/dftd3_dir_validation.rs`), without the leading `v`.
36    fn pinned_version() -> &'static str {
37        let version = include_str!("../build.rs")
38            .split("const SDFTD3_TAG: &str = \"v")
39            .nth(1)
40            .expect("build.rs must define SDFTD3_TAG as a v-prefixed string literal");
41        let version = version
42            .split('"')
43            .next()
44            .expect("SDFTD3_TAG literal must be terminated by a quote");
45        assert!(!version.is_empty(), "SDFTD3_TAG must not be empty");
46        version
47    }
48
49    /// The `X.Y.Z` contract of `SDFTD3_VERSION`: exactly three
50    /// dot-separated components, each non-empty and made only of ASCII
51    /// digits (the `v`-prefixed tag minus its leading `v`).
52    fn is_plain_semver(version: &str) -> bool {
53        let mut parts = version.split('.');
54        let is_component = |part: Option<&str>| {
55            part.is_some_and(|p| !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit()))
56        };
57        is_component(parts.next())
58            && is_component(parts.next())
59            && is_component(parts.next())
60            && parts.next().is_none()
61    }
62
63    #[test]
64    fn pinned_version_is_plain_semver() {
65        // Guards the build.rs `cargo:rustc-env` plumbing: the value must be
66        // the tag minus its leading `v`, e.g. "1.4.0". The tie to the pin
67        // itself is checked by `reported_version_matches_the_pinned_tag`.
68        assert!(
69            is_plain_semver(SDFTD3_VERSION),
70            "SDFTD3_VERSION = {SDFTD3_VERSION:?} must be `X.Y.Z` (three non-empty \
71             numeric components) derived from the v-prefixed tag"
72        );
73    }
74
75    #[test]
76    fn semver_check_rejects_malformed_and_non_numeric_versions() {
77        // Regression test (nightly review 2026-10-27): the assertion used
78        // to check only the *first* component for ASCII digits and the
79        // remaining two for mere existence (`is_some()`), so every value
80        // below passed `pinned_version_is_plain_semver` although none of
81        // them is the promised `X.Y.Z` — e.g. an RC pin such as
82        // `v1.4.0-rc1` would have yielded "1.4.0-rc1" unnoticed.
83        const INVALID: &[&str] = &[
84            "",             // nothing at all
85            "1",            // single component
86            "1.4",          // two components
87            "1.4.0.5",      // four components
88            "1..0",         // empty second component
89            "1..",          // empty second and third components
90            ".4.0",         // empty first component
91            "1.beta.gamma", // non-numeric second and third components
92            "v1.4.0",       // leading `v` not stripped from the tag
93            "1.4.0-rc",     // release-candidate pin ("v1.4.0-rc")
94            "1.4.0rc",      // unseparated pre-release suffix
95            "1.4.0 ",       // trailing whitespace
96        ];
97        for version in INVALID {
98            assert!(
99                !is_plain_semver(version),
100                "{version:?} is not `X.Y.Z` and must be rejected"
101            );
102        }
103        for version in ["0.0.0", "0.5.1", "1.4.0", "10.20.30"] {
104            assert!(
105                is_plain_semver(version),
106                "{version:?} is `X.Y.Z` and must be accepted"
107            );
108        }
109    }
110
111    #[test]
112    fn reported_version_matches_the_pinned_tag() {
113        // Ties the *value* of the constant to the raw `SDFTD3_TAG` pin,
114        // mirroring what build.rs derives (`tag.trim_start_matches('v')`).
115        // Without this, the shape-only check above accepts any X.Y.Z, so
116        // replacing the tag-derived `cargo:rustc-env` emission with a
117        // hand-duplicated literal — the F0459 regression class the
118        // plumbing exists to prevent — would keep the suite green while
119        // the constant reports a version that was never built (nightly
120        // review 2026-10-27).
121        assert_eq!(
122            SDFTD3_VERSION,
123            pinned_version(),
124            "SDFTD3_VERSION must stay derived from the SDFTD3_TAG pin in build.rs"
125        );
126    }
127}