Clever Geek Handbook

CMakeでDoxygenを使用する

最近、ソースコードのドキュメントを維持し、 DoxygenとCMakeを使用してそれを構築することを考えました。 すぐに不快な問題に直面しました。 実際、私のプロジェクトでは次の構造を使用しています。 

 ビルド/
   src /
   CMakeLists.txt
  ドキシファイル
私の場合、アセンブリはビルドディレクトリで実行されます。 ただし、アセンブリはどこからでも実行できます。 したがって、アセンブリディレクトリを変更しても、ドキュメントは収集されません。 Doxygenは、このドキュメントを収集する必要のあるソースを見つけられません。 それから私は、 CMakeとDoxygenと一緒にドキュメントアセンブリプロセスを管理する方法を疑問に思いましたか？ ユーザーと開発者の複数の種類のドキュメントを取得する必要がある場合はどうなりますか？ Doxygenの 2つの構成ファイルを保持しますか？ 私はこのオプションが気に入らない ファイルは、1つのENABLED_SECTIONS変数の値のみが異なります。 以下で、ドキュメントのアセンブリを管理する方法について説明します。



方法1（CONFIGURE_FILE）



インターネットおよびCMakeソース自体で、 CMakeでDoxygenを操作するためのおよそ次の方法を見つけることができます。

FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  1. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  2. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  3. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  4. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  5. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  6. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  7. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



  8. FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .



FIND_PACKAGE(Doxygen) IF (DOXYGEN_FOUND) SET (DOXYGEN_INPUT ${CMAKE_SOURCE_DIR}) CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/doxygen.conf. in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ADD_CUSTOM_TARGET(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf) ELSE (DOXYGEN_FOUND) MESSAGE(STATUS "WARNING: Doxygen not found - Reference manual will not be created" ) ENDIF (DOXYGEN_FOUND) * This source code was highlighted with Source Code Highlighter .





トリックは、上記のコードの3行目と4行目にあります。 それらで何が起こるか見てみましょう。 ADD_CUSTOM_TARGETコマンドは、最初のパラメーターによって転送されたファイルを2番目のパラメーターによって転送されたファイルにコピーし、ソーステキストの@ VAR @または$ {VAR}の形式の変数をCMakeファイルで定義された対応する変数の値で置き換えます（ ドキュメントの ADD_CUSTOM_TARGETの詳細を参照してください）。 つまり doxygen.conf.inファイルにINPUT = @ DOXYGEN_INPUT @という形式の行がある場合、doxygen.confファイルではそれが置き換えられ、 @ DOXYGEN_INPUT @の代わりに変数CMAKE_SOURCE_DIRの値が置換されます（上記のコードの3行目を参照）。



上記の方法は、ドキュメントを組み立てるプロセスを何らかの形で管理することを可能にし、ほとんどのプロジェクトに非常に適しています。 それにもかかわらず、私の謙虚な意見では、いくつかの重大な欠点があります。

  1. 制御するすべての変数は、事前に@ VAR @または$ {VAR}の形式で設定する必要があります
  2. これにはDoxywizardを使用できません。 一般に、 Doxywizardについては忘れることができます。 ファイル形式と互換性がなくなります。 Doxywizardからファイルを再保存すると、単にすべての設定が壊れます。
  3. もっとも重要なことは、このような構成ファイルはDoxygen自体と互換性がなくなり 、 CMakeがなければ、それを使用して正しいドキュメントを取得することができなくなることです。

別の方法（私のオプション）



