FindDoxygen

Doxygen 是一個文件產生工具（請參閱 https://doxygen.dev.org.tw）。這個模組會尋找 Doxygen 以及它支援的一些可選工具。

dot

Graphviz dot 工具程式用於呈現各種圖形。

mscgen

訊息圖表產生器 工具程式，由 Doxygen 的 \msc 和 \mscfile 命令使用。

dia

Dia 圖表編輯器，由 Doxygen 的 \diafile 命令使用。

在 3.9 版本中新增: 這些工具在 find_package() 命令中作為元件提供。例如

# Require dot, treat the other components as optional
find_package(Doxygen
             REQUIRED dot
             OPTIONAL_COMPONENTS mscgen dia)

此模組會定義以下變數

DOXYGEN_FOUND

如果找到 doxygen 可執行檔，則為 True。

DOXYGEN_VERSION

doxygen --version 報告的版本。

在 3.9 版本中新增: 此模組為 Doxygen 和找到的每個元件定義 IMPORTED 目標。這些可以用作自訂命令的一部分等等，並且應該優先於舊式（且現在已棄用）的變數，例如 DOXYGEN_EXECUTABLE。如果找到了它們對應的可執行檔，則會定義以下匯入目標（只有在請求了該元件時，才會定義元件匯入目標）

Doxygen::doxygen
Doxygen::dot
Doxygen::mscgen
Doxygen::dia

函式

doxygen_add_docs

在 3.9 版本中新增。

此函式旨在方便加入一個使用 Doxygen 產生文件的目標。它的目的是提供合理的預設值，以便專案通常只需提供輸入檔案和目錄，這就足以產生合理的結果。此函式支援自訂用於建構文件的 Doxygen 組態的功能。

doxygen_add_docs(targetName
    [filesOrDirs...]
    [ALL]
    [USE_STAMP_FILE]
    [WORKING_DIRECTORY dir]
    [COMMENT comment]
    [CONFIG_FILE filename])

此函式會建構一個 Doxyfile，並定義一個自訂目標，該目標會在此產生的檔案上執行 Doxygen。列出的檔案和目錄會用作產生的 Doxyfile 的 INPUT，並且它們可以包含萬用字元。明確列出的任何檔案也會新增為自訂目標的 SOURCES，以便它們會顯示在 IDE 專案的來源清單中。

為了使相對輸入路徑如預期般運作，預設情況下，Doxygen 命令的工作目錄將是目前的來源目錄（即 CMAKE_CURRENT_SOURCE_DIR）。可以使用 WORKING_DIRECTORY 選項來覆寫此項，以變更用作相對基準點的目錄。另請注意，Doxygen 的預設行為是從產生的文件中移除相對路徑的工作目錄（有關詳細資訊，請參閱 STRIP_FROM_PATH Doxygen 組態選項）。

如果提供，可選的 comment 會作為 add_custom_target() 命令的 COMMENT 傳遞，用於在內部建立自訂目標。

在 3.27 版本中新增: 如果設定 CONFIG_FILE，則會使用完整路徑提供的指定檔案作為 doxygen 組態檔。

在 3.12 版本中新增: 如果設定 ALL，則會將目標新增至預設建置目標。

在 3.16 版本中新增: 如果設定 USE_STAMP_FILE，則此函式定義的自訂命令會在每次重新執行 doxygen 時，在目前的二進位目錄中建立一個名稱為 <targetName>.stamp 的戳記檔。如果存在此選項，則 <filesOrDirs> 中的所有項目都必須是檔案（即沒有目錄、符號連結或萬用字元），並且在呼叫 doxygen_add_docs() 時，每個檔案都必須存在。如果列出的任何項目遺失或在給定 USE_STAMP_FILE 時不是檔案，則會引發錯誤。將會在每個檔案上建立一個相依性，以便只有在更新其中一個檔案時才會重新執行 doxygen。如果沒有 USE_STAMP_FILE 選項，如果建置 <targetName> 目標，則無論 <filesOrDirs> 中列出的任何內容是否已變更，都會一律重新執行 doxygen。

可以透過在呼叫 doxygen_add_docs() 之前設定 CMake 變數來自訂產生的 Doxyfile 的內容。任何名稱為 DOXYGEN_<tag> 的變數，其值都會取代為 Doxyfile 中的對應 <tag> 組態選項。如需支援的完整組態選項清單，請參閱 Doxygen 文件。

