Document how to use GetGitRevisionDescription "offline"

[alerque]

I am not a CMake expert; I'm far more accustomed to raw GNU Make. One of the idioms I usually bake into build systems is automatic version updating such that the version string is determined from git tags and updated on each commit. This works great for simplifying release workflows, and as long as everybody (including automated deployments, etc.) builds from git working trees it works great.

For more traditional software release paradigms where a source tarball is distributed, this is a little more complicated. Since people will not always be building from a git working tree but may be working from a source tarball, one has to include a fallback to determine the version number.

Using GNU Make based builds I know how to do this by bundling a version file with the latest string into the source, and falling back to reading it in the event git is not available. This way make dist or whatever will produce a tarball with an internal data file that can be read in lieu of git describe.

I am trying to contribute a similar workflow to a project that uses CMake. I've successfully included GetGitRevisionDescription from this repository and adapted the build to fetch the version string and define project() using it.

include(GetGitRevisionDescription)
git_describe(GIT_VERSION --tags --always)
string(REGEX REPLACE "-([0-9]*).*" ".\\1" VERSION "${GIT_VERSION}")
project (myproject
	VERSION "${VERSION}")

What I can't figure out is where and how I should cache this project data such that the project can also be build from source tarballs.

It would be nice to see the documentation comments for GetGitRevisionDescription include some notes on the best way to go about using it "offline".

[rpavlik]

Yeah, that would be a good thing. I'm not sure there's a single best way, especially since projects tend to use a git archive as their release tarball, which leaves little room to inject a version file. Probably best approach is to include a version file, but ignore it if you find out there's a git repo?

[alerque]

especially since projects tend to use a git archive as their release tarball

Not the same thing in my mind, the git archive output is useless as far as I'm concerned. It's neither a Git repo with any history or context nor a proper source release with prep work done. The only use cases I care about are actual Git repositories (with history & tags) and generated release tarballs which can include whatever generated resources are needed to make the build function without the repo history. An exact version string is part of that.

[alerque]

By the way the above linked project workflow does include one way of doing this for by stashing a file when building cmake source packages. This issue was before I worked out a way ... and I don't know if my solution is a very elegant one, CMake might have an easier way to go about it than what I did.