Doxygen + Jenkinsの使い方のメモ書き
環境とか準備とかそういうの
環境はWindows7と8で確認してますです.
最初に Doxygen: Downloads からWindowsのインストーラをダウンロードしておきます.
この記事を書いてる時点での最新バージョンだと doxygen-1.8.3.1-setup.exe ってやつです.
ダウンロードできたら適当にインストールしちゃいましょう.
インストール先はデフォルトの C:\Program Files\doxygen
で問題ないと思いますが,
僕はパスにスペースが入るのが嫌だったので C:\doxygen
にしました.
Doxygenの動作確認をします.コマンドプロンプトを開いて
C:\> c:\doxygen\bin\doxygen.exe --version
1.8.3.1
次にドキュメンテーションコメント付きのコードを用意しておきます.
公式の資料 Doxygen を参考にしながら適当にソースコードとドキュメンテーションコメントを書きます.
Javadoc形式で書くことになっているので,ちゃちゃっと書いてしまいます(他にQtというコメント形式も使えるようですが僕にはよくわからないので今回はスルー).
サンプルに書いたのはこんなコード.
Doxygen設定ファイルの作成
Doxygenを弄っていきます.
これはGUIでやるのが分かりやすい気がするので, C:\doxygen\bin\doxywizard.exe
を使います.
Step 1
- 「Specify the working directory from which doxygen will run」にはdoxygenを実行する際にカレントディレクトリにするディレクトリを指定します.ひとまず設定ファイルと同じ場所に指定しました.
Step 2
Wizardタブでは
- Project nameに適当な名前を入れます.
- OutputでLaTeXの生成からチェックを外します
Expertタブに移って
- EXTRACT_ALLをYES(チェック)
- INPUT_ENCODINGをCP932
- FILE_PATTERNSに「*.cpp」(お好みで必要なパターンを追加)
- VisualStudioを使っているとINPUTにUTF-8を指定してると化けるのでCP932に変更
必要に応じて色々変更することになると思いますが,最低限これでいいはず.設定内容を保存してドキュメントを生成します
Runタブに移り,[Run Doxygen]をクリックすると生成されます.
Doxywizerdの[Show HTML output]をクリックするか,設定した出力先にhtmlってディレクトリができているので,その中にあるindex.htmlを開くと生成したドキュメントが見られます.
Jenkinsとの連携時の設定
流れとしては、
- Doxygen Pluginをインストール
- ビルド時の手順でWindowsバッチコマンドの実行を使ってDoxygenを実行
- ビルド後の処理でPublish Doxygen Pluginを使ってJenkinsにドキュメントへのリンクを貼る
という感じです.
まずはDoxygen Plugin - Jenkins - Jenkins Wikiをインストールします.Jenkinsのプラグイン管理の画面で探せばすぐに見つかると思います.
次にビルド処理にDoxygenを実行するコマンドを追加します.このとき,必ず設定ファイル作成時に「Specify the working directory from which doxygen will run」で設定したディレクトリに移動してから実行するようにします.
cd doxygenExample\doxygenExample
C:\doxygen\bin\doxygen.exe doxy-conf
このコマンドが開始される際のカレントディレクトリはJenkinsのworkspace直下なので cd doxygenExample\doxygenExample
となっています.
最後にビルド後の処理に、Publish Doxygenを追加し、設定を行います。設定は高度な設定も開いて行います。 と言っても項目は2つですが。
- Doxyfile path
- Folder from which doxygen is run
「Doxyfile path」にはworkspaceから設定ファイルへの相対パス doxygenExample\doxygenExample\doxy-conf
を入力します。
「Folder from which doxygen is run」には設定ファイル作成時に「Specify the working directory from which doxygen will run」で設定したディレクトリを入力します。
設定を保存してビルド実行すれば、ジョブのトップページに [DoxyGen HTML] というリンクができているはずです。
うまく生成できているか確認しましょう。
おわりに
「Specify the working directory from which doxygen will run」と「Folder from which doxygen is run」の正しい設定がわからなくてハマりました…
これを理解していないとDoxywizerd使った時と,コマンドラインから実行した時でhtmlが生成される場所が変わってしまい混乱することになりますゆえ.