オリジナル: 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を使うのが初めてならインターネットから資料をダウンロードして確認してみてください。.
Nexus ユーザーの場合:
Nexus Maven Repository Manager を利用している場合、この手順をする必要はありません。そのかわりに、こちら に従って、事前準備と適切な settings.xml
を用意してください。
比較的新しい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)。
Maven2.0.9より古いバージョンを使っている場合は、さらに 追加のステップが必要です。
新規プラグインの作成
新規プラグインを作るためには以下のように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のコードを隅々まで見るとよいでしょう。
IntelliJのMavenはデフォルトでソースとJavaDocをオンデマンドにダウンロードします。だからソースを見るためには Maven Projects
タブにある Download artifacts
ボタンをクリックする必要があります。
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は変更を自動的に検知します。
src/main/resources
にあるビューファイルやsrc/main/webapp
のリソースファイルを変更した場合は, ブラウザでF5を押して変更を見てください。- 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
- 毎回リポジトリにアクセスするのをさけるために
mvn -o ...
のようにMavenを実行することを考えましょう。そうすれば操作が早くなって快適になります。 - ここからたどれる users を購読しましょう。そうすれば我々も君にアクセスできます。
- あなたが依存しているJenkinsのバージョンがあがった場合は、いったん
mvn clean
を実行しましょう。そしてjettyが使っているtarget/work
を削除しましょう。新しいバージョンはworkを使います。target/workは使いません。 そうしないとjettyが古い残ったjarファイルを使い続けるかもしれないです。
Comments:
Not tolerance of others, is unworthy of tolerance by others,louis vuitton outlet but who can say oneself is not to need tolerant?
Posted by at Dec 07, 2010 17:23
|