Mercurial > crates > nonstick

comparison libpam-sys/libpam-sys-impls/README.md @ 190:995aca290452

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Restructure the way libpam-sys-impls works to fix cross-compilation. The previous structure of libpam-sys-impls meant that things got confusing (including for me) between what constants were build-time and what constants were run-time. This broke cross-compilation. This simplifies the way that works so that `libpam-sys-impls` has *no* build script itself and is intended mostly as a library to be included in other libraries' build scripts (while also exporting the PamImpl enum).
author Paul Fisher <paul@pfish.zone>
date Sat, 02 Aug 2025 18:47:46 -0400
parents 0730f5f2ee2a
children
comparison
equal deleted inserted replaced
189:b2456d274576 190:995aca290452
1 # `libpam-sys-impls`: LibPAM library detection 1 # `libpam-sys-impls`: LibPAM library detection
2 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. 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 It can also be used at runtime, but is primarily intended for build scripts.
4 5
5 This is mostly a backend crate for [libpam-sys](https://crates.io/crates/libpam-sys/). 6 Its main use is as a backend for [libpam-sys](https://crates.io/crates/libpam-sys/).
6 That crate re-exports pretty much everything we provide. 7 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 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 9
64 ## MSRV 10 ## MSRV
65 11
66 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS. 12 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.