correct way to encode/embed version number in program code

Question

I would like to embed my software version in my code and later retrieve it from the program binary with a command like argument like -v or --version. As an example some of the GNU/Linux software binaries print their version information when supplied with a -v or -V argument in the command line take ls as an example:

$ ls --version
ls (GNU coreutils) 8.13
Copyright (C) 2011 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Is there a convention or standard do this? I tried to search for this information but since I didn't know the right terminology my search only resulted in version control howto's. The software code is written in C++ language if it helps to address the problem better.

Solution 1

Normally, for major and minor version numbers (as in, 1.2, 1 is major and 2 is minor), they are most often written in the code directly, usually as a #define (because you might need them for conditional compilations, i.e., #if blocks).

You would typically have a separate header that contains only those defines and nothing else (except the header-guard), to minimize dependencies.

Some people use the build system (like cmake) to pull a version number from the version control (git, svn, cvs, etc..) and then put that version number into their "version" header. Or, they put the version number into the build system configuration files and then put that onto the header, as shown on the cmake tutorial. Personally, I don't like this approach because it tends to modify your header files too often and cause frequent and pointless recompilations.

I prefer writing the version number in the header file, and then pulling out those version numbers (major, minor, ..) from the header onto the build system. This is another thing that cmake can very easily do.

If you want to embed a very day-by-day version number into your software, such as a build number or revision number, then you should not put it as a #define in a header file, but rather as a extern const variable that you define in one cpp file. For example, you can use cmake to pull a revision number from your version control system, tack that onto the cpp file that defines this extern const int revision; variable (through cmake's configure_file function), and link your programs with that cpp / object file. This way, the revision number is built into your programs automatically at every re-build, and it won't trigger full recompilations every time it's updated (which is at every commit).

The point is that major and minor version numbers are not changed frequently enough to require any kind of automatic maintenance, but you need to manually write them in one place only, and automatically propagate it everywhere else where it might be relevant (I would recommend that this place be the header file itself). It's only the revision or build numbers that need to be fully automated (generated by the version control, and propagated everywhere else automatically).

Solution 2

I believe it is customary to keep the version number in a dedicated header file. Some tools can automatically generate this for you.

For example, see section "Adding a Version Number and Configured Header File" in CMake Tutorial.

Comments

[Mohan]

"I prefer writing the version number in the header file, and then pulling out those version numbers from the header onto the build system." Any chance you could expand on how you had CMake do this?

[rien333]

This option is great, but I wonder if there is a way to do this without CMake overwriting any files.

[Kevin]

@Mohan Something like the answer discussed here would work to have CMake extract the build info from a header file.