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

Question

我有一些 C++ 代码库，用 doxygen 记录，并用 GNU make 构建。 版本信息集中在 makefile 中，我有类似的内容：

版本=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 配置文件中： （edit：doxygen 是从 makefile 中调用的，通过一个 'make-doc' 目标）

预定义 = APP_VERSION=$(VERSION)

但是，如果我在 doxygen \mainpage 命令中尝试这样的操作，它会失败，因为（当然）宏名称不会在 cmets 中扩展...

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

问题

• 您知道在 doxygen cmets 中“扩展”该宏的方法吗？这可以通过对 makefile 中包含注释的文件进行一些 sed 处理来完成，但也许这可以直接用 doxygen 解决？

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

相关：How to display a defined value

Answer 1

cmets 中的宏通常不会扩展（例如，请参阅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，但我从未这样做过，也不知道使用它在主页上包含版本信息有多容易。

Answer 2

你需要使用make的“导出”功能，即一个非常简单的make文件

project_name=FooBar
export project_name
all:
    doxygen Doxyfile

将允许您在 C++ 中使用以下 cmets

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

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

Answer 3

commands manual 建议 $(VARIABLE) 扩展环境变量。那么也许您可以将您的版本放入环境变量中？