Skip to content.

Sections
Personal tools
You are here: Home » 技術文書 » ツール » Maven連載 » 第4回 サイトレポートを使ってみる[1]

Document Actions

第4回 サイトレポートを使ってみる[1]

今回の内容

前回は、サンプルプロジェクトに対して基本的なゴールを実行してみました。今回はプロジェクトの各種レポートを生成するサイトレポートの出力のための設定と、レポート作成について解説します。なお、今回よりWebでの連載になりました。メルマガには記事のダイジェストのみ掲載することになります。今後ともよろしくお願いします。

Mavenの最新版公開

先月5/20にMavenの最新公開版となる1.0-rc3がリリースされました。今回のリリースでは、サイトレポートに日本語を使用としたときの文字化けのバグが修正されています [1] 。是非最新版に更新してください。

サイトレポートとは

Mavenで管理するプロジェクトは、POM(Project Object Model)にモデル化されています。サイトレポートはPOMに関連する情報、及び成果物をレポートとして生成したものです。プロジェクトは、プロジェクト自体の属性(名前、目的、組織、開発者、メーリングリスト)と、プロジェクトの成果物が刻々と変化しています。サイトレポートは、変化するプロジェクトのスナップショットとして、プロジェクトを様々な角度から表現します。

また、サイトレポートはプロジェクトポータルとしての役割も果します。プロジェクトに関する全ての公開可能な情報が、サイトレポートから辿りつけるようになることで、プロジェクトに関する情報の集約が実現できます。

各レポートの中には、Ant単体でも実行できるものもあります。しかしAntでプロジェクトポータルを作ろうとすると、build.xmlの記述、関連タスクの取得と設定、HTML作成などなど、手作業がかなりあります。プロジェクトが変るとまた新しくやりなおし...こんな経験をしたことがありませんか? 筆者が最初にMavenに目を付けたのはこのサイトレポートがあったからでした。Mavenの真髄は プロジェクトのモデル化による一貫性のあるアクション ですが、プロジェクトにMavenを導入するのに、このサイトレポートから始めてみるのはお勧めできます。

Mavenの利用者は、サイトレポートによって2つのプロジェクトの側面を文書化して閲覧することができます。

  • プロジェクトの目的、チーム情報の閲覧
    • POMに記述してある、プロジェクトの目的、開発者、メーリングリスト、問題管理サイトへのURL、ソースコード管理サーバへのリンクなどを文書化します。途中からプロジェクトに参加しても、プロジェクトを取り巻く環境が一目でわかるようになっています。
  • プロジェクトの成果物の日々の確認
    • プロジェクトが進むにつれて、成果物、つまりソースコードやテストコードも増えていきます。Mavenのサイトレポートを使用すると、プロジェクトの成長過程を様々な角度から確認することができます。

サイトレポートは日次で生成するようにスケジュールすることで、毎朝最新のプロジェクトの状態を確認することができます。これ以上の頻度で(日に数回)サイトレポートを生成する場合には、規模が大きくなってきた時の生成時間などの問題もからんできます。また、それ以下の頻度(数日に1回)では、情報が陳腐化してしまう恐れがあります。

サイトレポート生成のための設定

必要な設定について

サイトレポートはproject.xmlに記述してあるPOMの設定と、実際の成果物であるソースコードを基に生成されます。サイトレポートを生成する前に、レポートの出力エンコードについて設定する必要があります。サイトレポートの出力エンコーディングは、project.properties に maven.docs.outputencoding を指定します。

project.xml に日本語を記述していても、maven.docs.outputencodingを指定すれば自動的に変換され出力できますが、Javadocの場合は基本的に記述されているエンコーディングで生成されてしまいます。実際にはソースコードに使用しているエンコーディングに全体を合わせるのをお勧めします。

なお、今回は実際のプロジェクトとして、お馴染の JUnit をMavenに対応させて、サイトレポートを出力させてみました。既存のプロジェクトをMavenに対応させてサイトレポートが生成できるようにするためには、最低限コンパイルができるように、ソースディレクトリの設定と依存関係の解決が必要です。

POMの設定

