# `libpam-sys-impls`: LibPAM library detection

This crate detects what implementation of LibPAM should be used, as part of the build script, and exports that information to downstream crates.

This is mostly a backend crate for [libpam-sys](https://crates.io/crates/libpam-sys/).
That crate re-exports pretty much everything we provide.
In most cases, you can just use that instead of depending upon this directly.

## Usage

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

### Constants

You can match on the current PAM implementation at runtime.
All known PAM implementations are in the `PamImpl` enumeration, and `PamImpl::CURRENT` is set to the current implementation.
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_impls::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, more different way
}
```

## Configuration

Known implementations of PAM are listed in the `PamImpl` enum, and your currently installed implementation is automatically detected.

If you need to configure this, you can override it **at build time** with the `LIBPAMSYS_IMPL` environment variable:

- Unset or empty (the default): Use the version of PAM most commonly found on the target OS.
  If we don't know what kind of PAM is usually installed on this OS, we fall back to `__installed__`.
- `__installed__`: Looks at the PAM library installed on the current machine.
  If none is recognized, falls back to `XSso`.
- The name of a `PamImpl` entry: The named PAM implementation.
  For instance, `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.