Doxygen 的某些預設值會被覆寫，以為 CMake 專案提供更適當的行為。除非在呼叫 doxygen_add_docs() 之前變數已具有值，否則以下每個設定都會明確設定（並附帶一些例外說明）

DOXYGEN_HAVE_DOT

如果要求 dot 元件並且已找到該元件，則設定為 YES，否則設定為 NO。任何現有的 DOXYGEN_HAVE_DOT 值都會被忽略。

DOXYGEN_DOT_MULTI_TARGETS

此模組會設定為 YES（請注意，這需要 1.8.10 以上版本的 dot）。只有在 DOXYGEN_HAVE_DOT 也設定為 YES 時，此選項才有意義。

DOXYGEN_GENERATE_LATEX

此模組設定為 NO。

DOXYGEN_WARN_FORMAT

對於以 Visual Studio 為基礎的產生器，這會設定為 Visual Studio IDE 可辨識的形式：$file($line) : $text。對於所有其他產生器，Doxygen 的預設值不會被覆寫。

DOXYGEN_PROJECT_NAME

以目前專案的名稱填入（即 PROJECT_NAME）。

DOXYGEN_PROJECT_NUMBER

以目前專案的版本填入（即 PROJECT_VERSION）。

DOXYGEN_PROJECT_BRIEF

以目前專案的描述填入（即 PROJECT_DESCRIPTION）。

DOXYGEN_INPUT

專案不應設定此變數。它會被填入傳遞給 doxygen_add_docs() 的檔案和目錄集合，從而提供與其他內建命令（例如 add_executable()、add_library() 和 add_custom_target()）一致的行為。如果專案設定了名為 DOXYGEN_INPUT 的變數，它將被忽略並發出警告。

DOXYGEN_RECURSIVE

此模組設定為 YES。

DOXYGEN_EXCLUDE_PATTERNS

如果輸入集合包含目錄，此變數將指定用於從中排除檔案的模式。doxygen_add_docs() 會加入以下模式，以確保不會將 CMake 特有的檔案和目錄包含在輸入中。如果專案設定了 DOXYGEN_EXCLUDE_PATTERNS，這些內容會與這些額外模式合併，而不是取代它們。

