1 files changed, 67 insertions, 0 deletions
diff --git a/libsyslog/src/lib.rs b/libsyslog/src/lib.rs
index e69de29..7c253ae 100644
--- a/libsyslog/src/lib.rs
+++ b/libsyslog/src/lib.rs
@@ -0,0 +1,67 @@
+//! This crate provides an API implementing the standard Rust logging facade
+//! to the system's syslog. That is, it implements the [Log][log::Log] trait
+//! of the [log] crate for native syslog (the one typically implemented in C
+//! and residing in libc).
+//!
+//! Syslog needs to be initialized prior to any [logging macros][log#macros]
+//! being called. That is usally done through a single chained call of its
+//! [builder][Syslog::builder], with optional
+//! [methods][SyslogBuilder#implementations] to customize the logger before
+//! finalizing the setup by calling [build][SyslogBuilder::build] and
+//! [init][Syslog::init].
+//!
+//! Typical use: (A.k.a. recommended snippet to copy'n'paste to the start of
+//! `main()` of your daemon.)
+//! ```
+//! # fn main() -> Result<()> {
+//! libsyslog::Syslog::builder()
+//!     .module_level(std::module_path!(), log::LevelFilter::Info)
+//!     .level(log::LevelFilter::Off)
+//!     .build()
+//!     .init()?;
+//!
+//! error!("Hello libsyslog. I've failed you.");
+//! # }
+//! ```
+//!
+//! It is likely reasonable for most users to configure the
+//! [module_level][SyslogBuilder::module_level] and
+//! [level][SyslogBuilder::level] filters to only have the application's own
+//! log messages sent to syslog (ignoring potentially chatty libraries), as in
+//! the above example.
+//!
+//! The scope of this crate is limited as described by the very first paragraph
+//! above. Its intended use is during normal operation, in software with modest
+//! requirements on low frequency logging. Note that syslog risks killing
+//! performance. Consider using another additional facade, in combination with
+//! a `--no-daemon` option, for when developing and debugging. And please
+//! remember, if [libsyslog][`crate`] does not meet your requirements, there
+//! are plenty of other crates for logging around.
+
+// According to [doc][], syslog() and friends are not thread safe on AIX. It
+// appears there is a family or related functions with an _r suffix which
+// should likely be used instead. Patches for adding AIX support are welcome.
+//
+// It should of course possible to locally disable the check below, but then
+// it's up to you to ensure your application is single threaded.
+//
+#[cfg(target_os = "aix")]
+compile_error!("AIX user, please help with the code comment above this error.");
+//
+// [doc]: https://www.ibm.com/docs/en/aix/latest?topic=s-syslog-openlog-closelog-setlogmask-subroutine
+
+mod builder;
+mod facility;
+// TODO Deprecate feature once the bitflags crate reaches 2.0.0.
+#[cfg(feature = "bitflags")]
+mod logopt;
+mod syslog;
+
+#[cfg(feature = "bitflags")]
+pub use logopt::*;
+
+pub use {
+    builder::*,
+    facility::*,
+    syslog::*,
+};