Mercurial > crates > nonstick

annotate libpam-sys/libpam-sys-helpers/README.md @ 141:a508a69c068a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Remove a lot of Results from functions. Many functions are documented to only return failing Results when given improper inputs or when there is a memory allocation failure (which can be verified by looking at the source). In cases where we know our input is correct, we don't need to check for memory allocation errors for the same reason that Rust doesn't do so when you, e.g., create a new Vec.
author Paul Fisher <paul@pfish.zone>
date Sat, 05 Jul 2025 17:16:56 -0400
parents efbc235f01d3
children 4b3a5095f68c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
1 # `libpam-sys-helpers`: cross-platform tools for libpam
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
3 This crate contains tools for `libpam` that **don't directly link to `libpam.so`**.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4 This allows for creation of `libpam` abstractions (e.g. test doubles) that don't require libpam to be present if they don't link directly into it.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
5
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
6 ## Handling PAM implementations
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8 Different PAM implementations have different constants and some different behaviors.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9 If you need to change your behavior based on PAM implementation, there are a few ways to do so.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11 ### Constants
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
12
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
13 The current PAM implementation is available in `PamImpl::CURRENT`.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 This is present as a string literal macro in `pam_impl_name!`.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
16 ### Conditional compilation
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
18 This package provides custom `#[cfg]`s to compile based on the current PAM implementation.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
20 First, **enable custom `#[cfg]`s in your build.rs**:
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22 ```rust
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23 // build.rs
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
24 use libpam_sys_helpers::pam_impl;
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 fn main() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 pam_impl::enable_pam_impl_cfg();
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29 // everything else you do at build time
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31 ```
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
32
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
33 This will then allow you to use the `pam_impl` configuration variable at compile time:
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
34
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35 ```rust
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36 #[cfg(pam_impl = "LinuxPam")]
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 fn handle_pam() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 // do things in a Linux-PAM specific way
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
39 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 #[cfg(not(pam_impl = "LinuxPam"))]
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42 fn handle_pam() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 // do things in another way
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 ```
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 ## Configuration
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 By default, this crate automatically detects your libpam version.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 Known implementations are listed in the `PamImpl` enum.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 You can override this **at build time** by setting the `LIBPAMSYS_IMPL` environment variable to one of those names.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 For example, `LIBPAMSYS_IMPL=OpenPam cargo build` will build this library for OpenPAM.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
55 ## MSRV
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.