view 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
line wrap: on
line source

# `libpam-sys-helpers`: cross-platform tools for libpam

This crate contains tools for `libpam` that **don't directly link to `libpam.so`**.
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.

## Handling PAM implementations

Different PAM implementations have different constants and some different behaviors.
If you need to change your behavior based on PAM implementation, there are a few ways to do so.

### Constants

The current PAM implementation is available in `PamImpl::CURRENT`.
This is present as a string literal macro in `pam_impl_name!`.

### Conditional compilation

This package provides custom `#[cfg]`s to compile based on the current PAM implementation.

First, **enable custom `#[cfg]`s in your build.rs**:

```rust
// build.rs
use libpam_sys_helpers::pam_impl;

fn main() {
    pam_impl::enable_pam_impl_cfg();
    
    // everything else you do at build time
}
```

This will then allow you to use the `pam_impl` configuration variable at compile time:

```rust
#[cfg(pam_impl = "LinuxPam")]
fn handle_pam() {
    // do things in a Linux-PAM specific way
}

#[cfg(not(pam_impl = "LinuxPam"))]
fn handle_pam() {
    // do things in another way
}
```

## Configuration

By default, this crate automatically detects your libpam version.
Known implementations are listed in the `PamImpl` enum.

You can override this **at build time** by setting the `LIBPAMSYS_IMPL` environment variable to one of those names.
For example, `LIBPAMSYS_IMPL=OpenPam cargo build` will build this library for OpenPAM.

## MSRV

This library supports **Rust 1.75**, as the version currently (July 2025) available in Debian Trixie and Ubuntu 24.04 LTS.