上記の欠点を回避するために、ドキュメントアセンブリプロセスを制御する独自のマクロを作成することにしました。





  1. MACRO（CONFIGURE_DOXYGEN_FILE DOXYGEN_CONFIG_FILE FILE_NAME_SUFFIX）
  2. IF （EXISTS $ {PROJECT_SOURCE_DIR} / $ {DOXYGEN_CONFIG_FILE}）
  3. FILE（REMOVE $ {CMAKE_CURRENT_BINARY_DIR} / doxy-$ {FILE_NAME_SUFFIX} .conf）
  4. ファイル（読み取り$ {PROJECT_SOURCE_DIR} / $ {DOXYGEN_CONFIG_FILE} DOXYFILE_CONTENTS）
  5. STRING （REGEX REPLACE ";" "\\\\;" DOXYFILE_CONTENTS "$ {DOXYFILE_CONTENTS}" ）
  6. STRING （正規表現の置換"\ n" ";" DOXYFILE_LINES "$ {DOXYFILE_CONTENTS}" ）
  7. リスト（長さDOXYFILE_LINES行）
  8. 数学（EXPR ROW "$ {ROW}-1" ）
  9. FOREACH（私は$ {ROW}の範囲）
  10. リスト（ GET DOXYFILE_LINES $ {I} LINE）
  11. IF （線の「」 ）
  12. 文字列（正規表現「^ [a-zA-Z]（[^]）+」 DOXY_PARAM $ {LINE}）
  13. IF （定義済みDOXY _ $ {DOXY_PARAM}）
  14. 文字列（正規表現の置換"=（[^ \ n]）+" "= $ {DOXY _ $ {DOXY_PARAM}}" LINE $ {LINE}）
  15. ENDIF （定義済みDOXY _ $ {DOXY_PARAM}）
  16. ENDIF （）
  17. FILE（APPEND $ {CMAKE_CURRENT_BINARY_DIR} / doxy-$ {FILE_NAME_SUFFIX} .conf "$ {LINE} \ n" ）
  18. ENDFOREACH（）
  19. その他 （）
  20. MESSAGE（SEND_ERROR 「Doxygen設定ファイル '$ {DOXYGEN_CONFIG_FILE}'が見つかりません。ドキュメントは生成されません」
  21. ENDIF （）
  22. ENDMACRO（CONFIGURE_DOXYGEN_FILE）
*このソースコードは、 ソースコードハイライターで強調表示されました。




  1. MACRO（ADD_DOCUMENTATION TARGET DOXYGEN_CONFIG_FILE）
  2. FIND_PACKAGE（Doxygen）
  3. IF （DOXYGEN_FOUND）
  4. CONFIGURE_DOXYGEN_FILE（$ {DOXYGEN_CONFIG_FILE} $ {TARGET}）
  5. ADD_CUSTOM_TARGET（$ {TARGET}コマンド$ {DOXYGEN_EXECUTABLE} $ {CMAKE_CURRENT_BINARY_DIR} / doxy-$ {TARGET} .conf）
  6. ELSE （DOXYGEN_FOUND）
  7. MESSAGE（ステータス「Doxygenが見つかりません。ドキュメントは生成されません」 ）
  8. ENDIF （DOXYGEN_FOUND）
  9. ENDMACRO（ADD_DOCUMENTATION）
*このソースコードは、 ソースコードハイライターで強調表示されました。


最も簡単な使用方法





  1. SET （DOXY_OUTPUT_LANGUAGE "ロシア語" ）
  2. SET （DOXY_INPUT $ {PROJECT_SOURCE_DIR}）
  3. ADD_DOCUMENTATION（doc Doxyfile）
*このソースコードは、 ソースコードハイライターで強調表示されました。


ここで何が起こっているかを考えてください。 CONFIGURE_DOXYGEN_FILEマクロは、 CMake configure_fileコマンドに多少似ています 。 Doxygen構成ファイルのコピーを作成しますが、特別な変更は必要ありません。 彼女は構成ファイルを1行ずつ読み取り、 Doxygenパラメーターを探し、 CMakeに同じ名前とDOXY_プレフィックスを持つパラメーターがあるかどうかを確認します（13行目）。 そのようなパラメーターが存在する場合、その値はDoxygenパラメーターの値として置換されます（14行目）。



T.O. CMakeで Doxygenパラメーターを操作でき、同時にソース構成ファイルとDoxygenおよびDoxywizardとの互換性を失わないようにします。 結果のファイルのコピーは、元の構造を完全に保持します。



結論として、ユースケースはより複雑です。 ユーザーと開発者のドキュメントの同時アセンブリがどのように見えるかのバリアント。 このため、ソースコードで\ ifコマンドを使用して適切なセクションをマークする必要があります





  1. SET （DOXY_OUTPUT_LANGUAGE "ロシア語" ）
  2. SET （DOXY_INPUT $ {PROJECT_SOURCE_DIR}）
  4. SET （DOXY_ENABLED_SECTIONS "user_sec" ）
  5. SET （DOXY_OUTPUT_DIRECTORY "$ {CMAKE_CURRENT_BINARY_DIR} / doc-user" ）
  6. ADD_DOCUMENTATION（user_doc Doxyfile）
  8. SET （DOXY_ENABLED_SECTIONS "developer_sec" ）
  9. SET （DOXY_OUTPUT_DIRECTORY "$ {CMAKE_CURRENT_BINARY_DIR} / doc-developer" ）
  10. ADD_DOCUMENTATION（developer_doc Doxyfile）
  12. ADD_CUSTOM_TARGET（doc DEPENDS user_doc developer_doc）
*このソースコードは、 ソースコードハイライターで強調表示されました。


More articles:


All Articles