*/.git/*
*/.svn/*
*/.hg/*
*/CMakeFiles/*
*/_CPack_Packages/*
DartConfiguration.tcl
CMakeLists.txt
CMakeCache.txt

DOXYGEN_OUTPUT_DIRECTORY

此模組設定為 CMAKE_CURRENT_BINARY_DIR。請注意，如果專案為此提供了自己的值，且它是相對路徑，則它將被轉換為相對於目前二進位目錄的絕對路徑。這是必要的，因為 doxygen 通常會從來源樹中的目錄執行，以便相對來源路徑能夠如預期運作。如果此目錄不存在，則會在執行 doxygen 命令之前以遞迴方式建立它。

若要變更任何這些預設值或覆寫任何其他 Doxygen 設定選項，請在呼叫 doxygen_add_docs() 之前設定相關的變數。例如：

set(DOXYGEN_GENERATE_HTML NO)
set(DOXYGEN_GENERATE_MAN YES)

doxygen_add_docs(
    doxygen
    ${PROJECT_SOURCE_DIR}
    COMMENT "Generate man pages"
)

許多 Doxygen 設定選項接受值清單，但 Doxygen 要求它們以空白分隔。CMake 變數將清單作為字串保存，項目以分號分隔，因此需要進行轉換。doxygen_add_docs() 命令會特別檢查以下 Doxygen 設定選項，並將其關聯的 CMake 變數的內容轉換為要求的形式（如果已設定）。針對此處指定的 Doxygen 設定，CMake 變數會命名為 DOXYGEN_<name>。

ABBREVIATE_BRIEF
ALIASES
CITE_BIB_FILES
DIAFILE_DIRS
DOTFILE_DIRS
DOT_FONTPATH
ENABLED_SECTIONS
EXAMPLE_PATH
EXAMPLE_PATTERNS
EXCLUDE
EXCLUDE_PATTERNS
EXCLUDE_SYMBOLS
EXPAND_AS_DEFINED
EXTENSION_MAPPING
EXTRA_PACKAGES
EXTRA_SEARCH_MAPPINGS
FILE_PATTERNS
FILTER_PATTERNS
FILTER_SOURCE_PATTERNS
HTML_EXTRA_FILES
HTML_EXTRA_STYLESHEET
IGNORE_PREFIX
IMAGE_PATH
INCLUDE_FILE_PATTERNS
INCLUDE_PATH
INPUT
LATEX_EXTRA_FILES
LATEX_EXTRA_STYLESHEET
MATHJAX_EXTENSIONS
MSCFILE_DIRS
PLANTUML_INCLUDE_PATH
PREDEFINED
QHP_CUST_FILTER_ATTRS
QHP_SECT_FILTER_ATTRS
STRIP_FROM_INC_PATH
STRIP_FROM_PATH
TAGFILES
TCL_SUBST

如果以下單一值的 Doxygen 選項包含至少一個空格，則會自動加上引號。

CHM_FILE
DIA_PATH
DOCBOOK_OUTPUT
DOCSET_FEEDNAME
DOCSET_PUBLISHER_NAME
DOT_FONTNAME
DOT_PATH
EXTERNAL_SEARCH_ID
FILE_VERSION_FILTER
GENERATE_TAGFILE
HHC_LOCATION
HTML_FOOTER
HTML_HEADER
HTML_OUTPUT
HTML_STYLESHEET
INPUT_FILTER
LATEX_FOOTER
LATEX_HEADER
LATEX_OUTPUT
LAYOUT_FILE
MAN_OUTPUT
MAN_SUBDIR
MATHJAX_CODEFILE
MSCGEN_PATH
OUTPUT_DIRECTORY
PERL_PATH
PLANTUML_JAR_PATH
PROJECT_BRIEF
PROJECT_LOGO
PROJECT_NAME
QCH_FILE
QHG_LOCATION
QHP_CUST_FILTER_NAME
QHP_VIRTUAL_FOLDER
RTF_EXTENSIONS_FILE
RTF_OUTPUT
RTF_STYLESHEET_FILE
SEARCHDATA_FILE
USE_MDFILE_AS_MAINPAGE
WARN_FORMAT
WARN_LOGFILE
XML_OUTPUT

在 3.11 版本中新增：在某些情況下，可能不希望 doxygen_add_docs() 自動為特定設定選項加上引號，例如 ALIASES，它可能需要包含自己的嵌入式引號。DOXYGEN_VERBATIM_VARS 變數可用於指定不應加上引號的 Doxygen 變數清單（包含開頭的 DOXYGEN_ 前綴）。然後專案負責確保這些變數的值在直接放置在 Doxygen 輸入檔中時有意義。對於清單變數，清單項目仍然以空格分隔，只會跳過自動加上引號的動作。例如，以下範例允許 doxygen_add_docs() 將引號套用至 DOXYGEN_PROJECT_BRIEF，但不套用至 DOXYGEN_ALIASES 清單中的每個項目（括號語法 也可用於使處理嵌入式引號更容易）。

set(DOXYGEN_PROJECT_BRIEF "String with spaces")
set(DOXYGEN_ALIASES
    [[somealias="@some_command param"]]
    "anotherAlias=@foobar"
)
set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)

產生的 Doxyfile 將包含以下行：

PROJECT_BRIEF = "String with spaces"
ALIASES       = somealias="@some_command param" anotherAlias=@foobar

已棄用的結果變數

自 3.9 版本起已棄用。

為了與舊版本的 CMake 相容，還定義了以下變數，但它們已棄用，不應再使用。

DOXYGEN_EXECUTABLE

doxygen 命令的路徑。如果專案需要直接參考 doxygen 可執行檔，它們應該改用 Doxygen::doxygen 匯入目標。

DOXYGEN_DOT_FOUND

如果找到 dot 可執行檔，則為 True。

DOXYGEN_DOT_EXECUTABLE

dot 命令的路徑。如果專案需要直接參考 dot 可執行檔，它們應該改用 Doxygen::dot 匯入目標。

DOXYGEN_DOT_PATH

在 DOXYGEN_DOT_EXECUTABLE 中回報的包含 dot 可執行檔的目錄路徑。即使在 Windows 上，路徑也可能包含正斜線，不適合直接替換到 Doxyfile.in 範本中。如果您需要此值，請取得 Doxygen::dot 目標的 IMPORTED_LOCATION 屬性，並使用 get_filename_component() 來擷取該路徑的目錄部分。您也可以考慮使用 file(TO_NATIVE_PATH) 來準備 Doxygen 設定檔的路徑。

已棄用的提示變數

自 3.9 版本起已棄用。

DOXYGEN_SKIP_DOT

此變數對於 find_package 的組件形式無效。在回溯相容模式（即不使用組件清單）下，它會阻止搜尋器模組搜尋 Graphviz 的 dot 工具。