FindDoxygen

Doxygen 是一個文件產生工具 (請參閱 https://doxygen.dev.org.tw)。此模組尋找 Doxygen 以及它支援的一些選用工具

dot

Graphviz dot 公用程式，用於渲染各種圖形。

mscgen

Message Chart Generator 公用程式，由 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 選項，則無論 <filesOrDirs> 中列出的任何內容是否已變更，只要建置 <targetName> 目標，就會始終重新執行 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 變數，則會將其內容轉換為所需的格式。CMake 變數的名稱為 DOXYGEN_<name>，用於此處指定的 Doxygen 設定。

  • 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

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

已棄用的提示變數

自版本 3.9 起已棄用。

DOXYGEN_SKIP_DOT

此變數對於 find_package 的組件形式無效。在向後相容模式下 (即沒有組件清單)，它可以防止 finder 模組搜尋 Graphviz 的 dot 公用程式。