miauのブログ

はてなダイアリー「miauの避難所」をはてなブログに移行しました

phpUnderControl 初期設定&設定上の注意点

というわけで続きです。

CakePHP の深いところは次回にまわしますが、オプションで指定するだけ、というようなポイントは今回説明してしまいます。今回も長いので要注意です。

また前置き

  • 普段 SimpleTest を使っているので、PHPUnit まわりの設定には疎いです
  • デプロイもやってないので同様です
  • svn 前提で書きます
  • プロジェクト名は my-project としておきます
  • パスは /opt/cruisecontrol からの相対パスだと思ってください。

プロジェクトの作成

プロジェクトの作成には、大きく 2 種類のやり方があります。

1. 手動で設定する方法

公式ドキュメントで紹介されている、config.xml と projects/my-project/build.xml を手動で作成する方法です。

ant でタスクを直接実行する手順なんかも書いてあるので、細かい動作を知りたい場合は読んでおいたほうがいいかもしれません。

/usr/share/php/docs/phpUnderControl/docs/ に well-commented なサンプルもあるので、これをコピーして雛形として使ってもいいでしょう。

2. phpuc project を使う方法

phpUnderControl 0.4.0 から使えるようになった方法で、

あたりで紹介されています。(PHPUnit Manual で紹介されている方法もこちら)

phpuc project --project-name my-project
              --version-control svn
              --version-control-url http://example.com/svn/trunk/
              --test-case HogeTest
              --test-file HogeTest.php
              --test-dir .
              --source-dir .
              --coding-guideline Zend
              /opt/cruisecontrol

といったコマンドを実行する感じです。オプションを元に config.xml や projects/my-project/build.xml を勝手に作ってくれます。

以下、オプションで注意が必要な点について軽く説明します。

  • 最初の 3 つのオプションは必須なので指定します。
  • PHPUnit を使わない場合は test-case、test-dir、test-file は省略できるんですが、こうしてしまうとグラフ作成の記述が追加されないため、適当なものを指定しています。これを指定しない場合、自分で config.xml に追加する必要がありますのでご注意ください。
  • --source-dir は PHPDocumentor や PHPUnit の対象となるディレクトリを指定するオプションです。デフォルトで src になります。path/to/repository/trunk/src というような構成があるとして、--version-control-url オプションで trunk を指定したような場合はデフォルトでいいんですが、trunk/src まで指定したような場合は . を指定しておきます。
  • --coding-guideline は PHP_CodeSniffer で使用されるコーディングルールの種類を指定します。デフォルトの PEARpear.php.net で公開する場合を想定したルールだと思うので、私は Zend(or これを元にしたコーディングルール)を使っています。この辺の詳細は以下に書いています。

・・・とまあ色々書きましたが、オプションを間違えても後で .xml を変更すればいいだけなので、あまり深く考えなくても大丈夫です。

オプションを色々つけるのが面倒で、

phpuc example --project-name my-project /opt/cruisecontrol

を元に編集をやったこともありますが、

  • svn からの取得設定等を自分で行う必要がある
    • alwaysbuild になっているので、ここの設定も変える必要あり
  • source 配下に余計なファイルができるので、これを消す必要もあり

という感じでかえって面倒だったので、やめておいたほうがよいです。

checkout タスクの確認

phpuc project でプロジェクトを作成する際、--version-control-url を指定しても、SVN に認証がかかっているような場合チェックアウトがうまくいかなかった気がします。(--username と --password は指定したはずなんですが・・・。)毎回のビルドでは svn up が呼ばれるだけなので、ここでコケるとチェックアウトすらされていません。

念のため、

svn info projects/my-project/source

として確認しておきましょう。ここで

svn: 'projects/my-project/source' is not a working copy

と言われるようなら、手動でチェックアウトしてしまいます。

svn checkout http://example.com/svn/trunk/ projects/my-project/source

そして、

svn up projects/my-project/source

とやってちゃんと認証等を求められずにコマンドが実行できることを確認しておきます。

もし svn のユーザ名とパスワードが保存されない設定にしてあるのであれば、projects/my-project/build.xml で定義されている checkout タスクに --username や --password オプションを追加しておけば OK です。(以下でも特に断りがない場合、編集は projects/my-project/build.xml に対して行うと思ってください。)

諸々の設定

設定をちゃんと行わないと、エラーが多数検出されてしまいます。例えばこんな感じ。

一度こうなってしまうと「がんばってコーディングルール違反を 100 件削ったよ!」というような場合にもチャートの変化が微々たるものになってしまい、いまいちモティベーションが上がりません。なので、設定(特に除外設定)はある程度まじめにやっておいたほうが良いです。(本当は phpuc project の --ignore-dir オプションで指定できるはずなんですが、なぜだかうまくいっていないようです。)

といってもあまりまじめにやってると導入の敷居が高くなってしまうので、最初の数回のビルド履歴は消してしまう想定で、とりあえず導入しちゃうというのもアリだと思います。履歴は phpuc clean で消せますし。

以下一応個別に説明します。詳しくは各コマンドのヘルプ(phpcs --help や phpdoc -h)をご覧ください。

php-documentor タスクの設定

もし対象のディレクトリを絞り込みたい場合は、

  • -d オプションで対象ディレクトリを追加
  • -i オプションで除外ファイルを指定

します。例えば

  • 対象は ./app 以下を対象にしたい
  • その中でも ./app/tests、./app/vendors 以下は対象にしたくない

