Mercurial > crates > nonstick
annotate libpam-sys/libpam-sys-helpers/README.md @ 141:a508a69c068a
Remove a lot of Results from functions.
Many functions are documented to only return failing Results when given
improper inputs or when there is a memory allocation failure (which
can be verified by looking at the source). In cases where we know our
input is correct, we don't need to check for memory allocation errors
for the same reason that Rust doesn't do so when you, e.g., create a
new Vec.
author | Paul Fisher <paul@pfish.zone> |
---|---|
date | Sat, 05 Jul 2025 17:16:56 -0400 |
parents | efbc235f01d3 |
children | 4b3a5095f68c |
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. |