# dftd3-sys
Pinned, fully **static** build of the
[simple-dftd3](https://github.com/dftd3/simple-dftd3) (s-dftd3) Fortran
dispersion-correction library and its
[mctc-lib](https://github.com/grimme-lab/mctc-lib) dependency, for use with
the [`dftd3`](https://crates.io/crates/dftd3) Rust bindings
(without their `dynamic_loading` feature).
Extracted from the [fastatomstruct](https://gitlab.git.nrw/uni-ms/ag-salinga/fastatomstruct)
workspace as `crates/dftd3-build` at `4c6ec0fc`; renamed to `dftd3-sys`.
## What this crate is
A build-script-only support crate. It has **no Rust API** beyond one
constant, `SDFTD3_VERSION` (derived from the build pin, so it always
matches the library that was actually linked). Its `build.rs`:
1. extracts the pinned s-dftd3 and mctc-lib release tarballs shipped under
`vendor/` (SHA-256 verified) unless `DFTD3_DIR` or a maintainer-owned
`DFTD3_SYS_UPSTREAM_DIR` is used,
2. builds both as **static archives** with meson/ninja
(`--wrap-mode=nodownload`, OpenMP off — no new dynamic dependencies),
3. renames all `__mctc_*` symbols of *this* mctc-lib copy to a private
`__fasd3mctc_*` namespace, because `dftd4-sys` embeds its own,
incompatible mctc-lib build: without the rename, mixing the two
Fortran module vtable/copy/finalise thunks in one binary causes
reproducible SIGSEGVs,
4. emits `cargo:rustc-link-lib=static=...` flags plus the gfortran runtime.
The contract: everything ends up inside the final binary — there is never a
stray `libs-dftd3.so` to ship or find at runtime.
## Requirements
| `meson`, `ninja` | building the Fortran sources | |
| `gfortran` | compiling s-dftd3/mctc-lib; runtime linked as `libgfortran` | |
| `ar`, `nm`, `objcopy` | static-archive symbol namespacing (vendored build and `DFTD3_DIR` prefixes); `nm` also validates `DFTD3_DIR` archives | GNU binutils; `llvm-objcopy` is probed and works; `OBJCOPY=...` overrides |
| `tar`, `sha256sum`/`shasum` | unpacking and pin verification | `shasum -a 256` fallback for macOS/BSD |
| vendored tarballs | providing pinned upstream sources offline | `vendor/simple-dftd3-v1.4.0.tar.gz` and `vendor/mctc-lib-v0.5.1.tar.gz` are packaged with this crate |
Linux is the supported and CI-tested platform. See
[`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the platform policy.
## Offline / override builds
- **Default vendored build:** the package includes the pinned tarballs under
`vendor/`; the build script verifies SHA-256 and extracts them under
`OUT_DIR`. This is the crates.io-safe default and runs fully offline.
- **Maintainer source tree:** set `DFTD3_SYS_UPSTREAM_DIR=/path/to/simple-dftd3`
to build from a hand-extracted tree. The version is validated against the
pin. The tree is read-only input: the build happens in a copy under
`OUT_DIR`, which also gets the `app`/`test` patch. Upstream release tarballs
ship only mctc-lib's *wrap file*, so when the tree has no
`subprojects/mctc-lib`, the build script extracts the pinned,
SHA-256-verified mctc-lib from `vendor/` into that copy; a
maintainer-provided `subprojects/mctc-lib` is used as-is, with
drift from the mctc-lib pin reported as a build warning. Directory symlinks
inside the tree are never walked into (a `self -> .` link would make the
walk never terminate); they are skipped with a build warning, while symlinks
to regular files are mirrored with the target's content.
- **System prefix:** `DFTD3_DIR=/prefix` with *static* `libs-dftd3.a` and
`libmctc-lib.a` (or `libmctc.a`) under `lib`/`lib64`. Shared-only
installs are rejected on purpose — static linking is the contract. The
archives are content-checked: `libs-dftd3.a` must define the s-dftd3 C
API and a meson-installed `s-dftd3.pc` must match the pin (prefixes
without a `.pc` build with a warning). Thin archives copied away from
their build tree are rejected — rebuild them self-contained. Prefixes
carrying raw `__mctc_*` Fortran module symbols — which any meson install
does by construction — are namespaced like the vendored build: the
archives are copied into `OUT_DIR`, renamed to `__fasd3mctc_*`, and only
those copies are linked, so a `DFTD3_DIR` build can never mix its mctc-lib
with `dftd4-sys`'s copy.
## Usage
```toml
[dependencies]
dftd3-sys = "0.1"
dftd3 = { version = "0", default-features = false, features = ["api-v1_4"] }
```
The `dftd3` crate gates its own FFI declarations behind cumulative
`api-vX_Y` cargo features, and `default-features = false` — mandatory
here, because the default `dynamic_loading` feature would `dlopen` a
shared library and defeat the static contract — drops the default
`api-v0_5` along with it. At least one `api-v*` feature must therefore
be listed explicitly; pick the one matching the simple-dftd3 release
this crate builds, currently `api-v1_4` for the v1.4.0 pin.
Reference `dftd3_sys::SDFTD3_VERSION` somewhere in your final crate so the
link flags are not pruned (rustc drops unreferenced crates). See
[`USAGE.md`](USAGE.md) — including the fastatomstruct migration notes.
## License
LGPL-3.0-or-later (this crate). The linked upstream libraries are under
their own licenses: simple-dftd3 is LGPL-3.0-or-later and mctc-lib is
Apache-2.0. Their license texts travel inside the vendored release tarballs.