Julius: Fine-tune printing git commit hash

[bvschaik]

Printing the git commit hash on startup can use some fine-tuning (and explanation). For me it says right now:
INFO: Built with git commit: v1.0.0-22-g258ae61f30-dirty
Where does the "v1.0.0-22-g" come from?
What about the dirty flag? Is that always set because the build process creates files in the working directory? (need to check AppVeyor/Travis build scripts)
What does it print for release versions?

Originally proposed change by @jdmillard:

---

I pulled master after this was merged. My console displays:

INFO: Built with git commit:

My "clean build process" on Windows is:

cd build
cmake.exe .. -G "MinGW Makefiles"
mingw32-make.exe -j8
julius.exe "path\to\GOG Games\Caesar 3"

...

OKAY, I took a closer look and this. This feature depends on cmake executing a git command which breaks for the following git setup: If "Git for Windows" is used to clone, then generic CMD is used to compile. Building this way might sound strange, but there are real reasons for some people to build this way on Windows machines (too hard to explain here).

I suggest to leave the new CMake logic as-is. However, if no commit hash string was set during CMakeLists.txt, the INFO print statement should be avoided altogether. Your thoughts?

Here's my horrible pseudo code suggestion:

if (GIT_COMMIT_STRING_WAS_SET_BY_CMAKE)
{
    print_stuff_about_the_commit();
}

_Originally posted by @jdmillard in https://github.com/bvschaik/julius/pull/52#issuecomment-459549167_

[siredmar]

To explain what the string itself is:
v1.0.0-22-g258ae61f30-dirty -> a-b-c[-d]
a: latest git tag (e.g. v1.0.0)
b: commits above latest tag (22)
c: commit hash (10 digits) referencing the current build (e.g. g258ae61f30)
d: if the local working tree has modifications based on the hash seen in c (e.g. g258ae61f30) there will be a dirty flag set. This flag is optional as it won't be printed if the working tree is exactly the git commit without modifications

But where does that come from?
It is generated by the git describe command in the CMakeLists.txt. This string is then handled over to the version.h.in file which will generates the platform/version.h containing a string which can be printed out in the program.

On the git with windows build issue:
As long as you have git installed, cloned the repo, built it cmake within a mingw environment there should be no problem at all. I don't work with windows, but can't image that this should be a big problem, right?
But if you get the source by zip without any containing .git folders this cmake routine won't work at all because the git command can't run successfully.

I don't know how the game is compiled in windows right now. I saw some pull requests regarding Visual Studio. Does VS build the source with cmake?

[jdmillard]

@siredmar, i issue is if you compile with a console that cannot see git, from its perspective git isn't installed, so CMake saves an empty string.

The feature is excellent, but just needed a simple failsafe.

[siredmar]

Don't get me wrong. Fallbacks are important and the are valuable - if they are necessary.
In this particular case you would fix not a bug in the code but an unproper setup build environment. And thats surely not the way you want to go.

So to build the software you already have to meet requirements like:

• linux,mac,mingw,...?
• cmake
• SDL
• gcc

Having setup git correctly would be just another requirement to build the software.
One can't expect to have a fully functional software without the proper requirements met.

[crudelios]

@siredmar the problem is you are requesting a dependency that wasn't there before.

Because Windows is Windows, git probably isn't set to the path unless a specific git console is used, so the command fails. Also, people may not even have git and instead of cloning the repo, they download the zip file.

I think something like: INFO: Built with git commit: unknown (please install git and/or add it to PATH to get build information) would be fine.

[jdmillard]

"Having set up git correctly". That isn't the issue here. Y'all feel free to leave it as-is, I'm trying to offer friendly advice which you are perfectly free to ignore.

CMake shouldn't depend on git and git shouldn't depend on CMake. Having the build routine detect the commit is fantastic, but don't expect the console that calls CMake to be the same one that called git. Consider all different Windows console options: CMD, PowerShell, Linux Subsystem for Windows, Putty, "Git for Windows", MSYS2, MobaXterm. And all those options don't even consider the git GUI applications out there - which I stay away from. When configuring these terminals, git, and/or GUI applications, there is an endless number of combinations.

EDIT: the suggestion to add to PATH is fine, but making it a build requirement is probably not best-practice.

[crudelios]

@jdmillard but it can still be built without git, right? I have no access to my PC, hence the question.

[jdmillard]

Yep. Displaying the version is just broken, everything else works fine. .. which is why really it's a small nitpick.

[jdmillard]

I've seen projects where the version.h is committed to repo and maintained as new release/minor/patch versions are bumped. I'm not saying it has to be done this way, but the log message could display VERSION + commit hash (if the commit hash was successfully detected by CMake).

[siredmar]

@siredmar the problem is you are requesting a dependency that wasn't there before.

Because Windows is Windows, git probably isn't set to the path unless a specific git console is used, so the command fails. Also, people may not even have git and instead of cloning the repo, they download the zip file.

I think something like: INFO: Built with git commit: unknown (please install git and/or add it to PATH to get build information) would be fine.

That scenario sounds reasonable. Like i already said i had no clue how this thing was built in Windows.
But still the fact that people can get the source as a zip file (without any git information) is worth the implementation you suggested.

[siredmar]

I've seen projects where the version.h is committed to repo and maintained as new release/minor/patch versions are bumped. I'm not saying it has to be done this way, but the log message could display VERSION + commit hash (if the commit hash was successfully detected by CMake).

The nice thing about the generated version information is that one does not have to maintain a version number over several places manually and keep them synced (e.g. version.h, git tags, ...)

[jdmillard]

I've seen projects where the version.h is committed to repo and maintained as new release/minor/patch versions are bumped. I'm not saying it has to be done this way, but the log message could display VERSION + commit hash (if the commit hash was successfully detected by CMake).

The nice thing about the generated version information is that one does not have to maintain a version number over several places manually and keep them synced (e.g. version.h, git tags, ...)

Fair enough. It tends to come in handy on libraries where dependent projects need to enforce a specific version via CMake... which is not the case here. So far we have 1 version though. Regardless, this will come down to a decision to be made by @bvschaik .

[siredmar]

I am creating a pull request with the suggestions made here:

1. If cmake put a meaningful information in version.h, it will be used
2. If cmake didn't (e.g. git isn't installed, source as zip,...) the string proposed by @crudelios is provided

[siredmar]

Please see #82

[jdmillard]

One thing to keep in mind, if the downloaded zip is going to drive a design decision, consider that the downloaded zip does not contain a .git folder. I don't think this is a big deal honestly. I'm just throwing it out there.

[crudelios]

That's true, but I think it might become too verbose of an error message...