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

Question

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

c++makefiledoxygen

8

我有一些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配置文件中，方法如下：（编辑：doxygen是通过'make-doc'目标从makefile调用的）

PREDEFINED = APP_VERSION=$(VERSION)

但是，如果我尝试在doxygen \mainpage命令中添加类似于这样的内容，它会失败，因为（当然），宏名称不会在注释中扩展...

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

问题

你知道一种方法能够在doxygen注释中“扩展”宏吗？这可能可以通过对makefile中保存注释的文件进行一些sed处理来完成，但也许可以直接通过doxygen解决？
除了自动版本控制系统提供的版本控制工具之外，其他项目如何处理版本控制，以使版本ID在文件中得到唯一定义，以便软件构建系统和文档构建系统都能获取？

相关：如何显示定义值

- kebs

3个回答

2

您需要使用“导出”功能，使一个非常简单的make文件具有以下特点：

project_name=FooBar
export project_name
all:
    doxygen Doxyfile

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

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

我可以看到在大量导出时这可能会变得很麻烦，但这是一个相当简单的方法。或者，您可以从独立的BASH脚本中运行doxygen并将所有导出项放入其中，以避免过多污染Makefile。

- Harry

我刚回到这个问题，意识到（有点晚了...）这正是我正在寻找的！我不知道为什么当时没有注意到它。接受答案。 - kebs

2

命令手册建议使用$(VARIABLE)来扩展环境变量。因此，您可以将您的版本放在环境变量中吗？

- shoosh

当然可以，但问题是：我该如何在doxygen生成的文件中打印出它的值呢？或者也许我对你的回答有误解，请你澄清一下好吗？ - kebs

在Windows上使用Doxygen 1.8.6对我有效。在批处理文件中：set DOC_VERSION=1.0在MyPage.dox中：版本：$(DOC_VERSION) - Anthony Hayward

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Chris · Accepted Answer

评论中的宏通常不会被展开（例如，参见此答案）。这不是doxygen特有的问题，我无法想到使用PREDEFINED配置选项来解决这个问题。

正如您在问题中所述，您可以使用sed，参见此答案中的第三个要点。例如，使用以下命令：

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指定的命令中输出到标准输出的任何内容）。文档中提供了使用多种不同版本控制系统获取版本号的示例。此外，这里是一篇描述如何使用git和doxygen提取版本信息的页面。

此配置选项唯一的缺点是我不知道如何指定文件版本信息应出现在最终文档中的位置。我认为您可以使用布局文件：更改页面布局，但我从未这样做过，也不知道如何轻松地将版本信息包含在主页上。