project.xml に記述するPOMの値はサイトレポートに表示されます。詳しくは以降のプロジェクト情報の解説に譲りますが、ここではサイトレポートの顔であるトップページとロゴの設定について解説します。

サイトレポートの上部は、左上がプロジェクトに関る組織について、右上がプロジェクトそのものについての情報を表示します。組織は<organization>配下の<name>、<url>、<logo>の値を、プロジェクトについては<name>、<logo>、<url>の値を使用します。どちらも<logo>が指定されていない場合には、<name>の値が代りに表示されます。サンプルでは、組織にJUnit.orgの情報をロゴ付きで、プロジェクトのロゴについては、JUnit.orgでお馴染のカエルを指定してみました。

組織の設定:

<project>
  [...]

  <!-- プロジェクトの名前、ロゴ、URL(右上) -->
  <name>JUnit</name>
  <logo>http://www.junit.org/images/frogMov.gif</logo>
  <url>http://www.junit.org/</url>

  <!-- 組織の名前、ロゴ、URL(左上) -->
  <organization>
    <name>JUnit.org</name>
    <url>http://www.junit.org/</url>
    <logo>http://www.junit.org/images/junitlogo.gif</logo>
  </organization>

 [...]

</project>

サイトレポートの右上のロゴ、クリック時のリンクは、project.xml 直下の<url>、<logo>を設定します。

ソースディレクトリの設定

ソースディレクトリとは、ソースツリーを格納しておくためのディレクトリのことです。Mavenの推奨するプロジェクトツリーは、ソースツリーを ${basedir}/src/java 以下に格納します。このようなレイアウトであれば、 src/java を project.xml の <sourceDirectory>に指定しておくだけで後は設定の必要はありません。 [2] 同様にテストコードのソースツリーは src/test になります。

Mavenを使っていないプロジェクトのソースツリーでは、プロジェクトルート直下にソースツリーを配置している場合があります。(JUnitもそうです) この場合、<sourceDiretory> には . を設定することになりますが、こうするとプロジェクトルートにある全てのディレクトリがソースコードの対象となってしまいます。通常こういった配置をしているプロジェクトでは、 build.xml に <fileset> を使用して対象ファイルをフィルタが書かれているはずです。しかし1つディレクトリを配置してソースツリーを移動するだけで、フィルタを設定する必要はなくなります。できればソースツリーの移動を検討しましょう。

ソースディレクトリを設定しない(=./)場合:

projectRoot
  |- jp       <= 全てがコンパイル対象になる
  |   |- co   
  |- doc      <= この配下にJavaソースがあったら対象にされてしまう!
  |- sample   <= この配下にJavaソースがあったら対象にされてしまう!

ソースディレクトリにsrc/javaを設定した場合:

projectRoot
  |- src
  |   |- java <== ここを起点としてソースを探索する
  |   |- test
  |- doc      <== 対象外
  |- sample   <== 対象外

Mavenでも project.xml にフィルタを記述することは可能ですが [3] 、現在の構成では全てのプラグインがそのフィルタを使う保証はされません。このためディレクトリを分けておくほうが安全です。Mavenの推奨するプロジェクトツリーの説明は http://maven.apache.org/reference/dirlayout.html を参照してください。

依存関係の解決

依存関係の解決は、 project.xml の <dependencies> で設定します。依存関係の設定については 前回 の記事を参考にしてください。

サイトレポートの生成

サイトレポートの生成は、mavenでビルドができる状態のプロジェクトで「maven site」を実行します。siteゴールは、java:compileゴールに依存しているため、ソースのコンパイルが成功しないとレポートが生成できません。siteゴールを実行すると、多くのレポート生成用のプラグインを呼出します。サイトレポートに含まれるレポートは、デフォルトで11種類用意されています。project.xmlをカスタマイズして、どのレポートを対象とするかを指定することもできます。 [4]

サイトレポートの生成:

$ maven -b site
build:start:

site:
xdoc:register-reports:
maven-jdepend-plugin:register:

maven-checkstyle-plugin:register:

maven-changes-plugin:register:

maven-changelog-plugin:register:

maven-developer-activity-plugin:register:

maven-file-activity-plugin:register:

