Mercurial > crates > nonstick

comparison libpam-sys/libpam-sys-impls/README.md @ 176:0730f5f2ee2a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Turn `libpam-sys-consts` back into `libpam-sys-impls`. This moves the constants into `libpam-sys` and makes `libpam-sys-impls` responsible solely for detecting the current PAM implementation.
author Paul Fisher <paul@pfish.zone>
date Wed, 30 Jul 2025 17:53:31 -0400
parents libpam-sys/libpam-sys-consts/README.md@180237d0b498
children 995aca290452
comparison
equal deleted inserted replaced
175:e30775c80b49 176:0730f5f2ee2a
1 # `libpam-sys-impls`: LibPAM library detection
2
3 This crate detects what implementation of LibPAM should be used, as part of the build script, and exports that information to downstream crates.
4
5 This is mostly a backend crate for [libpam-sys](https://crates.io/crates/libpam-sys/).
6 That crate re-exports pretty much everything we provide.
7 In most cases, you can just use that instead of depending upon this directly.
8
9 ## Usage
10
11 Different PAM implementations have different constants and some different behaviors.
12 If you need to change your library's behavior based on PAM implementation, there are a few ways to do so.
13
14 ### Constants
15
16 You can match on the current PAM implementation at runtime.
17 All known PAM implementations are in the `PamImpl` enumeration, and `PamImpl::CURRENT` is set to the current implementation.
18 This is present as a string literal macro in `pam_impl_name!`.
19
20 ### Conditional compilation
21
22 This package provides custom `#[cfg]`s to compile based on the current PAM implementation.
23
24 First, **enable custom `#[cfg]`s in your build.rs**:
25
26 ```rust
27 // build.rs
28 use libpam_sys_impls::pam_impl;
29
30 fn main() {
31 pam_impl::enable_pam_impl_cfg();
32
33 // everything else you do at build time
34 }
35 ```
36
37 This will then allow you to use the `pam_impl` configuration variable at compile time:
38
39 ```rust
40 #[cfg(pam_impl = "LinuxPam")]
41 fn handle_pam() {
42 // do things in a Linux-PAM specific way
43 }
44
45 #[cfg(not(pam_impl = "LinuxPam"))]
46 fn handle_pam() {
47 // do things in another, more different way
48 }
49 ```
50
51 ## Configuration
52
53 Known implementations of PAM are listed in the `PamImpl` enum, and your currently installed implementation is automatically detected.
54
55 If you need to configure this, you can override it **at build time** with the `LIBPAMSYS_IMPL` environment variable:
56
57 - Unset or empty (the default): Use the version of PAM most commonly found on the target OS.
58 If we don't know what kind of PAM is usually installed on this OS, we fall back to `__installed__`.
59 - `__installed__`: Looks at the PAM library installed on the current machine.
60 If none is recognized, falls back to `XSso`.
61 - The name of a `PamImpl` entry: The named PAM implementation.
62 For instance, `LIBPAMSYS_IMPL=OpenPam cargo build` will build this library for OpenPAM.
63
64 ## MSRV
65
66 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.