# `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.