Mercurial > crates > nonstick

annotate libpam-sys/libpam-sys-consts/README.md @ 162:180237d0b498

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve README files for libpam-sys and libpam-sys-consts.
author Paul Fisher <paul@pfish.zone>
date Mon, 14 Jul 2025 15:07:16 -0400
parents e9354e655f38
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
1 # `libpam-sys-consts`: Constants for LibPAM
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2
162
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
3 This is mostly a backend crate for [libpam-sys](https://crates.io/crates/libpam-sys/).
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
4 That crate re-exports pretty much everything we provide.
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
5 In most cases, you can just use that instead of depending upon this directly.
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
6
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7 This crate does two primary things:
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8
162
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
9 - Detects which implementation of LibPAM to use (as part of the build script), and exports that information to downstream crates.
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10 - Exports the constants specific to that version of LibPAM.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11 These are located in the `constants` module.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
12
162
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
13 ## Handling different PAM implementations
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15 Different PAM implementations have different constants and some different behaviors.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
16 If you need to change your library's behavior based on PAM implementation, there are a few ways to do so.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
18 ### Constants
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19
162
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
20 You can match on the current PAM implementation at runtime.
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
21 All known PAM implementations are in the `PamImpl` enumeration, and `PamImpl::CURRENT` is set to the current implementation.
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22 This is present as a string literal macro in `pam_impl_name!`.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
24 ### Conditional compilation
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 This package provides custom `#[cfg]`s to compile based on the current PAM implementation.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28 First, **enable custom `#[cfg]`s in your build.rs**:
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 ```rust
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31 // build.rs
161
e9354e655f38 Improve PAM detection docs.
Paul Fisher <paul@pfish.zone>
parents: 160
diff changeset
32 use libpam_sys_consts::pam_impl;
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
33
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
34 fn main() {
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35 pam_impl::enable_pam_impl_cfg();
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 // everything else you do at build time
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 }
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
39 ```
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 This will then allow you to use the `pam_impl` configuration variable at compile time:
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 ```rust
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 #[cfg(pam_impl = "LinuxPam")]
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 fn handle_pam() {
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46 // do things in a Linux-PAM specific way
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 }
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 #[cfg(not(pam_impl = "LinuxPam"))]
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 fn handle_pam() {
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51 // do things in another, more different way
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 }
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 ```
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
55 ## Configuration
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56
158
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
57 Known implementations of PAM are listed in the `PamImpl` enum, and your currently installed implementation is automatically detected.
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
58
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
59 If you need to configure this, you can override it **at build time** with the `LIBPAMSYS_IMPL` environment variable:
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
60
160
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
61 - Unset or empty (the default): Use the version of PAM most commonly found on the target OS.
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
62 If we don't know what kind of PAM is usually installed on this OS, we fall back to `__installed__`.
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
63 - `__installed__`: Looks at the PAM library installed on the current machine.
09dff285ff5e Switch default PAM detection strategy to target-based.
Paul Fisher <paul@pfish.zone>
parents: 158
diff changeset
64 If none is recognized, falls back to `XSso`.
162
180237d0b498 Improve README files for libpam-sys and libpam-sys-consts.
Paul Fisher <paul@pfish.zone>
parents: 161
diff changeset
65 - The name of a `PamImpl` entry: The named PAM implementation.
158
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
66 For instance, `LIBPAMSYS_IMPL=OpenPam cargo build` will build this library for OpenPAM.
148
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
67
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
68 ## MSRV
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
69
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
70 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.