Mercurial > crates > nonstick

comparison libpam-sys/libpam-sys-helpers/README.md @ 148:4b3a5095f68c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Move libpam-sys helpers into their own library. - Renames libpam-sys-helpers to libpam-sys-consts. - Moves libpam-sys-helpers::helpers into libpam-sys-helpers, which moves them completely out of libpam-sys's dependency chain. - Moves the aliases from libpam-sys into libpam-sys::aliases.
author Paul Fisher <paul@pfish.zone>
date Mon, 07 Jul 2025 12:11:43 -0400
parents efbc235f01d3
children 0730f5f2ee2a
comparison
equal deleted inserted replaced
147:4d7333337569 148:4b3a5095f68c
1 # `libpam-sys-helpers`: cross-platform tools for libpam 1 # `libpam-sys-helpers`: Cross-platform helpers for `libpam-sys`
2 2
3 This crate contains tools for `libpam` that **don't directly link to `libpam.so`**. 3 This provides memory-management helpers for `libpam-sys`.
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 4
6 ## Handling PAM implementations 5 This does not actually depend upon `libpam-sys`; it only uses `libpam-sys-consts`.
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.