记录CMake脚本

Question

我发现自己处于这样一种情况，希望能够准确记录一系列自定义的CMake宏和函数，并想知道如何做到这一点。

首先想到的是仅使用内置语法并仅记录脚本，如下所示：

# -----------------------------
# [FUNCTION_NAME | MACRO_NAME]
# -----------------------------
# ... description ...
# -----------------------------

这很好。然而，我想使用通用的文档生成器，比如doxygen，来生成外部文档，以便任何人都可以阅读，而无需查看实现（这是很常见的情况）。

一种方法是编写一个简单的解析器，直接从CMake脚本生成相应的C/C++头文件，并附带适当的签名和文档，然后可以使用doxygen或类似的工具进行处理。也可以通过手动维护这样的头文件，但显然这很繁琐且容易出错。

还有其他方法可以将文档生成器与CMake脚本一起使用吗？

- thokra

Answer 1

这是我能找到的最接近的内容。以下内容已经测试过，适用于CMake 2.8.10。目前，CMake 3.0正在开发中，它将获得一个基于Sphinx和reStructuredText的新文档系统。我猜这会带来新的方式来记录你的模块。

CMake 2.8可以从你的模块中提取文档，但只考虑文件开头的文档。所有文档都被添加为CMake注释，以单个#开头。双重##将被忽略（所以你可以在你的文档中添加注释）。文档的结尾由第一行非注释行标记（例如空行）

第一行给出了模块的简要描述。它必须以-开头，并以句点.或空行结束。

# - My first documented CMake module.
# description

或者 # - 我的第一个CMake模块文档 # # 描述

在HTML中，以两个或更多空格开头的行（在#之后）将使用等宽字体格式化。

示例：

# - My custom macros to do foo
#
# This module provides the macro foo().
# These macros serve to demonstrate the documentation capabilietes of CMake. 
#    
#    FOO( [FILENAME <file>]
#         [APPEND]
#         [VAR <variable_name>]
#    )
#
# The FOO() macro can be used to do foo or bar. If FILENAME is given, 
# it even writes baz. 

MACRO( FOO )
 ...
ENDMACRO()

要仅为您的自定义模块生成文档，请调用：

cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html

设置CMAKE_MODULE_PATH可以定义额外的目录以搜索模块。否则，您的模块需要在默认的CMake位置中。 --help-custom-modules将文档生成限制为自定义的、非CMake标准模块。如果您提供一个文件名，则文档将写入该文件，否则将写入stdout。如果文件名具有已识别的扩展名，则相应地格式化文档。

以下格式是可能的:

• .html用于HTML文档
• .1到.9用于man页
• .docbook用于Docbook
• 其他任何内容: 纯文本

- Johannes S.

---

--help-custom-modules 在 CMake 3 中不受支持。 - billx