sasl2_sys/
lib.rs

1// Copyright Materialize, Inc. All rights reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License in the LICENSE file at the
6// root of this repository, or online at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16#![allow(non_camel_case_types, non_upper_case_globals, non_snake_case)]
17
18//! Bindings to Cyrus SASL.
19//!
20//! This crate provides raw bindings to the [Cyrus SASL library][upstream],
21//! libsasl2. Each module corresponds to a public header file in the [C
22//! API][c-api].
23//!
24//! # Build configuration
25//!
26//! ## Vendored
27//!
28//! If the `vendored` Cargo feature is enabled, a bundled copy of libsasl2 will
29//! be compiled and statically linked. The libsasl2 version will generally track
30//! the latest upstream release. Note that the version number of this crate is
31//! unrelated to the bundled version of libsasl2.
32//!
33//! sasl2-sys is currently bundling libsasl2 [v2.1.28].
34//!
35//! When configuring the bundled library, sasl2-sys is intentionally
36//! conservative in the features it enables. All optional features are disabled
37//! by default. The following Cargo features can be used to re-enable features
38//! as necessary.
39//!
40//!   * **`gssapi-vendored`** enables the GSSAPI plugin (`--enable-gssapi`) by
41//!      building and statically linking a copy of MIT's Kerberos implementation
42//!      using the [krb5-src] crate.
43//!
44//!      This feature is not supported on Windows.
45//!
46//!   * **`plain`** enables the PLAIN plugin (`--enable-plain`).
47//!
48//!   * **`scram`** enables the SCRAM plugin (`--enable-scram`). This requires
49//!     linking against OpenSSL via the [openssl-sys] crate.
50//!
51//! Note that specifying any of these features implies `vendored`.
52//!
53//! For convenience, the `vendored` feature of the [openssl-sys] crate is
54//! re-exported as the `openssl-vendored` feature. This feature is unlikely to
55//! be useful unless used in conjuction with the `scram` feature.
56//!
57//! The eventual goal is to expose each libsasl2 feature behind a Cargo feature
58//! of the same name. Pull requests on this front are welcomed.
59//!
60//! ## System
61//!
62//! Without the `vendored` Cargo feature, sasl2-sys will search for the libsasl2
63//! library and headers in several standard locations. If the `pkg-config`
64//! feature is enabled, as it is by default, pkg-config will be queried for the
65//! location of the sasl2 library.
66//!
67//! To override the automatic search, set the `SASL2_DIR` environment variable
68//! to the path of the directory containing the desired libsasl2 directory.
69//!
70//! If the layout of the libsasl2 directory is nonstandard, set the
71//! `SASL2_LIB_DIR` and `SASL2_INCLUDE_DIR` environment variables to the path of
72//! the directory containining the libsasl2 libraries and headers, respectively.
73//! These environment variables take precedence over `SASL2_DIR` if set.
74//!
75//! When linking against a system library, dynamic linking is preferred unless
76//! the `SASL2_STATIC` environment variable is set.
77//!
78//! # Platform support
79//!
80//! Upstream supports [most major platforms][upstream-platforms], but sasl2-sys
81//! is only tested on recent versions of Ubuntu, macOS, and Windows. Patches
82//! that improve support for other platforms are welcome.
83//!
84//! [c-api]: https://github.com/cyrusimap/cyrus-sasl/tree/master/include
85//! [krb5-src]: https://github.com/MaterializeInc/rust-krb5-src
86//! [openssl-sys]: https://github.com/sfackler/rust-openssl
87//! [upstream]: https://www.cyrusimap.org/sasl
88//! [upstream-platforms]: https://www.cyrusimap.org/sasl/sasl/installation.html#supported-platforms
89//! [v2.1.28]: https://github.com/cyrusimap/cyrus-sasl/releases/tag/cyrus-sasl-2.1.28
90
91#[cfg(feature = "openssl-sys")]
92extern crate openssl_sys;
93
94pub mod hmac_md5;
95pub mod md5;
96pub mod prop;
97pub mod sasl;
98pub mod saslplug;
99pub mod saslutil;
100
101/// Almagamates exports from all other modules.
102pub mod prelude {
103    pub use super::hmac_md5::*;
104    pub use super::md5::*;
105    pub use super::prop::*;
106    pub use super::sasl::*;
107    pub use super::saslplug::*;
108    pub use super::saslutil::*;
109}
sasl2_sys/lib.rs

sasl2_sys/
lib.rs
