Doxygen: Outputting Version Numbers

Question

I would like to have Doxygen display the source code version number as part of the main page or the title header.

Presently, our code has the version defined as a text literal:

/*!
 *  \brief  Text literal containing the build number portion of the
 *              ESG Application Version.
 */
static const char   build_version_text[] = "105";

I have searched the internet for a method to get the 105 from the above statement into the Doxygen main page (or header) with no luck.

Background
We have a build server that updates the text string as part of a nightly build operation. The file is updated, then checked into the Software Configuration Management system. The build server is also capable of generating the documentation. We would also like to have the developers be able to check out the code, the build the Doxygen documentation at their workstations.

We are using Doxygen version 1.8.11.

Might be related: http://stackoverflow.com/questions/10692970/ — kebs, Sep 20 '16 at 20:22
I read that, but I was hoping for a solution that doesn't involve environment variables. — Thomas Matthews, Sep 20 '16 at 20:45
@ThomasMatthews, please check my revised answer. There are no environment variables, the script is driven by doxygen itself, so should be ok to use both in the automated build and by a developer at his/her workstation. — Marc Alff, Sep 23 '16 at 09:44

Artur Kink · Accepted Answer · 2016-09-19T22:59:28.393

What you're looking for is to set the PROJECT_NUMBER config option based on the value in your source. I don't think this can be done, but the way I would go about achieving the same result is as follows.

Since the project version is updated when a build script runs, have the build script generate an extra file, for example Doxyversion. Have the content of the file be:

PROJECT_NUMBER = "<versiontext>"

Update your main Doxyfile and replace

PROJECT_NUMBER =

with

@INCLUDE = "<pathToDoxyversion>"

Edit:

A solution I can think of that does not require duplicating the version string requires parsing the version string out from the file into an environment variable. Then you can set PROJECT_NUMBER to

PROJECT_NUMBER=$(ENV_VAR)

Another option is you can call doxygen with

( cat Doxyfile ; echo "PROJECT_NUMBER=$ENV_VAR" ) | doxygen

Both solutions would require the developers to know to do this when generating the documentation, or wrapping the entire doxygen call in a script. Also potential portability issues.

I don't see the need for the extra file. We can write a build script that can insert (replace) text for the PROJECT_NUMBER option. I'm hoping for a solution with only one instance of the version string. — Thomas Matthews, Sep 19 '16 at 22:04
Fair Enough, I added a way I can think of accomplishing that, but I find it to be worse than the duplicate value heh. — Artur Kink, Sep 19 '16 at 23:03

Marc Alff · Answer 2 · 2016-09-23T09:40:21.020

Full solution below, from a real example.

Main page

In the documentation for the main page (or anywhere, really), use special markers for the text to substitute dynamically.

Main page source: https://github.com/mysql/mysql-server/blob/8.0/sql/mysqld.cc#L22

See the special ${DOXYGEN_GENERATION_DATE} markers

Doxygen input filters

In the doxygen configuration file, define an input filter for the file containing the special markers. For example,

FILTER_PATTERNS = "*/sql/mysqld.cc=./doxygen-filter-mysqld"

Implement the doxygen-filter-mysqld script to:

Find the dynamic value to substitute (in your case, parse the value of build_version_text)
Replace (sed) the special marker with the value
Output the result to stdout

For example:

CMD1="s/\\\${DOXYGEN_GENERATION_DATE}/"`date -I`"/g"
...
sed -e ${CMD1} -e ${CMD2} -e ${CMD3} $1

Results

Result is at http://devdocs.no.oracle.com/mysql-server/8.0.0/

Doxygen: Outputting Version Numbers

2 Answers2

Main page

Doxygen input filters

Results

See Also