//! A safe, nonstick interface to PAM.
//!
//! This implements a type-safe library to interact with PAM.
//! Currently, it implements a subset of PAM useful for implementing a module.
//!
//! To write a new PAM module using this crate:
//!
//!  1. Create a `dylib` crate.
//!  2. Implement a subset of the functions in the [`PamModule`] trait
//!     corresponding to what you want your module to do.
//!     In the simplest case (for a new password-based authenticator),
//!     this will be the [`PamModule::authenticate`] function.
//!  3. Export your PAM module using the [`pam_export!`] macro.
//!  4. Build and install the dynamic library.
//!     This usually entails placing it at
//!     <code>/usr/lib/security/pam_<var>your_module</var>.so</code>,
//!     or maybe
//!     <code>/usr/lib/<var>your-architecture</var>/security/pam_<var>your_module</var>.so</code>.
//!
//! For general information on writing PAM modules, see
//! [The Linux-PAM Module Writers' Guide][module-guide]
//!
//! [module-guide]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html

#[cfg(feature = "link")]
mod _compat_checker {
    macro_rules! feature_check {
        ($feature:literal, pam_impl = ($($pimpl:literal),*)) => {
            #[cfg(all(feature = $feature, not(any($(pam_impl = $pimpl),*))))]
            compile_error!(
                concat!(
                    "The feature '", $feature, "' is only available ",
                    "with these PAM implementations:\n",
                    $("- ", $pimpl, "\n"),*,
                    "The current PAM implementation is:\n\n",
                    "  ", libpam_sys::pam_impl_name!(), "\n\n",
                    "Set the 'LIBPAMSYS_IMPL' environment variable to one of ",
                    "the above PAM implementation names to build ",
                    "for that implementation of PAM."
                )
            );
        }
    }
    feature_check!("linux-pam-ext", pam_impl = ("LinuxPam"));
    feature_check!("basic-ext", pam_impl = ("LinuxPam", "OpenPam"));
    feature_check!("openpam-ext", pam_impl = ("OpenPam"));
    feature_check!("sun-ext", pam_impl = ("Sun"));
}

pub mod constants;
pub mod conv;
pub mod module;

pub mod handle;

mod _doc;
mod environ;
pub mod items;
#[cfg(feature = "link")]
pub mod libpam;
pub mod logging;

#[cfg(feature = "link")]
#[doc(inline)]
pub use crate::libpam::{LibPamHandle, LibPamTransaction, TransactionBuilder};
#[doc(inline)]
pub use crate::{
    constants::{
        AuthnFlags, AuthtokAction, AuthtokFlags, BaseFlags, CredAction, ErrorCode, Result,
    },
    conv::{BinaryData, Conversation, ConversationAdapter},
    environ::{EnvironMap, EnvironMapMut},
    handle::{ModuleClient, PamShared, Transaction},
    module::PamModule,
};