Mercurial > crates > nonstick
changeset 184:42f747774d94
Really get documentation stuff squared away.
Expand READMEs and polish off module documentation.
| author | Paul Fisher <paul@pfish.zone> |
|---|---|
| date | Thu, 31 Jul 2025 14:36:50 -0400 |
| parents | 4f46681b3f54 |
| children | fb8b547b36b7 |
| files | Cargo.lock Cargo.toml README.md src/lib.rs testharness/Cargo.toml testharness/src/bin/testharness.rs testharness/src/lib.rs |
| diffstat | 7 files changed, 74 insertions(+), 185 deletions(-) [+] |
line wrap: on
line diff
--- a/Cargo.lock Wed Jul 30 18:43:07 2025 -0400 +++ b/Cargo.lock Thu Jul 31 14:36:50 2025 -0400 @@ -3,36 +3,12 @@ version = 3 [[package]] -name = "anyhow" -version = "1.0.98" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e16d2d3311acee920a9eb8d33b8cbc1787ce4a264e85f964c2404b969bdcd487" - -[[package]] name = "bitflags" version = "2.9.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1b8e56985ec62d17e9c1001dc89c88ecd7dc08e47eba5ec7c29c7b5eeecde967" [[package]] -name = "cargo_metadata" -version = "0.9.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "46e3374c604fb39d1a2f35ed5e4a4e30e60d01fab49446e08f1b3e9a90aef202" -dependencies = [ - "semver", - "serde", - "serde_derive", - "serde_json", -] - -[[package]] -name = "itoa" -version = "1.0.15" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c" - -[[package]] name = "libc" version = "0.2.174" source = "registry+https://github.com/rust-lang/crates.io-index" @@ -62,12 +38,6 @@ ] [[package]] -name = "memchr" -version = "2.7.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "32a282da65faaf38286cf3be983213fcf1d2e2a58700e808f83f4ea9a4804bc0" - -[[package]] name = "nonstick" version = "0.0.8-alpha0" dependencies = [ @@ -82,139 +52,6 @@ name = "nonstick-testharness" version = "0.0.8-alpha0" dependencies = [ - "anyhow", "libpam-sys-impls", "nonstick", - "test-cdylib", - "thiserror", ] - -[[package]] -name = "proc-macro2" -version = "1.0.95" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "02b3e5e68a3a1a02aad3ec490a98007cbc13c37cbe84a3cd7b8e406d76e7f778" -dependencies = [ - "unicode-ident", -] - -[[package]] -name = "quote" -version = "1.0.40" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1885c039570dc00dcb4ff087a89e185fd56bae234ddc7f056a945bf36467248d" -dependencies = [ - "proc-macro2", -] - -[[package]] -name = "ryu" -version = "1.0.20" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "28d3b2b1366ec20994f1fd18c3c594f05c5dd4bc44d8bb0c1c632c8d6829481f" - -[[package]] -name = "semver" -version = "0.9.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1d7eb9ef2c18661902cc47e535f9bc51b78acd254da71d375c2f6720d9a40403" -dependencies = [ - "semver-parser", - "serde", -] - -[[package]] -name = "semver-parser" -version = "0.7.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "388a1df253eca08550bef6c72392cfe7c30914bf41df5269b68cbd6ff8f570a3" - -[[package]] -name = "serde" -version = "1.0.219" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5f0e2c6ed6606019b4e29e69dbaba95b11854410e5347d525002456dbbb786b6" -dependencies = [ - "serde_derive", -] - -[[package]] -name = "serde_derive" -version = "1.0.219" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5b0276cf7f2c73365f7157c8123c21cd9a50fbbd844757af28ca1f5925fc2a00" -dependencies = [ - "proc-macro2", - "quote", - "syn", -] - -[[package]] -name = "serde_json" -version = "1.0.140" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "20068b6e96dc6c9bd23e01df8827e6c7e1f2fddd43c21810382803c136b99373" -dependencies = [ - "itoa", - "memchr", - "ryu", - "serde", -] - -[[package]] -name = "syn" -version = "2.0.104" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "17b6f705963418cdb9927482fa304bc562ece2fdd4f616084c50b7023b435a40" -dependencies = [ - "proc-macro2", - "quote", - "unicode-ident", -] - -[[package]] -name = "test-cdylib" -version = "1.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c8f41b1f729f5ff5177beab62e5a9251e318df8386e260ab3c944cff502ee78d" -dependencies = [ - "cargo_metadata", - "serde", - "serde_json", - "toml", -] - -[[package]] -name = "thiserror" -version = "2.0.12" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "567b8a2dae586314f7be2a752ec7474332959c6460e02bde30d702a66d488708" -dependencies = [ - "thiserror-impl", -] - -[[package]] -name = "thiserror-impl" -version = "2.0.12" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7f7cf42b4507d8ea322120659672cf1b9dbb93f8f2d4ecfd6e51350ff5b17a1d" -dependencies = [ - "proc-macro2", - "quote", - "syn", -] - -[[package]] -name = "toml" -version = "0.5.11" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f4f7f0dd8d50a853a531c426359045b1998f04219d88799810762cd4ad314234" -dependencies = [ - "serde", -] - -[[package]] -name = "unicode-ident" -version = "1.0.18" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5a5f39404a5da50712a4c1eecf25e90dd62b613502b7e925fd4e4d19b5c96512"
--- a/Cargo.toml Wed Jul 30 18:43:07 2025 -0400 +++ b/Cargo.toml Thu Jul 31 14:36:50 2025 -0400 @@ -20,6 +20,16 @@ edition.workspace = true rust-version.workspace = true +[package.metadata.docs.rs] +default-target = "x86_64-unknown-linux-gnu" + +targets = [ + "x86_64-apple-darwin", + "x86_64-unknown-freebsd", + "x86_64-unknown-illumos", +] + + [features] default = ["link"] @@ -39,9 +49,6 @@ # Extensions to PAM that are supported by Sun's PAM. sun-ext = [] -# This feature exists only for testing. -test-install = [] - [dependencies] bitflags = "2.9.0" libc = { optional = true, version = "0.2" }
--- a/README.md Wed Jul 30 18:43:07 2025 -0400 +++ b/README.md Thu Jul 31 14:36:50 2025 -0400 @@ -1,7 +1,7 @@ # 🍳 nonstick -Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust safely. -Don't worry about getting stuck on unsafe code. +Nonstick lets you use PAM (Pluggable Authentication Modules) from Rust. +Never worry about getting stuck on unsafe code. You can use nonstick for interacting with PAM from both sides: @@ -16,6 +16,15 @@ Further documentation can be found in the crate's rustdoc. +## Why use nonstick? + +- Safe, idiomatic Rust API. +- Supports both modules and client applications. +- Works with all PAM implementations. +- Does not require system headers. +- Few dependencies, fast builds (no `syn`!). +- Well-tested on multiple platforms (AMD64 Linux, FreeBSD, and Illumos). + ## Status - **Modules**: full support for all calls by PAM into modules.
--- a/src/lib.rs Wed Jul 30 18:43:07 2025 -0400 +++ b/src/lib.rs Thu Jul 31 14:36:50 2025 -0400 @@ -139,8 +139,46 @@ //! environment variable at build time. See the [`libpam_sys`] documentation. #![doc = concat!("This documentation was built for **", pam_impl_name!(), "**.")] //! +//! # Cargo features +//! +//! This crate provides the following Cargo features: +//! +//! - **link** (enabled by default): Actually link against PAM, +//! rather than just providing an abstract PAM interface. +//! Enabling this will fail if extensions incompatible with the +//! PAM implementation you're linking against are also enabled. +//! - Extensions beyond the PAM specification provided by various PAM +//! implementations: +//! - **basic-ext**: Enable extensions provided by both Linux-PAM and OpenPAM. +//! This is limited to a few return enums. +//! - **linux-pam-ext** (includes basic-ext): Enable extensions provided by +//! Linux-PAM. This includes enum values and the ability to send +//! binary messages between the PAM module and the application. +//! - **openpam-ext** (includes basic-ext): Enable extensions provided by +//! OpenPAM. This includes enum values. +//! - **sun-ext**: Enable extensions provided by Sun PAM. +//! This includes enum values. +//! +//! # Design +//! +//! This library consists of two parts: +//! +//! - The generic PAM interface, a set of traits describing the behavior of PAM +//! and the API we export. It is independent of the PAM library itself and +//! could be implemented by any crate to provide PAM-like services. +//! This is primarily intended to allow a developer to test their PAM modules +//! and applications by writing mock implementations to verify their +//! application (or module) code's interactions with PAM itself. +//! +//! - The bindings to LibPAM itself. This part is included only when **link** +//! is enabled. These live in the `libpam` submodule (with a few exceptions +//! for constant-related code). +//! //! # References //! +//! These documents were used when authoring this library and will probably be +//! of value if you want to implement a PAM module or a PAM application. +//! //! - The Linux-PAM guides provide information for a variety of audiences. //! While some of it is specific to Linux-PAM, much of it applies to other //! PAM implementations: @@ -156,15 +194,16 @@ //! - [OpenPAM admin documentation][bsdpam8] //! - [Illumos pam.conf documentation][sunpam5] //! - [The original PAM specification][spec] (mostly of historical interest) +//! - [Cooking spray](https://en.wikipedia.org/wiki/Cooking_spray) #![doc = ""] -#![doc = crate::_doc::man7!(man7pam8: 8 pam)] -#![doc = crate::_doc::manbsd!(bsdpam8: 8 pam)] -#![doc = crate::_doc::mansun!(sunpam5: 5 "pam.conf")] -#![doc = crate::_doc::stdlinks!(3 pam)] -#![doc = crate::_doc::guide!(adg: "Linux-PAM_ADG.html")] -#![doc = crate::_doc::guide!(mwg: "Linux-PAM_MWG.html")] -#![doc = crate::_doc::guide!(sag: "Linux-PAM_SAG.html")] -#![doc = crate::_doc::xsso!(spec: "toc.htm")] +#![doc = _doc::man7!(man7pam8: 8 pam)] +#![doc = _doc::manbsd!(bsdpam8: 8 pam)] +#![doc = _doc::mansun!(sunpam5: 5 "pam.conf")] +#![doc = _doc::stdlinks!(3 pam)] +#![doc = _doc::guide!(adg: "Linux-PAM_ADG.html")] +#![doc = _doc::guide!(mwg: "Linux-PAM_MWG.html")] +#![doc = _doc::guide!(sag: "Linux-PAM_SAG.html")] +#![doc = _doc::xsso!(spec: "toc.htm")] #[cfg(feature = "link")] mod _compat_checker {
--- a/testharness/Cargo.toml Wed Jul 30 18:43:07 2025 -0400 +++ b/testharness/Cargo.toml Thu Jul 31 14:36:50 2025 -0400 @@ -1,6 +1,6 @@ [package] name = "nonstick-testharness" -description = "Automatic test harness for the Nonstick PAM library." +description = "End-to-end testing for the Nonstick PAM library." publish = false license.workspace = true version.workspace = true @@ -16,15 +16,9 @@ linux-pam-ext = ["nonstick/linux-pam-ext"] openpam-ext = ["nonstick/openpam-ext"] sun-ext = ["nonstick/sun-ext"] -test-install = [] [dependencies] nonstick = { path = "..", features = ["link"], default-features = false } [build-dependencies] libpam-sys-impls = { path = "../libpam-sys/libpam-sys-impls" } - -[dev-dependencies] -anyhow = "1.0.98" -test-cdylib = "1.1.0" -thiserror = "2.0.12"
--- a/testharness/src/bin/testharness.rs Wed Jul 30 18:43:07 2025 -0400 +++ b/testharness/src/bin/testharness.rs Thu Jul 31 14:36:50 2025 -0400 @@ -1,4 +1,5 @@ -//! The actual program which runs the tests. +//! Test program to interact with PAM and `../lib.rs` to ensure that nonstick +//! does everything right. use nonstick::conv::Exchange; use nonstick::items::Items;
--- a/testharness/src/lib.rs Wed Jul 30 18:43:07 2025 -0400 +++ b/testharness/src/lib.rs Thu Jul 31 14:36:50 2025 -0400 @@ -1,4 +1,6 @@ -//! The nonstick library +//! Test module for nonstick. This works with the `testharness` binary +//! to test the end-to-end behavior of nonstick (i.e., that it plumbs everything +//! from the application through PAM to the module properly). use crate::nonstick::items::ItemsMut; use crate::nonstick::EnvironMapMut;