オリジナル: Plugin Tutorial

このドキュメントでは hello-worldプラグイン とともにプラグイン開発の始め方を示しています。

プラグインは何ができるの？

Jenkins では拡張ポイントを定義しています。それはビルドシステムのある側面をモデル化したインターフェースもしくは抽象クラスです。これらのインターフェースでは実装する必要があるものを定めており、Jenkins ではプラグインがこの実装にコントリビュートすることを許可しています。拡張ポイントについてもっと知りたい場合はこのドキュメントを見てください。

このドキュメントでは、ビルダー を実装してhelloと出力します。（ビルトインのビルダーはAnt, Maven, シェルスクリプトを含みます。ビルダーはプロジェクトをビルドします。）

他のリソース

このチュートリアル以外にも他のチュートリアルや例を下記から参照することができます。

• Stephen Connolly's 7 part tutorial (Writing a Hudson plugin)
  • Part 1 - Preparation
  • Part 2 - Understanding m2 and freestyle projects
  • Part 3 - Subcontracting for Publisher and MavenReporter
  • Part 4 - Abstract Publishers and MavenReporters
  • Part 5 - Reporting
  • Part 5½ - Typos corrected
  • Part 6 - Parsing the results
  • Part 7 - Putting it all together
  • yet not finished: health reports
• 日本語でのクイックスタートガイド
• The JenkinsPluginTotallySimpelGuide by martinO

環境の準備

プラグインを開発するためには Maven 2 (なぜ?) と JDK 6.0以降が必要です。もしMavenを使うのが初めてならインターネットから資料をダウンロードして確認してみてください。.

比較的新しいMaven（つまり2.0.9以降）で下記の記述を ~/.m2/settings.xml (Windowsユーザなら %USERPROFILE%\.m2\settings.xml です)に追加してください。

<settings>
  <pluginGroups>
    <pluginGroup>org.jenkins-ci.tools</pluginGroup>
  </pluginGroups>

  <profiles>
    <!-- Give access to Jenkins plugins -->
    <profile>
      <id>jenkins</id>
      <activation>
        <activeByDefault>true</activeByDefault> <!-- change this to false, if you don't like to have it on per default -->
      </activation>
      <repositories>
        <repository>
          <id>repo.jenkins-ci.org</id>
          <url>http://repo.jenkins-ci.org/public/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>repo.jenkins-ci.org</id>
          <url>http://repo.jenkins-ci.org/public/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>

ここではJenkins Mavenプラグインの略称を使います（つまりorg.jenkins-ci.tools:maven-hpi-plugin:1.61:createの代わりにhpi:create）。

新規プラグインの作成

新規プラグインを作るためには以下のようにmavenコマンドを実行します。

$ mvn -cpu hpi:create

ここでいくつか質問されます。それはgroupId（これはmaven用語でパッケージ名です）やartifactId（これはmaven用語でプロジェクト名です）といったものです。そして開発するプラグインのスケルトンが生成されます。これをビルドして確認してみましょう。

$ cd newly-created-directory
$ mvn package

説明:

-cpu 関連あるMavenプラグインをすべて更新します。
hpi: プラグイン開発を支援するJenkins HPIプラグインの一部を起動する次に示すゴールを特定するサフィックス
create ディレクトリレイアウトと新規Jenkinsプラグインのpomを生成しモジュールリストに加えるゴール
package すべてのソースをコンパイルし、テストをはしらせ、パッケージを作る( *.hpiを作ってHPIプラグインによって上書きされます) 標準的なゴールです。

プラグインのビルド

下記のように、 mv install コマンドを利用して、プラグインがビルドできます。この結果、 ./target/pluginname.hpi というファイルが出来ます。こちらはJenkinsへのDeployの際に利用します。

$ mvn install

IDEでの生産的な環境の作り方

NetBeans

NetBeansユーザはプロジェクトディレクトリを開くことによりIDEのMavenサポートを受けることができます（6.7以降にバンドルされています。6.5ではプラグインマネージャから利用可能です）。アーキタイプも新規プロジェクトダイアログから利用可能です。

IntelliJ IDEA

IntelliJ7.0以降のユーザはIDEからpom.xmlをロードすることができます。ライブラリやJenkins coreのコードを隅々まで見るとよいでしょう。

Eclipse

