git-tags-semver
Tool to extract SemVer Version Information from annotated git tags This package allows to extract SemVer version information from annotated git tags in the format "vX.Y.Z". It is used from build.rs build scripts. For usage details, see the API documentation.
This crate is made to call and parse the git describe command. It is assumed that the repo uses
annotated git tags in the format "vX.Y.Z" or "vX.Y.Z-rc". So for example, the first commit of
the release candidate branch for 1.0.0 should be tagged with "v1.0.0-rc" and the actual 1.0.0
release should be tagged with "v1.0.0". This information has to be extracted at compile time so
it needs to be done in a build.rs
. Since the build.rs
is run in the directory of the crate
it belongs to, your project itself should contain that build.rs
, i.e. it should not be done
in a git submodule or a dependency of your project. The following build.rs
will write the
version information to version.rs
in the current OUT_DIR
directory which is
"the folder in which all output and intermediate artifacts should be placed"
by build scripts:
use env;
use fs;
use Path;
use Command;
Afterwards, <OUT_DIR>/version.rs
contains a pub const
GitVersion<'static>
.
Specifically, that file looks like:
pub const VERSION: GitVersion = GitVersion ;
To use it in your application, you can include the generated code like that:
include!;
Cargo.toml / Feature-Gates
This tool is especially designed to be used in no_std
contexts, e.g. bare-metal firmwares.
Therefore, it is generally no_std
(the type definitions) but for extracting and writing the
version information to an intermediate file, it needs the standard library (and build.rs
is
run with std
, even for no_std
packages). Thus, the standard library usage which enables the
part required in the build.rs
has to be enabled with the "build" feature. So, for a no_std
package, you need to add it as a dependency twice, the corresponding part in your Cargo.toml
could look like this:
[]
= { = "1.0.0" }
[]
= { = "1.0.0", = ["build"] }
Note that this additionally requires to use
feature resolver version 2
for your project which is
the default since Rust's 2021 edition
or can be specified with resolver = "2"
in your Cargo.toml
(if using a workspace, this must
be done in the top-level/workspace Cargo.toml
).
License
Open Logistics Foundation License
Version 1.3, January 2023
See the LICENSE file in the top-level directory.
Contact
Fraunhofer IML Embedded Rust Group - embedded-rust@iml.fraunhofer.de