Mercurial > crates > nonstick

changeset 129:5b2de52dd8b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cleanups: create readmes, add a few docs, remove cruft.
author Paul Fisher <paul@pfish.zone>
date Mon, 30 Jun 2025 23:49:54 -0400
parents ad77f2af5ff4
children 80c07e5ab22f
files Cargo.lock libpam-sys/README.md libpam-sys/libpam-sys-impls/Cargo.toml libpam-sys/libpam-sys-impls/README.md libpam-sys/libpam-sys-impls/src/lib.rs libpam-sys/libpam-sys-test/Cargo.toml libpam-sys/libpam-sys-test/README.md libpam-sys/src/ffi.rs
diffstat 8 files changed, 46 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/Cargo.lock	Mon Jun 30 23:00:53 2025 -0400
+++ b/Cargo.lock	Mon Jun 30 23:49:54 2025 -0400
@@ -307,7 +307,6 @@
 name = "libpam-sys-impls"
 version = "0.0.1"
 dependencies = [
- "bindgen",
  "dlopen",
  "proc-macro2 1.0.95",
  "quote 1.0.40",
--- a/libpam-sys/README.md	Mon Jun 30 23:00:53 2025 -0400
+++ b/libpam-sys/README.md	Mon Jun 30 23:49:54 2025 -0400
@@ -1,6 +1,9 @@
-# libpam-sys
+# `libpam-sys`: low-level bindings to Pluggable Authentication Modules
 
-This crate provides low-level access to PAM.
+This crate provides low-level access to PAM, working with multiple PAM implementations.
+You do not need PAM system headers installed to use this!
+
+If you're looking for a nice, safe, Rusty API to PAM, may I recommend [nonstick][nonstick]?
 
 ## Configuration
 
@@ -14,7 +17,7 @@
 Each implementation exports all the functionality available in its respective PAM library.
 `XSso` exports only what is in the [X/SSO specification][xsso].
 
-## Features
+## Cargo Features
 
 The `helpers` feature (optional, but on by default) exports two helpers for PAM memory management.
 
@@ -23,6 +26,21 @@
 
 Neither are directly referenced elsewhere, and both allow you to bring your own storage abstractions.
 
+## Testing
+
+Tests are mostly run through `libpam-sys-test`, which lives in the crate's workspace in its repository (along with [nonstick]).
+
+- [`ctest`][ctest] verifies the correctness of the FFI bindings (function/struct alignment, etc.).
+- A kind of scuffed homebrew thing also verifies that the constants are correct.
+
+Testing is mainly accomplished through the `libpam-sys-test` package in this crate's workspace.
+There are some unit tests of glue code and other type checks.
+
+## Minimum Rust version
+
+This crate supports **Rust 1.75**, the current version in Debian Trixie and Ubuntu 24.04.2 LTS.
+There shouldn't be much that needs changing, since PAM's API is quite stable.
+
 ## References
 
 - [X/SSO PAM specification][xsso]: This 1997 document laid out the original specification for PAM.
@@ -34,6 +52,8 @@
 - [Illumos PAM repository][illumos-pam]: Illumos's implementation of PAM, based on Sun's Solaris. Even more basic than OpenPAM.
   - [Illumos PAM man page][manillumos]: Illumos's root man page for its PAM implementation.
 
+[ctest]: https://github.com/rust-lang/libc/tree/ctest-v0.4.11/ctest
+[nonstick]: https://crates.io/crates/nonstick
 [xsso]: https://pubs.opengroup.org/onlinepubs/8329799/toc.htm
 [linux-pam]: https://github.com/linux-pam/linux-pam
 [man7]: https://www.man7.org/linux/man-pages/man8/pam.8.html
--- a/libpam-sys/libpam-sys-impls/Cargo.toml	Mon Jun 30 23:00:53 2025 -0400
+++ b/libpam-sys/libpam-sys-impls/Cargo.toml	Mon Jun 30 23:49:54 2025 -0400
@@ -4,13 +4,13 @@
 version = "0.0.1"
 rust-version.workspace = true
 edition.workspace = true
+readme = "README.md"
 
 [lib]
 proc-macro = true
 
 
 [build-dependencies]
-bindgen = "0.72.0"
 dlopen = "0.1.8"
 proc-macro2 = "1.0.95"
 quote = "1.0.40"
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libpam-sys/libpam-sys-impls/README.md	Mon Jun 30 23:49:54 2025 -0400
@@ -0,0 +1,6 @@
+# `libpam-sys-impls`
+
+This crate is an internal implementation detail of the [`libpam-sys`] crate.
+Its one public-facing macro is documented there.
+
+[`libpam-sys`]: https://docs.rs/libpam-sys
\ No newline at end of file
--- a/libpam-sys/libpam-sys-impls/src/lib.rs	Mon Jun 30 23:00:53 2025 -0400
+++ b/libpam-sys/libpam-sys-impls/src/lib.rs	Mon Jun 30 23:49:54 2025 -0400
@@ -1,3 +1,10 @@
+//! Internal-use macros for [`libpam-sys`]. Please don't use them.
+//!
+//! The build script detects what the current PAM implementation is,
+//! and then these macros generate code based on that.
+//!
+//! [`libpam-sys`]: https://docs.rs/libpam-sys
+
 use proc_macro as pm;
 use proc_macro2::{Delimiter, Group, Literal, Span, TokenStream, TokenTree};
 use quote::{format_ident, quote};
--- a/libpam-sys/libpam-sys-test/Cargo.toml	Mon Jun 30 23:00:53 2025 -0400
+++ b/libpam-sys/libpam-sys-test/Cargo.toml	Mon Jun 30 23:49:54 2025 -0400
@@ -4,6 +4,7 @@
 edition.workspace = true
 rust-version.workspace = true
 publish = false
+readme = "README.md"
 
 [dependencies]
 libc = "0.2.174"
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libpam-sys/libpam-sys-test/README.md	Mon Jun 30 23:49:54 2025 -0400
@@ -0,0 +1,8 @@
+# The `libpam-sys` tests
+
+This crate exists to provide tests for `libpam-sys`, without being part of it and having all its dependencies come along.
+It works like [the `libc-test` crate][libc-test] for `libc` (and also uses `ctest`).
+
+The `build.rs` script generates test code which is included by files in `tests/`.
+
+[libc-test]: https://github.com/rust-lang/libc/tree/ctest-v0.4.11/libc-test
--- a/libpam-sys/src/ffi.rs	Mon Jun 30 23:00:53 2025 -0400
+++ b/libpam-sys/src/ffi.rs	Mon Jun 30 23:49:54 2025 -0400
@@ -218,7 +218,3 @@
 extern "C" {
     pub fn pam_get_authtok(pamh: *mut pam_handle, x: c_int, token: *mut *const c_char, prompt: *const c_char) -> c_int;
 }
-
-
-// int (*)(struct pam_handle *, char *, void *, void (*)(struct pam_handle *, void *, int))
-// int (*)(struct pam_handle *, char *, void *, int (*)(struct pam_handle *, void *, int))
\ No newline at end of file