Mercurial > crates > nonstick

annotate libpam-sys/libpam-sys-consts/README.md @ 158:d5b7b28d754e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build. Also fixes some formatting stuff.
author Paul Fisher <paul@pfish.zone>
date Sat, 12 Jul 2025 17:17:37 -0400
parents 4b3a5095f68c
children 09dff285ff5e
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
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
3 This crate does two primary things:
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
5 - Detects which implementation of LibPAM the current machine uses (as part of the build script), and exports that information to downstream crates.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
6 - 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
7 These are located in the `constants` module.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9 ## Handling different PAM implmementations
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11 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
12 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
13
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 ### Constants
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
16 The current PAM implementation is available in `PamImpl::CURRENT`.
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17 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
18
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19 ### Conditional compilation
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
20
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21 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
22
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23 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
24
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25 ```rust
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 // build.rs
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 use libpam_sys_helpers::pam_impl;
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29 fn main() {
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 pam_impl::enable_pam_impl_cfg();
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
32 // everything else you do at build time
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 ```
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36 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
37
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 ```rust
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
39 #[cfg(pam_impl = "LinuxPam")]
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40 fn handle_pam() {
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 // 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
42 }
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 #[cfg(not(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 another, more different 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
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 ## Configuration
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51
158
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
52 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
53
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
54 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
55
158
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
56 - Unset or `` (the default): Probe the currently installed LibPAM to figure out which implementation it is.
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
57 If LibPAM is not present, this will fall back to `__TARGET_DEFAULT__`.
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
58 - `__TARGET_DEFAULT__`: Select the version of LibPAM most likely to be installed on the current OS.
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
59 This is a useful setting for cross-compiling.
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
60 - The name of a `PamEnum` entry: The named PAM implementation.
d5b7b28d754e Add `__TARGET_DEFAULT__` PamImpl and set up for docsrs build.
Paul Fisher <paul@pfish.zone>
parents: 148
diff changeset
61 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
62
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
63 ## MSRV
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
64
4b3a5095f68c Move libpam-sys helpers into their own library.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
65 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.