Mercurial > crates > nonstick

annotate libpam-sys/libpam-sys-helpers/README.md @ 136:efbc235f01d3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Separate libpam-sys-helpers from libpam-sys. This separates the parts of libpam-sys that don't need linking against libpam from the parts that do need to link against libpam.
author Paul Fisher <paul@pfish.zone>
date Thu, 03 Jul 2025 14:28:04 -0400
parents
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
136
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
1 # `libpam-sys-helpers`: cross-platform tools for libpam
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
2
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
3 This crate contains tools for `libpam` that **don't directly link to `libpam.so`**.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
4 This allows for creation of `libpam` abstractions (e.g. test doubles) that don't require libpam to be present if they don't link directly into it.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
5
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
6 ## Handling PAM implementations
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
7
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
8 Different PAM implementations have different constants and some different behaviors.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
9 If you need to change your behavior based on PAM implementation, there are a few ways to do so.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
10
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
11 ### Constants
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
12
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
13 The current PAM implementation is available in `PamImpl::CURRENT`.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
14 This is present as a string literal macro in `pam_impl_name!`.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
15
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
16 ### Conditional compilation
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
17
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
18 This package provides custom `#[cfg]`s to compile based on the current PAM implementation.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
19
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
20 First, **enable custom `#[cfg]`s in your build.rs**:
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
21
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
22 ```rust
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
23 // build.rs
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
24 use libpam_sys_helpers::pam_impl;
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
25
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
26 fn main() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
27 pam_impl::enable_pam_impl_cfg();
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
28
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
29 // everything else you do at build time
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
30 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
31 ```
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
32
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
33 This will then allow you to use the `pam_impl` configuration variable at compile time:
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
34
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
35 ```rust
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
36 #[cfg(pam_impl = "LinuxPam")]
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
37 fn handle_pam() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
38 // do things in a Linux-PAM specific way
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
39 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
40
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
41 #[cfg(not(pam_impl = "LinuxPam"))]
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
42 fn handle_pam() {
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
43 // do things in another way
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
44 }
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
45 ```
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
46
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
47 ## Configuration
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
48
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
49 By default, this crate automatically detects your libpam version.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
50 Known implementations are listed in the `PamImpl` enum.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
51
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
52 You can override this **at build time** by setting the `LIBPAMSYS_IMPL` environment variable to one of those names.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
53 For example, `LIBPAMSYS_IMPL=OpenPam cargo build` will build this library for OpenPAM.
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
54
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
55 ## MSRV
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
56
efbc235f01d3 Separate libpam-sys-helpers from libpam-sys.
Paul Fisher <paul@pfish.zone>
parents:
diff changeset
57 This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.