README

Helper functions that can be used from build.rs to extract a version number from Git or Mercurial tags.

Version numbers mostly follow the Python PEP440 conventions. If the current folder corresponds to a version tag, then return that tag. Otherwise, identify the closest tag and return a string of the form tag.dev_N_+hash where N is the number of revisions between the tagged and current revisions. In both cases, if the current folder has been modified, then add the current date as YYYYMMDD to the local version label.

If the current folder isn't a Git or Mercurial checkout, this will try to get the tag, distance and hash from a .hg_archival.txt file as generated by hg archive, then fallback to the version defined in Cargo.toml. Since there is no way to check if the code has been modified, vcs_version will always add a date suffix to the version from .hg_archival.txt or Cargo.toml.

Example usage

Put this in your build.rs:

use std::env;
use std::fs::File;
use std::io::Write;
use std::path::Path;

fn main()
{
   let out_dir = env::var ("OUT_DIR").unwrap();
   let mut f = File::create (Path::new (&out_dir).join ("build_info.rs")).unwrap();
   let version = vcs_version::get_version();
   writeln!(f, "pub const PKG_NAME: &'static str = \"{} {} {}\";",
            env::var ("CARGO_PKG_NAME").unwrap(),
            version,
            env::var ("PROFILE").unwrap_or ("".into()))
      .unwrap();
   writeln!(f, "pub const PKG_VERSION: &'static str = \"{}\";",
            version)
      .unwrap();
}

Then in your main.rs or lib.rs:

include!(concat!(env!("OUT_DIR"), "/build_info.rs"));

This will define two public string constants:

• PKG_NAME contains the full package name, including the version number,
• PKG_VERSION contains only the version.