ソースコードから自動ドキュメント生成: CMake と "FindDoxygen" を活用した Doxygen の使い方

"FindDoxygen" は、CMake に付属するモジュールであり、Doxygen 実行可能ファイルと Graphviz の "dot" プログラムを検索します。 Doxygen は、ソースコードから自動的にドキュメントを生成するツールです。 Graphviz の "dot" プログラムは、Doxygen によって生成されるグラフを可視化するために使用されます。

使い方

"FindDoxygen" モジュールを使用するには、CMake の find_package コマンドを使用します。以下は、基本的な例です。

find_package(Doxygen)

if (DOXYGEN_FOUND)
  message(STATUS "Doxygen found: ${DOXYGEN_VERSION}")

  # Doxygen コマンドを生成する
  add_executable(my_docs doxygen)
  target_sources(my_docs PRIVATE docs)

  # Doxygen 構成ファイルを指定する
  set(DOXYGEN_INPUT "docs/main.dox")
  set(DOXYGEN_OUTPUT "docs/html")

  # Doxygen コマンドを実行する
  target_link_directories(my_docs PRIVATE ${DOXYGEN_INCLUDEDIR})
  target_link_libraries(my_docs ${DOXYGEN_LIBRARIES})
  add_custom_command(TARGET my_docs
                     COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT}
                     OUTPUT_DIRECTORY ${DOXYGEN_OUTPUT})
endif()

この例では、find_package コマンドを使用して "Doxygen" パッケージを検索します。パッケージが見つかった場合、DOXYGEN_FOUND 変数が TRUE に設定され、Doxygen のバージョン情報が DOXYGEN_VERSION 変数に格納されます。

次に、add_executable コマンドを使用して Doxygen コマンドを生成します。コマンドのソースファイルは docs ディレクトリ内の main.dox ファイルです。

続いて、set コマンドを使用して Doxygen 構成ファイルと出力ディレクトリを指定します。

最後に、target_link_directories コマンドと target_link_libraries コマンドを使用して Doxygen コマンドに必要なライブラリをリンクします。そして、add_custom_command コマンドを使用して Doxygen コマンドを実行します。

オプション

"FindDoxygen" モジュールは、いくつかのオプションを受け取ります。以下は、利用可能なオプションのリストです。

DOXYGEN_OPTIONAL_COMPONENTS: このオプションを使用して、Doxygen がサポートするオプションコンポーネントを指定できます。利用可能なコンポーネントは、"mscgen"、"dia"、"graphviz" です。
DOXYGEN_REQUIRED: このオプションを TRUE に設定すると、モジュールは Doxygen 実行可能ファイルを見つけることが必須であることを示します。パッケージが見つからない場合、CMake はエラーで終了します。
DOXYGEN_SKIP_DOT: このオプションを TRUE に設定すると、モジュールは "dot" プログラムの検索をスキップします。

"FindDoxygen" モジュールの詳細については、CMake のドキュメントを参照してください:

古いバージョンの CMake を使用している場合は、モジュールのドキュメントで利用可能なオプションと変数が異なる場合があります。
この説明は、CMake バージョン 3.8 以降で使用できる "FindDoxygen" モジュールの最新バージョンに基づいています。

cmake_minimum_required(VERSION 3.8)

project(myproject)

find_package(Doxygen REQUIRED)

if (DOXYGEN_FOUND)
  message(STATUS "Doxygen found: ${DOXYGEN_VERSION}")

  # Doxygen コマンドを生成する
  add_executable(my_docs doxygen)
  target_sources(my_docs PRIVATE docs)

  # Doxygen 構成ファイルを指定する
  set(DOXYGEN_INPUT "docs/main.dox")
  set(DOXYGEN_OUTPUT "docs/html")

  # Doxygen コマンドを実行する
  target_link_directories(my_docs PRIVATE ${DOXYGEN_INCLUDEDIR})
  target_link_libraries(my_docs ${DOXYGEN_LIBRARIES})
  add_custom_command(TARGET my_docs
                     COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT}
                     OUTPUT_DIRECTORY ${DOXYGEN_OUTPUT})

  # Doxygen ターゲットを "all" ターゲットに依存させる
  add_dependencies(myproject ALL my_docs)
endif()

add_executable(myprogram main.cpp)

target_link_libraries(myprogram myproject)

この例では、以下のことが行われます。

CMake のバージョン 3.8 を必要とすることを宣言します。
myproject という名前のプロジェクトを作成します。
"Doxygen" パッケージを検索します。
パッケージが見つかった場合、Doxygen のバージョン情報を出力します。
Doxygen コマンドを生成します。コマンドのソースファイルは docs ディレクトリ内の main.dox ファイルです。
Doxygen 構成ファイルと出力ディレクトリを指定します。
Doxygen コマンドに必要なライブラリをリンクします。
Doxygen コマンドを実行します。
Doxygen ターゲットを "all" ターゲットに依存させます。
main.cpp ファイルから myprogram という名前の実行可能ファイルを作成します。
myprogram 実行可能ファイルを myproject ライブラリにリンクします。

この例は、"FindDoxygen" モジュールの基本的な使用方法を示しています。具体的なニーズに合わせてコードをカスタマイズする必要があります。