Eclipse 3.2にはバグ (詳細.)があるのでEclipse3.3以降を使いましょう。
Eclipseユーザは以下のMavenコマンドを走らせることによってEclipseのプロジェクトファイル（カスタムのoutputDirectoryパラメータはEclipseでのJSR-269のアノテーションプロセッササポートの欠如に対処するために使われる）を生成することができます。

$ mvn -DdownloadSources=true -DdownloadJavadocs=true -DoutputDirectory=target/eclipse-classes eclipse:eclipse

代替策として、Eclilpseユーザは maven2 eclipse プラグインをインストールしてIDEでMavenプロジェクトディレクトリを開くこともできます。

もし Unable to find a plugin class. Did you put @plugin in javadoc? というエラーメッセージに遭遇したら、これはEclipseとMavenの両方がビルドの出力ディレクトリを使うことが原因です。mavenでビルドする前に mvn clean を実行するか出力先を変更してください。

プラグインのワークスペースのレイアウト

プラグインのワークスペースは以下に示す主要なものから成り立っています。

pom.xml

Mavenはプラグインをビルドするためにこれを使います。

src/main/java

プラグインのJavaソースファイル

src/main/resources

プラグインのJelly/Groobyビュー　詳細はこのドキュメント を見てください。

src/main/webapp

イメージやHTMLファイルなどプラグインの静的なリソース

ソースコード

ソースコードを見てみましょう。プラグインのメインエントリポイントは Pluginを継承したPluginImplクラスです。Jenkinsは ( Plugin から継承関係を経由して)プラグインクラスを検出すると、インスタンスを作成しメソッドを呼び出します。

多くの場合プラグインクラスは単に 拡張ポイントを登録してるだけです。あなたのメインの仕事は拡張ポイントを実装することです。詳しくは ビルダー がどう実装されているか何をしているかソースコードを読んでみてください。

プラグインのデバッグ

NetBeans 6.7以降のユーザは単に*デバッグ*と押すだけです。他の人はあなたのプラグイン付きのJenkinsを起動するために以下のコマンドを実行してください。
簡易版:

mvnDebug hpi:run

Unix:

$ export MAVEN_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n"
$mvn hpi:run

Windows:

> set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n
> mvn hpi:run

ブラウザで http://localhost:8080/ にアクセスすればJetty上のJenkinsページを見れるはずです。 MAVEN_OPTS の役割はデバッガポート8000ですべてを起動するためのものです。こうすればIDEからこのポートへデバッグセッションを開始することができます。

いったん起動したら実行しつづけます。Jettyは変更を自動的に検知します。

1. src/main/resources にあるビューファイルや src/main/webapp のリソースファイルを変更した場合は, ブラウザでF5を押して変更を見てください。
2. Javaソースファイルを変更した場合は、IDE でコンパイル(NetBeans 6.7+: デバッグ > コードの変更の適用)してください。Jettyは変更を検知して自動的に再デプロイします。 mvn を実行する必要はありません。

   MAVEN_OPTSは -Xmx のような他のJVMパラメータを指定するのに使用することができます。

ポートの変更

Jenkinsを8080以外のポートで起動する必要があるならシステムプロパティ port にセットしてください。

$ mvn hpi:run -Djetty.port=8090

コンテキストパスの設定

maven-hpi-plugin 1.65 以降 (parent pom が 1.401 以降) では、system propertyを利用して、コンテキストパスを指定できます。

$ mvn hpi:run -Dhpi.prefix=/jenkins

プラグインの配布

プラグインの配布イメージを作るには以下のようにMavenゴールを実行してください。

$ mvn package

これにより target/*.hpi ファイルを作成できます。他のユーザはJenkinsのweb UIを使ってこのプラグインをJenkinsにアップロードすることができます。 (もしくは $JENKINS_HOME/plugins に配置してください。)

プラグインのjenkins-ci.orgへのホスティング

ここまできたらあなたのプラグインをjenkins-ci.orgにホスティングすることを考えるべきでしょう。やり方は このドキュメントをみるといいでしょう。

他のtips

1. 毎回リポジトリにアクセスするのをさけるために mvn -o ... のようにMavenを実行することを考えましょう。そうすれば操作が早くなって快適になります。
2. ここからたどれる users を購読しましょう。そうすれば我々も君にアクセスできます。
3. あなたが依存しているJenkinsのバージョンがあがった場合は、いったん mvn clean を実行しましょう。そしてjettyが使っている target/work を削除しましょう。新しいバージョンはworkを使います。target/workは使いません。　そうしないとjettyが古い残ったjarファイルを使い続けるかもしれないです。