记录 CMake 脚本答案

【问题标题】：Documenting CMake scripts记录 CMake 脚本
【发布时间】：2014-02-28 01:24:29
【问题描述】：

我发现自己想要准确地记录大量自定义 CMake 宏和函数，并且想知道如何去做。

首先想到的是简单地使用内置语法并且只使用文档脚本，如下所示：

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

这很好。但是，我想使用通用文档生成器（例如 doxygen）来生成外部文档，任何人都可以阅读这些文档，而无需查看实现（这是一种常见的场景）。

一种方法是编写一个简单的解析器，该解析器直接从 CMake 脚本生成具有适当签名和文档的相应 C/C++ 标头，可以通过 doxygen 或类似工具进行处理。也可以手动维护这样的标题 - 这显然是乏味且容易出错的。

还有其他方法可以使用带有 CMake 脚本的文档生成器吗？

【问题讨论】：

标签： cmake

【解决方案1】：

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

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

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

# - 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 标准模块。如果您提供文件名，则文档将写入文件，否则将写入标准输出。如果文件名具有可识别的扩展名，则相应地格式化文档。

以下格式是可能的：

.html 用于 HTML 文档
.1 到 .9 的手册页
.docbook 用于文档手册
其他：纯文本

【讨论】：

--help-custom-modules 不支持 CMake 3。