maven-license-plugin:register:

maven-javadoc-plugin:register:

maven-jxr-plugin:register:

maven-junit-report-plugin:register:

maven-tasklist-plugin:register:

site:run-reports:

[以下続く...]

サイトレポートは標準では ${maven.build.dest}/docs 、つまりtarget/docs に生成されます。サイトレポートの生成先は maven.docs.dest で変更可能です。

サイトレポート解説

サイトレポート - About

About [プロジェクト名] は、サイトレポートのトップページになります。project.xml の <description>の内容がそのまま適用されます。descriptionを複数行に渡って記述したい場合には、<![CDATA[]]>で記述します。<![CDATA[]]>の内部にはHTMLタグも記述できるため、自由にレイアウトすることができます。

Descriptionの設定(project.xml):

<!-- プロジェクトの説明 -->
<description>
  <![CDATA[
  <p>Welcome to JUnit.org. This site is dedicated to software developers using JUnit or one of the 
  other XUnit testing frameworks. We'll be adding more content and web-based services over time. 
  Initially we'll be providing links to give you a one-stop destination to learn the latest 
  information on unit testing.</p>

  <p>Our goal is to serve you. Please tell us what you'd like to see here by contacting us at 
  <a href="mailto:junit@objectmentor.com">junit@objectmentor.com</a>. JUnit support is handled 
  through the <a href="http://groups.yahoo.com/group/junit/">JUnit Yahoo Group</a>.</p>

  <p>If you are looking for another one of the testing frameworks, you should look on 
  <a href="http://www.xprogramming.com/">www.xprogramming.com</a> under 
  <a href="http://www.xprogramming.com/software.htm">software</a>.</p>
  ]]>
</description>
サイトレポート - Project Info

プロジェクト情報は xdoc プラグインによって生成されます。実はサイトレポート全体のフレームもxdocプラグインによって生成されます。個々のレポートへのリンクまで生成して、リンクの先は個々のレポートが責任をもって生成するという仕組になっています。また、サイトレポートをカスタマイズする際にも、xdocを使用することになります。リンク先の個々のレポートは各レポートが別途生成することになります。

MalingLists

project.xmlに記述してある<mailingLists>の内容を元に、メーリングリストの一覧を出力します。<mailingLists>は複数の<mailingList>を含むことができます。JUnitの場合はメーリングリストにMailmanを使用しています。MailmanはWebインターフェースでメーリングリストへの登録/解除ができるため、<subscribe>、<unsubscribe>にはメールアドレスは記述せずに、<archive>にMailmanのURLを設定しています。

<mailingLists>の設定例:

<mailingLists>
  <mailingList>
    <name>junit-announce</name>
    <!-- 本来はここに subscribeできるアドレスを指定 -->
    <subscribe/>
    <!-- 本来はここに unsubscribeできるアドレスを指定 -->
    <unsubscribe/>
    <archive>http://lists.sourceforge.net/lists/listinfo/junit-announce</archive>
  </mailingList>
</mailingLists>
Project Team

project.xmlに記述してある<developers>の内容を元に、開発メンバーのレポートを生成します。JUnitの場合は、Sourceforgeのメンバー情報から値を指定しています。 [5]

<developers>の設定例:

<developers>
  <developer>
    <id>egamma</id>
    <name>Eric Gamma</name>
    <organization>The IBM Ottawa Lab</organization>
    <email>egamma@users.sourceforge.net</email>
    <roles>
      <role>developer</role>
    </roles>
  </developer>

  [...]

</devepers>
Dependencies

project.xmlに記述してある<dependencies>の内容を元に、依存するライブラリに関するレポートを生成します。JUnitの場合は依存ライブラリが存在しないため未設定です。

Source Repository

project.xmlに記述してある<repository>の内容を元に、ソースコードの構成管理システムのリポジトリに関するレポートを生成します。現状ではCVS(cvs, pserver, ext)と、Starteam、Subversionに対応しています。JUnit の場合は開発者用のリポジトリアクセスは不明なので、<connection>のみ設定してあります。<url>は ViewCVS のリンクを設定しておきます。

<repository>の設定例:

<repository>
  <connection>scm:cvs:pserver:anonymous@cvs.sourceforge.net:/cvsroot/junit:junit</connection>
  <developerConnection/>
  <url>http://cvs.sourceforge.net/viewcvs.py/junit/junit/</url>
</repository>

<connection>内容は次のようになっています。

scm:[SCMソフトウェア名]:[アクセス方法]:[ユーザID]@[ホスト名]:[リポジトリパス]:[モジュール名]
Issue Tracking

project.xmlに記述してある<issueTrakingUrl>の内容を元に、問題追跡システムに関するレポートを生成します。現在のMavenでは残念ながら & のような実体参照が必要な記号を含むURLをissueTrackingUrlに使用することができません。JUnitのバグ管理システムはSourceForgeのBTSを使用しているため、URLに & を含んでしまいます。今回はURLを設定するのはやめておきます。 [6]

サイトレポート - Project Reports

Project Rerports はMavenが標準で用意しているレポートプラグインによって生成されています。ここでは各レポートについて簡単に紹介します。各レポートを生成するプラグインについての詳しい情報は プラグインのサイト を参照してください。

Metrics

JDepend を使用した、パッケージ、クラス間の依存度レポートを表示します。オブジェクト指向の原則として高凝集、低結合や、循環依存の禁止などが挙げられます。JDependのレポートから、パッケージ毎の安定性、抽象度、循環依存の判定を読みとることができます。Summaryの項目の説明を以下に挙げておきます。

Summaryの項目一覧

項目名 意味
TC 全クラス数
AC 抽象クラス数
CC 具象クラス数
AC 求心性(外部に依存されている)クラス数
EC 遠心性(外部に依存している)クラス数
A 抽象度
I 不安定度
D 距離(抽象と安定のバランスの指針)

JUnitの場合だと、junit.awtuiパッケージは距離が0%です。つまり抽象的ではなく、外部からも使われない独立したパッケージであると言えます。一方、junit.frameworkパッケージは距離が40%です。そこそこ抽象的で、外部から使われており、外部への依存度もそれほど高くない比較的安定したパッケージと言えます。

また、循環依存に関しては、 Cycles に一覧されるので、一目でわかるようになっています。

Checkstyle report

非常に有名なコーディングスタイルチェッカーである Checkstyle を使用したスタイルチェックのレポートを生成します。Checkstyleは、単体でもAntやEclipseプラグインを使用してのチェックが可能です。EclipseプラグインとMavenを併用することで、プロジェクト全体としてスタイルの統一化を徹底することができます。デフォルトではCheckstyleのコーディングルールは sun のコーディングスタイルになっています。独自定義のコーディングスタイルを使用したい場合には、project.properties で maven.checkstyle.properties にカスタイマイズしたCheckstyleの設定ファイルを指定します。

Change Log

SCMの変更履歴を取得して、最新更新順でリスト表示します。更新履歴には「日付」、「作者」、「対象ファイル」、「コミットログ」が記載されているので、いつ誰が何をコミットしたかが一目でわかります。また、 project.xmlの中で、<repository>の<url>を指定していれば、ファイルやバージョンからViewCVSのサイトへのリンクが貼られます。デフォルトでは変更履歴の表示期間は30日以内の変更に限られています。この期間を変更する場合には、project.propertiesに maven.changelog.range=日数 を追加します。サンプルでは730日(2年)を指定しています。

Developer Activity

Change LogがSCMの更新履歴をそのままに表示しているのに対して、こちらは開発者に着目した更新情報のレポートです。SCMの更新履歴を元に、開発者毎にコミットしたファイル数、変更したファイル数を集計、ソートして表示します。開発者名から Project Info - Project team へのリンクが貼られています。こちらもデフォルトでは30日以内の変更のみ扱います。変更したい場合には、project.properties に maven.activitylog.range=日数 を追加します。

File Activity

こちらのレポートはファイルに着目した更新情報のレポートです。SCMの更新履歴を元に、変更された回数が多い順にファイルをソートして表示します。ファイル名からViewCVSへのリンクが貼られています。こちらもデフォルトでは30日以内のファイルの変更のみ扱いますので、変更したい場合はDeveloper Activity と同様に mavne.activitylog.range=日数 を追加します。

