krb5_src/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//! Build system integration for [libkrb5], MIT's Kerberos implementation.
17//!
18//! This crate builds a vendored copy of libkrb5 using Cargo's support for
19//! custom build scripts. It is not intended for direct consumption, but as a
20//! dependency for other crates that need libkrb5 available, like [sasl2-sys].
21//!
22//! krb5-src is currently bundling libkrb5 [v1.19.2].
23//!
24//! To use this crate, declare a `dependency` or `dev-dependency` on `krb5-src`.
25//! Then, in the build script for your crate, the environment variable
26//! `DEP_KRB5_SRC_ROOT` will point to the directory in which the bundled copy of
27//! libkrb5 has been installed. You can build and link another C library against
28//! this copy of libkrb5, or generate Rust bindings and link Rust code against
29//! this copy of libkrb5.
30//!
31//! Note that you are responsible for instructing Cargo to link in the
32//! components of libkrb5 that you depend upon. Here is an example build script
33//! fragment.
34//!
35//! ```no_run
36//! # use std::env;
37//! # use std::path::PathBuf;
38//! println!(
39//! "cargo:rustc-link-search=native={}",
40//! PathBuf::from(env::var("DEP_KRB5_SRC_ROOT").unwrap()).join("lib").display(),
41//! );
42//! println!("cargo:rustc-link-lib=static=gssapi_krb5");
43//! println!("cargo:rustc-link-lib=static=krb5");
44//! println!("cargo:rustc-link-lib=static=k5crypto");
45//! println!("cargo:rustc-link-lib=static=com_err");
46//! println!("cargo:rustc-link-lib=static=krb5support");
47//! ```
48//!
49//! # Cargo features
50//!
51//! krb5-src can be configured with the following Cargo features:
52//!
53//! * **`binaries`** builds the binaries that come with libkrb5 (kinit,
54//! kdestroy, et al.) and installs them into `DEP_KRB5_SRC_ROOT/bin`.
55//!
56//! * **`nls`** enables native language support (i.e., localization). This
57//! feature corresponds to the `--enable-nls` configure flag.
58//!
59//! On some platforms, when this feature is enabled, the application must
60//! additionally link against libintl.
61//!
62//! * **`openssl-vendored`** enables the `vendored` feature of the `openssl-sys`
63//! crate.
64//!
65//! Note that none of these features have any effect when compiling on Windows.
66//!
67//! # Platform support
68//!
69//! krb5-src is tested on recent versions of Ubuntu, macOS, and Windows. Patches
70//! that improve support for other platforms are welcome.
71//!
72//! [libkrb5]: https://web.mit.edu/kerberos/
73//! [v1.19.2]: https://web.mit.edu/kerberos/krb5-1.19/
74//! [sasl2-sys]: https://github.com/MaterializeInc/rust-sasl