Mercurial > crates > nonstick

annotate libpam-sys/libpam-sys-consts/README.md @ 171:e27c5c667a5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.
author Paul Fisher <paul@pfish.zone>
date Fri, 25 Jul 2025 20:52:14 -0400
parents 180237d0b498
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.