# README

[![Docs](https://docs.rs/vcs_version/badge.svg)](https://docs.rs/vcs_version/)

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`:

```rust
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`:

```rust
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.