dftd3-sys 0.1.2

Pinned static build of the simple-dftd3 (s-dftd3) Fortran library for the `dftd3` bindings
Documentation
# Usage

## Depending on `dftd3-sys`

```toml
# Cargo.toml of the consumer
[dependencies]
dftd3-sys = { version = "0.1", optional = true }
dftd3 = { version = "0", default-features = false, features = ["api-v1_4"], optional = true }

[features]
dftd3 = ["dep:dftd3", "dep:dftd3-sys"]
```

The Rust FFI bindings and the safe wrapper API come from the
[`dftd3`](https://crates.io/crates/dftd3) crate (RESTGroup/dftd3-rs), used
**without** its `dynamic_loading` feature (which would `dlopen` a shared
library at runtime and defeat the static contract).

`dftd3` gates its FFI declarations behind cumulative `api-vX_Y` cargo
features, and `default-features = false` drops the default `api-v0_5`
together with `dynamic_loading` — so the dependency line must enable at
least one `api-v*` feature explicitly or the `dftd3` crate itself fails
to compile. `api-v1_4` matches the simple-dftd3 v1.4.0 pin this crate
builds and links.

**Mandatory:** reference the crate from the final link graph, e.g.

```rust
// without this the static-archive link flags from dftd3-sys's build
// script are pruned along with the unreferenced crate
const _: &str = dftd3_sys::SDFTD3_VERSION;
```

## Building

- Default: the build script extracts the pinned s-dftd3 / mctc-lib tarballs
  shipped under `vendor/` (SHA-256 verified) into `OUT_DIR` and builds them
  with meson/ninja/gfortran. No network access is required.
- Maintainer override: set `DFTD3_SYS_UPSTREAM_DIR=/path/to/simple-dftd3` to
  build from a pre-extracted source tree. The version must match the pin. The
  tree itself is never written to — the build uses a copy under `OUT_DIR`, so
  a (re-)build can never leave your checkout dirty. If the tree has no
  `subprojects/mctc-lib`, the build script extracts the pinned,
  SHA-256-verified mctc-lib from `vendor/` into that copy; an already present
  `subprojects/mctc-lib` is kept as-is, with pin drift reported as a build
  warning. *Directory* symlinks inside the tree (a `self -> .` link, a link
  pointing somewhere else) are never walked into: the build skips them and
  names them in a build warning, because a link that contains itself makes
  the walk never terminate and a link pointing out of the tree would drag
  unrelated directories into the build copy. Symlinks that point at a regular
  file are copied with that file's content.
- Prebuilt static archives: point `DFTD3_DIR` at a prefix containing *static*
  `libs-dftd3.a` + `libmctc-lib.a`. A shared-only install is rejected. The
  build script validates the prefix: `libs-dftd3.a` must actually provide the
  s-dftd3 C API (checked with `nm`), and an installed `s-dftd3.pc` must match
  the pinned version; a prefix without a `.pc` still builds, with a warning.
  Prefix archives that still define raw `__mctc_*` Fortran module symbols
  (the shape of any meson install) are renamed to `__fasd3mctc_*` under
  `OUT_DIR` — like the vendored build — and only the renamed copies are
  linked; a prefix whose `libs-dftd3.a` references raw `__mctc_*` symbols
  that nothing in it defines is rejected.
- `OBJCOPY=/path/to/objcopy` selects the symbol-renaming tool
  (otherwise `objcopy`, then `llvm-objcopy` are probed).

## Migration notes for fastatomstruct (dftd3-build → dftd3-sys)

fastatomstruct `origin/master` references the crate in three places:
the workspace `members` list,
`crates/fastatomstruct-simulation/Cargo.toml` (`dep:dftd3-build` feature +
path dependency), and one code reference,
`crates/fastatomstruct-simulation/src/corrections/dftd3.rs`:
`const _: &str = dftd3_build::SDFTD3_VERSION;`.

**Option A — dependency alias (zero code churn):**

```toml
dftd3-build = { package = "dftd3-sys", version = "0.1", optional = true }
```

`dftd3_build::SDFTD3_VERSION` and the `dep:dftd3-build` feature keep
working unchanged. Useful only as a temporary bridge while branches are in
flight.

**Option B — rename references (recommended):**

```toml
dftd3-sys = { version = "0.1", optional = true }
# feature: dftd3 = ["dep:dftd3", "dep:dftd3-sys"]
```

```rust
const _: &str = dftd3_sys::SDFTD3_VERSION;
```

**Recommendation: Option B.** The rename is mechanical (one dependency
line, one feature string, one `const _` in `corrections/dftd3.rs`, one
workspace `members` path), and Option A permanently hides the real crate
name behind an alias that no longer matches the upstream repo — every
future reader would have to resolve the indirection. Keep Option A only if
out-of-tree branches must build against both names simultaneously.