というような場合は、こんな感じでオプション指定をしてました。(スラッシュの位置が統一されていませんが、意図は覚えてません・・・。)

-d ./app
-i *tests/*,*/vendor*

ちなみにこの例では unit test のクラスを除外していますが、本当はこれもドキュメント生成対象に含めたほうがいいのかもしれません。

php-codesniffer タスクの設定

プロジェクト作成時に設定している場合は問題ありませんが、コーディングルールを変更する場合は --standard オプションを使用します。独自のルールを適用する場合フルパスで指定するとよいです。(私は独自ルールを pear/PHP/CodeSniffer/Standards に放り込んで、これを指定していました。)

対象が複数ある場合は引数に複数のファイルを渡してやり、除外ファイルを指定する場合は --ignore オプションで除外ファイルを指定します。

 --ignore=*/tests,*vendor*

Warning はいいから Error だけ拾いたい、というような場合は -n オプションを指定してしまえば OK です。

CakePHP で使用する場合、CakePHP CodingStandards に従うならインデントはタブで行うべきなので --tab-width=4 も指定しておきます。

その他タスクの設定

メール送信設定

せっかく CI サーバを立てたのですから、ビルドに失敗した場合はメール等で通知する設定にしておきましょう。

この設定については、前回も出てきた

で説明されています。(/usr/share/php/docs/phpUnderControl/docs/ 配下のサンプルにも記述があります。)

細かい設定は以下の URL を参照してください。

「細かいことはいいから開発用の ML にメール投げたい!」という場合は config.xml 配下にこんな感じの設定を追加すれば OK です。

      <htmlemail mailhost="smtp.example.com"
           returnaddress="dev_user@example.com"
           buildresultsurl="http://cruisecontrol.example.com:8080/buildresults/my-project"
           skipusers="true" spamwhilebroken="true" charset="UTF-8">
        <map alias="developer" address="dev_ml@example.com" />
        <failure address="developer" reportWhenFixed="true"/>
      </htmlemail>

日本語を含む場合は文字化けしてしまうので、charset の指定を追加しています。また、サンプルは

        <always address="developer" />

というようにビルドに成功した場合もメールを送るようになっていましたがいましたが、鬱陶しかったのでビルド失敗時(&失敗直後の成功時)のみ送られるよう、

        <failure address="developer" reportWhenFixed="true"/>

と設定変更しています。

さらに上記の URL では email になってましたが、ここを htmlemail に変えています。これは email だと

View results here -> http://cruisecontrol:8080/buildresults/my-project?log=log20090215195325

のように何の情報もないメールしか飛ばなかったためです。

htmlemail だとこれくらいのメールが飛びます。HTML メールが嫌いな方は email にして、charset オプションも外してしまってください。


DB 初期化等

unit test の前提となるテストを用意するために、DB 初期化シェルを流すようなケースがあると思います。タスクを追加してもいいんですが、面倒な場合 checkout タスクの最後に

<exec executable="sh" dir="${basedir}/source/db" failonerror="on">
    <arg line="initialize.sh"/>
</exec>

のような処理を追加してしまう形でもいいと思います。

トラブルシューティング

シュートしきれてないですが、ハマりそうな点です。

タイムゾーンがずれる件

Date of build なんかが JST 基準で 2009-03-04T20:20:11+0900 になってほしいのに、GMT 基準で 2009-03-04T11:20:11 になっていたりします。

前試したときは大丈夫だったんだけどなー?と調べてみると、CruiseControl 0.4.7 のバグのようで。0.4.8 で対応予定とのことです。

OutOfMemoryError 対策

CruiseControl をずっと起動していると、

Java heap space
java.lang.OutOfMemoryError: Java heap space

こんなエラーが出ることもありました。これは cruisecontrol.sh に

# CC_OPTS="-Xms128m -Xmx256m"

という記述があるので、これを uncomment しておけばとりあえず解決できると思います。(場合によってはもっと数値を増やす必要もあるかもしれません。)

また、PHPDocumentor だか PHP_CodeSniffer だかの実行時に、PHP 側で memory_limit 制限に引っ掛かることもあった気がします。この場合は php.ini 等で設定しましょう。

心構えとか

PHP_CodeSniffer や PHPDocumentor のエラーと真面目に向き合いすぎると、やたら時間を取られてしまいます。そこそこで満足しましょう。

心構えについては私がだらだら説明するよりも、以下のページを読んでいただくほうがいい気がします。

今後やりたいこと

実はまだ Selenium の実行を CI に組み込めてません。Selenium RC を叩く形にすれば簡単に実現はできるんですけど。これが組み込めるとテストで 30 分とかかかるようになってくるので、そこは一日に一度テスト〜、みたいな感じでより CI っぽくなってくるので、次回はぜひやりたいところ。

で、ちょっと悩んでいるところなんですが、Selenium をローカルで実行するとしたら、CI サーバは Windows で構築したほうがいいのかもしれません。IE での動作保証を求められる場合も多く、この場合 Selenium の実行も最終的には IE で行うことになりますので。

一方で、

という状況であれば、CI サーバは Linux のほうがいいかなという気がします。

なんかにあるように、OS 間の差異が吸収できるのも CI の利点だと思いますので。

      • -

といったところで、初期設定の話は終わり。あとは CakePHPSimpleTest)と組み合わせて使う方法について書く予定です。