Geek Answers Handbook

Expand the macro inside the doxygen comment to print the software version

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

version = 1.2.3.4

In my CFLAGS makefile, add the following definition:

CFLAGS + = -DAPP_VERSION = $ (VERSION)

This allows me to get the version in code, for example:

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

Now I would like to get this in the html files created by doxygen:

The current software version is 1.2.3.4

I managed to export the makefile variable to the doxygen configuration file, where: ( edit : doxygen is called from the make file via the "make-doc" target)

PREDEFINED = APP_VERSION = $ (VERSION)

But then if I try something like this in the doxygen \ mainpage command, it fails because (of course) the macro names do not expand in the comments ...

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

Questions

  • Do you know a way to "expand" this macro in doxygen comments? This can be done with some sed processing in the file containing the comment in the make file, but maybe this can be solved directly with doxygen?

  • How other projects handle version control (in addition to the automatic version control tool that VCS provides, I mean), so that the version identifier is uniquely defined in the file, so it can be obtained both using the software build system and using documentation assembly system.

Related: How to display a specific value

+7
source share
3 answers

You need to use the "export" make function, i.e. very simple make file with

 project_name=FooBar export project_name all: doxygen Doxyfile

Lets use the following comments in C ++

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

I see that this is becoming a PITA with a large set of exports, but it is a pretty simple way to do this. Alternatively, you can run doxygen from a separate BASH script with all exported to it, to avoid too much pollution of your Makefile.

+2
source

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

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

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

replaces all VERSION instances with 1.0 in all of your source files (you can specify which files to process with INPUT_FILTER , rather than process all source files). You may not want VERSION expand everywhere, so it might be better to use something like $(VERSION) and sed this token. In addition, you will need a way to get your version number from your makefile and into the doxygen configuration file. This can be done using another sed .

To access your last marker point, doxygen has a FILE_VERSION_FILTER configuration FILE_VERSION_FILTER to determine the version number of each file. Using this, you will print some version information (regardless of what is printed standardly from the command specified in FILE_VERSION_FILTER ) at the top of each page of the file. The documentation provides examples of obtaining a version number using a number of different version control systems. Also here is a page describing the use of git and doxygen to extract version information.

The only drawback of this configuration option is that I do not know how to specify where the version information of the file should be displayed in the final documentation. I suppose you can use a layout file: I suppose you can change the layout of the pages , but I never did, and I don't know how easy it would be to use this to include version information on the main page.

+3
source

More articles:


All Articles