Doxygen：输出版本号

Question

我希望Doxygen能在主页或标题头中展示源码版本号。目前，我们的代码把版本定义为文本字面量：

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

我在互联网上搜索了如何将上述语句中的105添加到Doxygen主页（或标题）的方法，但没有找到合适的方法。

背景： 我们有一个构建服务器，它会在每晚的构建操作中更新文本字符串。文件被更新后，会被检入软件配置管理系统。构建服务器还能够生成文档。我们也希望开发人员能够从代码库中检出代码，在他们的工作站上构建Doxygen文档。

我们正在使用Doxygen版本1.8.11。

- Thomas Matthews

---

可能相关：https://dev59.com/GmTVa4cB1Zd3GeqP_xgo - kebs

我看过那个，但我希望有一个不涉及环境变量的解决方案。 - Thomas Matthews

@ThomasMatthews，请检查我的修订答案。没有环境变量，脚本由doxygen本身驱动，因此应该可以在自动化构建和开发人员的工作站上使用。 - Marc Alff

Answer 1

你需要做的是根据源代码中的值设置PROJECT_NUMBER配置选项。我认为这是不可能实现的，但我会采用以下方法来达到同样的效果。

由于项目版本在构建脚本运行时更新，请让构建脚本生成一个额外的文件，例如Doxyversion。该文件的内容应为：

PROJECT_NUMBER = "<versiontext>"

请更新您的主Doxyfile并替换

PROJECT_NUMBER =

使用

@INCLUDE = "<pathToDoxyversion>"

编辑：

我能想到的一个解决方案不需要复制版本字符串，而是需要从文件中解析版本字符串到环境变量中。然后，您可以将PROJECT_NUMBER设置为

PROJECT_NUMBER=$(ENV_VAR)

另一个选择是您可以使用以下方式调用doxygen

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

这两种解决方案都需要开发人员在生成文档时知道如何实现此功能，或者将整个doxygen调用包装在脚本中。还可能存在可移植性问题。

- Artur Kink

---

我不认为需要额外的文件。我们可以编写一个构建脚本，可以插入（替换）PROJECT_NUMBER选项的文本。我希望只有一个版本字符串的解决方案。 - Thomas Matthews

好的，我增加了一种我能想到的实现方式，但我发现它比重复值更糟糕。 - Artur Kink

Answer 2

以下是一个真实示例的完整解决方案。

主页

在主页（或任何地方）的文档中，使用特殊标记来动态替换文本。

主页源代码： https://github.com/mysql/mysql-server/blob/8.0/sql/mysqld.cc#L22

请参见特殊的${DOXYGEN_GENERATION_DATE}标记。

Doxygen输入过滤器

在Doxygen配置文件中，为包含特殊标记的文件定义一个输入过滤器。例如：

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

实现doxygen-filter-mysqld脚本以：

• 查找要替换的动态值（在您的情况下，解析build_version_text的值）
• 使用sed将特殊标记替换为该值
• 将结果输出到stdout

例如：

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

结果

结果在http://devdocs.no.oracle.com/mysql-server/8.0.0/。

参见

所有这些都是为了解决我认为应该成为Doxygen功能的问题。请参阅已针对此问题输入的bug＃769679（功能请求：扩展环境变量的doxygen命令）。

https://bugzilla.gnome.org/show_bug.cgi?id=769679

- Marc Alff