記錄CMake腳本

Question

我發現自己處於一種情況，我想準確記錄一系列定製的CMake宏和函數，並想知道如何去做。

想到的是簡單地使用內置的語法和唯一文件腳本，像這樣的第一件事：

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

這是好的。但是，我想使用通用文檔生成器，例如doxygen，以生成外部文檔，任何人都可以閱讀而不需要查看實現（這是常見的場景）。

一種方法是編寫一個簡單的解析器，該解析器可以直接從CMake腳本生成相應的C/C++頭文件，並直接從CMake腳本生成相應的簽名和文檔，可以通過doxygen或類似的工具進行處理。人們也可以手工維護這樣的標題 - 這顯然是單調乏味且容易出錯的。

是否有任何其他方式使用CMake腳本的文檔生成器？

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標準模塊。如果你提供一個文件名，文檔就會寫入文件，否則就是標準輸出。如果文件名具有可識別的擴展名，則文檔將相應地進行格式化。

以下格式是可能的：

• .html爲HTML文檔
• .1到.9的手冊頁
• .docbook一些DocBook
• 別的：純文本