以下の例では、"FindDoxygen" モジュールのオプションを使用する方法を示します。

cmake_minimum_required(VERSION 3.8)

project(myproject)

find_package(Doxygen REQUIRED
              DOXYGEN_SKIP_DOT
              DOXYGEN_OPTIONAL_COMPONENTS mscgen dia)

if (DOXYGEN_FOUND)
  message(STATUS "Doxygen found: ${DOXYGEN_VERSION}")

  # Doxygen コマンドを生成する
  add_executable(my_docs doxygen)
  target_sources(my_docs PRIVATE docs)

  # Doxygen 構成ファイルを指定する
  set(DOXYGEN_INPUT "docs/main.dox")
  set(DOXYGEN_OUTPUT "docs/html")

  # Doxygen コマンドを実行する
  target_link_directories(my_docs PRIVATE ${DOXYGEN_INCLUDEDIR})
  target_link_libraries(my_docs ${DOXYGEN_LIBRARIES})
  add_custom_command(TARGET my_docs
                     COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT}
                     OUTPUT_DIRECTORY ${DOXYGEN_OUTPUT})

  # Doxygen ターゲットを "all" ターゲットに依存させる
  add_dependencies(myproject ALL my_docs)
endif()

add_executable(myprogram main.cpp)

target_link_libraries(myprogram myproject)

"dot" プログラムの検索をスキップします。
"mscgen" と "dia" というオプションコンポーネントを検索します。

この例は、"FindDoxygen" モジュールのオプションをカスタマイズする方法を示しています。具体的なニーズに合わせてオプションを調整する必要があります。

手動設定

欠点:
- 複雑でエラーが発生しやすい
- Doxygenと関連ツールのパスを手動で設定する必要がある
- CMakeのバージョン間で移植性が低い
利点:
- 高度な柔軟性と制御が可能
- 特定のニーズに合わせやす

手動設定では、Doxygenと関連ツールのパスをCMAKE_INCLUDE_PATHとCMAKE_LINK_DIRSなどの変数に直接設定します。 Doxygen構成ファイルも手動で作成する必要があります。この方法は、高度なカスタマイズが必要な場合や、"FindDoxygen"モジュールが正しく動作しない場合に役立ちます。

例

cmake_minimum_required(VERSION 3.8)

project(myproject)

set(DOXYGEN_EXECUTABLE "/path/to/doxygen")
set(DOT_EXECUTABLE "/path/to/dot")

# Doxygen コマンドを生成する
add_executable(my_docs doxygen)
target_sources(my_docs PRIVATE docs)

# Doxygen 構成ファイルを指定する
set(DOXYGEN_INPUT "docs/main.dox")
set(DOXYGEN_OUTPUT "docs/html")

# Doxygen コマンドを実行する
target_link_directories(my_docs PRIVATE ${DOXYGEN_EXECUTABLE}/include)
target_link_libraries(my_docs ${DOXYGEN_EXECUTABLE})
add_custom_command(TARGET my_docs
                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT}
                   OUTPUT_DIRECTORY ${DOXYGEN_OUTPUT})

# Doxygen ターゲットを "all" ターゲットに依存させる
add_dependencies(myproject ALL my_docs)

add_executable(myprogram main.cpp)

target_link_libraries(myprogram myproject)

サードパーティ製モジュール

欠点:
- "FindDoxygen"ほど広くサポートされていない場合がある
- 特定のCMakeプロジェクトとの互換性がない場合がある
利点:
- "FindDoxygen"よりも使い方が簡単な場合がある
- 追加機能を提供する場合がある

サードパーティ製のモジュールは、"FindDoxygen"の機能を拡張したり、特定のニーズに対応したりする代替手段を提供します。人気のあるオプションには、以下が含まれます。

これらのモジュールの使用方法については、それぞれのドキュメントを参照してください。

Bashスクリプト

欠点:
- 複雑なDoxygenプロジェクトには不向き
- CMakeワークフローに統合しにくい
利点:
- 非常にシンプルで軽量

Bashスクリプトを使用して、Doxygenと関連ツールの検索と実行を自動化することができます。これは、簡単なプロジェクトや、CMakeを使用しないことを好む場合に役立ちます。

例

#!/bin/bash

# Doxygenと関連ツールのパスを設定
DOXYGEN_EXECUTABLE="/path/to/doxygen"
DOT_EXECUTABLE="/path/to/dot"

# Doxygen コマンドを実行
${DOXYGEN_EXECUTABLE} docs/main.dox -o docs/html

# 生成されたドキュメントをビルドディレクトリにコピー
cp -r docs/html ../build/docs

カスタムCMakeスクリプト

欠点:
- 開発と保守に時間がかかる
利点:
- 高度な柔軟性と制御が可能
- 特定のニーズに合わせやすい
- CMakeワークフローに完全に統合

カスタムCMakeスクリプトを作成して、Doxygenと関連ツールの検索、構成、実行を独自の方法で処理することができます。これは、複雑なプロジェクトや、ワークフローを高度にカスタマイズする必要がある場合に役立ちます。

cmake_minimum_required(VERSION 3.8)

project(myproject)

# Doxygenと関連ツールの検索
find_program(DOXYGEN_EXECUT