Expand macro inside doxygen comment for printing out software version

Question

I have some C++ code base, documented with doxygen, and build with GNU make. Version information is centralized in makefile, where I have something like:

VERSION=1.2.3.4

In my makefile, the CFLAGS add the following define:

CFLAGS += -DAPP_VERSION=$(VERSION)

This enables me to get the version in code, like this:

#define STR_EXPAND(tok) #tok
#define STR(tok) STR_EXPAND(tok)
int main()
{
    cout << "software version is << STR(APP_VERSION) << endl;
}

Now, what I would like is to have this in the doxygen-produced html files:

Current version of software is 1.2.3.4

I managed to export the makefile variable into the doxygen configuration file with: (edit: doxygen is called from makefile, through a 'make-doc' target)

PREDEFINED = APP_VERSION=$(VERSION)

But then, if I try in the doxygen \mainpage command something like this, it fails, because (of course), macro names don't get expanded in comments...

/**
\mainpage this is the doc
Current version is $(APP_VERSION) -- or -- ... is APP_VERSION
*/

Questions

• Do you know of a way to "expand" that macro in the doxygen comments ? This could be done by some sed processing on the file holding the comment in the makefile, but maybe this can be solved directly with doxygen ?

• How do other projects handle versioning (besides automatic versioning tool that VCS provide, I mean), in a way that the version id is uniquely defined in a file, so it can be fetched both by software build system and documentation build system.

Related: How to display a defined value

Answer 1

Macros in comments are not generally expanded (see, for example, this answer). This is not unique to doxygen and I can 't think of a way to do this using the PREDEFINED configuration option.

As you state in the question, you can use sed, see the third bullet point in this answer. For example, using the following

INPUT_FILTER  = "sed -e 's/VERSION/1.0/'"

will replace all instances of VERSION with 1.0 in all your source files (you can specify which files to process with INPUT_FILTER, rather than processing all source files). You might not want VERSION to be expanded everywhere, so perhaps it is best to use something like $(VERSION) and sed this token. Also, you will need a way of getting your version number from your makefile and into your doxygen configuration file. This can be done with another sed.

To address your last bullet point, doxygen has the FILE_VERSION_FILTER configuration option for determining the version number of each file. Using this will print some version information (whatever is printed to standard out from the command specified in FILE_VERSION_FILTER) at the top of each file page. In the documentation there are examples of getting the version number using a number of different version control systems. Also, here is a page describing how to use git and doxygen to extract version information.

The only drawback with this configuration option is that I don't know how to specify where the file version information should appear in the final documentation. I presume you can use a layout file: I presume you can change the layout of pages, but I have never done this and don't know how easy it would be to use this to include version information on the mainpage.

Answer 2

the commands manual suggests that $(VARIABLE) expands environment variables. So maybe you can put your version in an environment variable?

Answer 3

You need to use the "export" functionality of make ie a very simple make file with

project_name=FooBar
export project_name
all:
    doxygen Doxyfile

Will allow you to use the following comments in C++

/*! \mainpage Project $(project_name) Lorem ipsum dolor

I can see this becoming a PITA with a large set of exports but it's a fairly simple way to do it. Alternatively you could run doxygen from a separate BASH script with all the exports in it to avoid polluting your Makefile too much.