在doxygen注释中展开宏以打印出软件版本

时间:2012-05-21 21:35:04

标签: c++ makefile doxygen

我有一些C ++代码库,用doxygen记录,并使用GNU make构建。 版本信息集中在makefile中,我有类似的东西:

  

VERSION = 1.2.3.4

在我的makefile中,CFLAGS添加以下定义:

  

CFLAGS + = -DAPP_VERSION = $(VERSION)

这使我能够在代码中获取版本,如下所示:

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

现在,我希望在doxygen生成的html文件中有这个:

  

当前版本的软件是1.2.3.4

我设法将makefile变量导出到doxygen配置文件中: (编辑:从makefile调用doxygen,通过'make-doc'目标)

  

PREDEFINED = APP_VERSION = $(VERSION)

但是,如果我尝试使用doxygen \ mainpage这样的命令,它会失败,因为(当然),宏名称不会在评论中扩展...

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

问题

  • 您是否知道在doxygen评论中“扩展”该宏的方法?这可以通过对makefile中保存注释的文件进行一些sed处理来完成,但是这可以直接用doxygen解决吗?

  • 其他项目如何处理版本控制(除了VCS提供的自动版本控制工具,我的意思),以版本ID在文件中唯一定义的方式,因此它可以通过软件构建系统和文档构建系统。

相关:How to display a defined value

3 个答案:

答案 0 :(得分:3)

评论中的宏通常不会扩展(例如,请参阅this answer)。这不是doxygen独有的,我不能想到使用PREDEFINED配置选项来实现这一目的。

正如您在问题中所述,您可以使用sed,请参阅this answer中的第三个要点。例如,使用以下

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

将在所有源文件中用VERSION替换1.0的所有实例(您可以使用INPUT_FILTER指定要处理的文件,而不是处理所有源文件)。您可能不希望VERSION在任何地方展开,因此最好使用此标记$(VERSION)sed之类的内容。此外,您需要一种从makefile获取版本号并进入doxygen配置文件的方法。这可以使用另一个sed完成。

为解决您的上一个要点,doxygen具有FILE_VERSION_FILTER配置选项,用于确定每个文件的版本号。使用此选项将在每个文件页面的顶部打印一些版本信息(无论是从FILE_VERSION_FILTER中指定的命令打印出来的标准信息)。在文档中,有一些使用许多不同版本控制系统获取版本号的示例。此外,here是一个描述如何使用git和doxygen来提取版本信息的页面。

此配置选项的唯一缺点是我不知道如何指定文件版本信息在最终文档中的显示位置。我假设您可以使用布局文件:我认为您可以change the layout of pages,但我从未这样做过,也不知道使用它在主页上包含版本信息是多么容易。

答案 1 :(得分:2)

commands manual表明$(VARIABLE)扩展了环境变量。那么也许您可以将您的版本放在环境变量中?

答案 2 :(得分:2)

您需要使用make的“导出”功能,即使用

创建一个非常简单的make文件
project_name=FooBar
export project_name
all:
    doxygen Doxyfile

允许您在C ++中使用以下注释

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

我可以看到这成为具有大量出口的PITA,但这是一种相当简单的方法。或者,您可以从单独的BASH脚本运行doxygen,其中包含所有导出,以避免过多地污染Makefile。