Mercurial > crates > nonstick

comparison libpam-sys/libpam-sys-helpers/README.md @ 136:efbc235f01d3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Separate libpam-sys-helpers from libpam-sys. This separates the parts of libpam-sys that don't need linking against libpam from the parts that do need to link against libpam.
author Paul Fisher <paul@pfish.zone>
date Thu, 03 Jul 2025 14:28:04 -0400
parents
children 4b3a5095f68c
comparison
equal deleted inserted replaced
135:b52594841480 136:efbc235f01d3
1 # `libpam-sys-helpers`: cross-platform tools for libpam
2
3 This crate contains tools for `libpam` that **don't directly link to `libpam.so`**.
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.
5
6 ## Handling PAM implementations
7
8 Different PAM implementations have different constants and some different behaviors.
9 If you need to change your behavior based on PAM implementation, there are a few ways to do so.
10
11 ### Constants
12
13 The current PAM implementation is available in `PamImpl::CURRENT`.
14 This is present as a string literal macro in `pam_impl_name!`.
15
16 ### Conditional compilation
17
18 This package provides custom `#[cfg]`s to compile based on the current PAM implementation.
19
20 First, **enable custom `#[cfg]`s in your build.rs**:
21
22 ```rust
23 // build.rs
24 use libpam_sys_helpers::pam_impl;
25
26 fn main() {
27 pam_impl::enable_pam_impl_cfg();
28
29 // everything else you do at build time
30 }
31 ```
32
33 This will then allow you to use the `pam_impl` configuration variable at compile time:
34
35 ```rust
36 #[cfg(pam_impl = "LinuxPam")]
37 fn handle_pam() {
38 // do things in a Linux-PAM specific way
39 }
40
41 #[cfg(not(pam_impl = "LinuxPam"))]
42 fn handle_pam() {
43 // do things in another way
44 }
45 ```
46
47 ## Configuration
48
49 By default, this crate automatically detects your libpam version.
50 Known implementations are listed in the `PamImpl` enum.
51
52 You can override this **at build time** by setting the `LIBPAMSYS_IMPL` environment variable to one of those names.
53 For example, `LIBPAMSYS_IMPL=OpenPam cargo build` will build this library for OpenPAM.
54
55 ## MSRV
56
57 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.