Project License

こちらはプロジェクトのライセンス情報を表示します。オープンソースプロダクトではライセンスは非常に重要ですが、SIなどの開発では設定する必要はないことが多いでしょう。

JavaDocs

javadocコマンドを使用してJavaDocを生成したものです。他のレポートとは異なり、Mavenで生成したサイトレポートとは別ウィンドウで表示されます。

JavaDoc Report

javadocコマンドの実行中のログを表示します。 これはjavadoc生成中にエラーや警告がなかったかどうかをチェックするのに有効です。 maven.docs.outputencoding を指定しないと日本語版j2sdkを使用している場合に文字化けします。

Source Xref / Test Xref

ソースコードのクロスリファレンスを生成します。Javadocと同じレイアウトで、HTML化、ソースコードの色分け、行番号を付加して、各クラス、インターフェースへのリンクを作成します。クロスリファレンスから、同じMavenで生成したJavadocへもリンクできるため、ソースコードを広く見たい場合には、EclipseなどのIDEよりも便利かもしれません。jxrというプラグインにより生成されます。

Source Xref、Test Xrefは各<sourceDirectory>、<unitTestSourceDirectory>で指定しているディレクトリ配下のソースを対象とします。今回のJUnitの場合は、プロダクトコードとテストコードが同一パッケージツリーに存在しているため、混在しています。

UnitTests

JUnitReportはJUnitによる単体テストの実行結果をレポートとして生成します。AntとJUnitで生成できるJUnitReportとはフレームを使わないで、1枚のHTMLとして生成する点が異なります。対象となるテストは <unitTestSourceDirectory> で指定したディレクトリを起点として、配下ディレクトリ全てを対象とします。デフォルトでは *Test.java ファイルが対象となります。対象のテストファイルを指定したい場合には、project.xmlに <unitTest> を設定してフィルタをかけます。フィルタの設定はAntの指定とほぼ同じです。

テストクラスのフィルタ:

<unitTest>
   <includes>
     <include>**/*Test.java</include>
   </includes>
   <excludes>
     <exclude>**/*Tests.java</exclude>
   </excludes>
 </unitTest>
Task List

ソースコードのJavadocコメント内の特定のタグ(デフォルトでは@todo)を一覧表示します。Eclipseのでタスク・タグで「@todo」を設定しておけば、Eclipseのタスクと同期がとれるようになります。対象のタグを変更したい場合は project.properties で maven.tasklist.taskTag を設定します。

Development Process

Development Processは本来は、開発プロセスの手順を記述しておき、プロジェクト内外で共有するものです。デフォルトでは、 http://maven.apache.org/development-process.html へのリンクになっています。もしDevelopment Processを別のURLへのリンクにしたい場合には、 project.properties で maven.xdoc.developmentProcessUrl を設定してください。

今回のまとめと次回予告

今回はサイトレポートについての設定とレポートの生成について解説しました。今回使用した、JUnitに対するproject.xmlとproject.propertiesの 設定アーカイブ を置いておきました。JUnitのソースツリーを入手して、Mavenを使ってサイトレポートを実行してみてください。

次回は今回に引き続き、サイトレポートについて取り上げます。今回はデフォルトの設定のままサイトレポートを出力しましたが、次回はレポートのカスタマイズを中心に解説する予定です。

文書情報

Author:懸田 剛(Takeshi Kakeda)
Contact:t-kakeda at esm.co.jp
[1]http://maven-plugins.sourceforge.jp/の主催者である菅谷さんのパッチが採用されました
[2]java以外のソースがある場合は src/groovyなどと言語毎にディレクトリを分けます
[3]<sourceDirecotry>はsourceModifications、<unitTestSourceDirecotory>は<unitTests>にフィルタを記述します
[4]レポートのカスタマイズについては次回解説します
[5]<organization>はSourceforgeからは取得できませんので、でっちあげです。一応所属会社を調べたつもりですが...
[6]次回サイトレポートのカスタマイズで代替リンクを作成します



この記事への評価にご協力をお願いします。

良かった 普通 イマイチ