How can a Rust program access metadata from its Cargo package?

Question

How do you access a Cargo package's metadata (e.g. version) from the Rust code in the package? In my case, I am building a command line tool that I'd like to have a standard --version flag, and I'd like the implementation to read the version of the package from Cargo.toml so I don't have to maintain it in two places. I can imagine there are other reasons someone might want to access Cargo metadata from the program as well.

Pontificate

Answer 1

Cargo passes some metadata to the compiler through environment variables, a list of which can be found in the Cargo documentation pages.

The compiler environment is populated by fill_env in Cargo's code. This code has become more complex since earlier versions, and the entire list of variables is no longer obvious from it because it can be dynamic. However, at least the following variables are set there (from the list in the docs):

CARGO_MANIFEST_DIR
CARGO_PKG_AUTHORS
CARGO_PKG_DESCRIPTION
CARGO_PKG_HOMEPAGE
CARGO_PKG_NAME
CARGO_PKG_REPOSITORY
CARGO_PKG_VERSION
CARGO_PKG_VERSION_MAJOR
CARGO_PKG_VERSION_MINOR
CARGO_PKG_VERSION_PATCH
CARGO_PKG_VERSION_PRE

You can access environment variables using the env!() macro. To insert the version number of your program you can do this:

const VERSION: &str = env!("CARGO_PKG_VERSION");

// ...

println!("MyProgram v{}", VERSION);

If you want your program to compile even without Cargo, you can use option_env!():

const VERSION: Option<&str> = option_env!("CARGO_PKG_VERSION");

// ...

println!("MyProgram v{}", VERSION.unwrap_or("unknown"));

Leblanc

Is this runtime or compile time? – Jaguarundi

@Jaguarundi compile time, as stated in the documentation – Satiate

Just to say to searchers, since this is a compile-time solution and uses environment variables, this will not resolve to subcrate's metadata for workspace members. – Applicant

Answer 2

The built-crate helps with serializing a lot of Cargo's environment without all the boilerplate.

Nadean

built also adds the git sha-1 (and lots of other useful things) – Triaxial

Answer 3

At build-time (as in build.rs), cargo_metadata may be useful. For example:

let path = std::env::var("CARGO_MANIFEST_DIR").unwrap();
let meta = MetadataCommand::new()
    .manifest_path("./Cargo.toml")
    .current_dir(&path)
    .exec()
    .unwrap();

let root = meta.root_package().unwrap();
let option = root.metadata["my"]["option"].as_str().unwrap();
let version = &root.version;
...

Typesetter

Answer 4

Other more recent alternatives:

// ...
let version = env!("CARGO_PKG_VERSION");
let name = env!("CARGO_PKG_NAME");
let author = env!("CARGO_PKG_AUTHORS");

println!("Program Name: {}", name);
println!("Program Version: {}", version);
println!("Program Autor: {}", author);

Triiodomethane

Answer 5

I know this question is old but in case anyone else lands here the clap crate is what I would recommend if you are writing a CLI application as it is fairly standard in the community now. Out of the box it will give you version with -V or --version. It will also give you help, make your argument handling easier and consistent with other applications which helps with user expectations.

Allnight