# mldsa-native-rs
**This crate is EXPERIMENTAL. Use at your own peril. (i.e., DON'T!)**
FFI bindings and an optional Rust wrapper for the
[`mldsa-native`][repo:mldsa-native] library.
## Repository
The git repository for this project uses git submodules.
When cloning, we recommend to use:
```sh
git clone --recursive
```
Alternatively, you might need to run
```sh
git submodule update --init --recursive
```
to ensure submodules are fetched and updated before being able to build
from source.
## Features flags
- `wrapper`: include a `wrapper` module that provides Rust types, traits, and
wrapper functions around the FFI items.
- `rand`: include keygen and signing functions in the wrapper that generate
their own random data using the `rand` crate.
- `extern-C-randombytes`: (*disabled by default*) if enabled exports a
default implementation of the `randombytes` function required by the
backend implementation.
- `native` *(opt-in)*: builds the optimized backend from
[`mldsa-native`][repo:mldsa-native] instead of its portable
implementation.
When enabled, this crate's `build.rs` autodetects the target's
capabilities and passes a corresponding set of defines to
`mldsa-native`, which is compiled as part of the build.
What those defines compile to on a given target is determined by
`mldsa-native`, not by this crate. For many targets this produces an
optimized build; for some, the detected define combination may fall
back to the portable implementation or fail to compile.
This crate makes no guarantees beyond those of `mldsa-native`.
If the build fails, disable this feature to use the portable
implementation.
- `built_info`: (*opt-in*) include a `built_info` module exposing build-time
metadata via the [`built`][crate:built] crate.
Provides a `BuiltInfo` struct with the package name and version, target/host
triples, build profile, `rustc` version, enabled features, and git metadata
(commit hash, HEAD ref, and dirty state) when built from a git repository.
When the `native` feature is also enabled, `BuiltInfo` additionally reports
the detected runtime CPU capabilities.
[repo:mldsa-native]: https://github.com/pq-code-package/mldsa-native