Crate license_fetcher 

Fetch licenses of dependencies at build time and embed them into your program.

license-fetcher is a crate for fetching actual license texts from the cargo source directory for crates that are compiled with your project. It does this in the build step in a build script. This means that the heavy dependencies of license-fetcher aren’t your dependencies!

Example

Import license-fetcher as a normal AND as a build dependency:

cargo add --build --features build license-fetcher
cargo add license-fetcher

src/main.rs

use license_fetcher::read_package_list_from_out_dir;
fn main() {
    let package_list = read_package_list_from_out_dir!().unwrap();
}

build.rs

use license_fetcher::build::config::{ConfigBuilder, Config};
use license_fetcher::build::package_list_with_licenses;
use license_fetcher::PackageList;

fn main() {
    // Config with environment variables set by cargo, to fetch licenses at build time.
    let config: Config = ConfigBuilder::from_build_env()
        .build()
        .expect("Failed to build configuration.");

    let packages: PackageList = package_list_with_licenses(config)
                                    .expect("Failed to fetch metadata or licenses.");

    // Write packages to out dir to be embedded.
    packages.write_package_list_to_out_dir().expect("Failed to write package list.");

    // Rerun only if one of the following files changed:
    println!("cargo::rerun-if-changed=build.rs");
    println!("cargo::rerun-if-changed=Cargo.lock");
    println!("cargo::rerun-if-changed=Cargo.toml");
}

For a more advanced example visit the build module documentation.

Adding Packages that are not Crates

Sometimes we have dependencies that are not crates. For these dependencies license-fetcher cannot automatically generate information. These dependencies can be added manually:

use std::fs::read_to_string;
use std::concat;

use license_fetcher::build::config::{ConfigBuilder, Config};
use license_fetcher::build::metadata::package_list;
use license_fetcher::{PackageList, Package, package};

fn main() {
    // Config with environment variables set by cargo, to fetch licenses at build time.
    let config: Config = ConfigBuilder::from_build_env()
        .build()
        .expect("Failed to build configuration.");

    // `packages` does not hold any licenses!
    let mut packages: PackageList = package_list(&config.metadata_config)
                                                .expect("Failed to fetch metadata.");

    packages.push(package! {
        name: "other dependency".to_owned(),
        version: "0.1.0".to_owned(),
        authors: vec!["Me".to_owned()],
        description: Some("A dependency that is not a rust crate.".to_owned()),
        homepage: None,
        repository: None,
        license_identifier: None,
        license_text: Some(
            read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/LICENSE"))
            .expect("Failed reading license of other dependency")
        )
    });

    // Write packages to out dir to be embedded.
    packages.write_package_list_to_out_dir().expect("Failed to write package list.");

    // Rerun only if one of the following files changed:
    println!("cargo::rerun-if-changed=build.rs");
    println!("cargo::rerun-if-changed=Cargo.lock");
    println!("cargo::rerun-if-changed=Cargo.toml");
}

Features

• serde enables the derivation of Serialize and Deserialize for Package and PackageList.

Modules

buildbuild

Functions for fetching metadata and licenses. This module holds functions to fetch metadata and licenses.

error

Wrapper around bincode and miniz_oxide errors during unpacking of a serialized and compressed PackageList.

Macros

package

Construct a Package.

read_package_list_from_out_dir

Embed and decode a PackageList, which you expect to be in $OUT_DIR/LICENSE-3RD-PARTY.bincode.deflate, via PackageList::from_encoded.

Structs

Package

Information regarding a crate / package.

PackageList

Holds information of all crates and licenses used for a release build.