开始第一个Jenkins Plugin

一 Jenkins插件的结构

Jenkins插件实际上是一个按照一定规则组织的jar包,其结构如下:

1
2
3
4
5
6
7
8
9
xxx.hpi
+- META-INF
| +-MANIFEST.MF
+- WEB-INF
| +- classes
| +- index.jelly
| +- XXXX.class
| +- lib
+- (static resources)

说明:

  • 1.插件的后缀为”.hpi”,文件名(xxx部分)是插件的简写名字,用来区分插件。
  • 2.如上图结构所示,它与war包类似,只是缺少web.xml。
  • 3.MANIFEST.MF包含一些入口的配置信息。其中有继承自Jenkins插件的类,用作实例化的入口。类的全名,用作我们去区分其他插件。
  • 4.WEB-INF/classes 用来包含插件需要的.class,jelly页面等内容。它们可以封装成jar包放到WEB-INF/lib下面
  • 5.WEB-INF/lib 包含插件中需要的.jar文件
  • 6.插件需要的静态文件如图片,HTML,css样式文件,JS文件等可以放到文件的根目录下面。

    二 Jenkins-Plugins的开发

    Jenkins插件的开发,使用maven来进行项目的管理和构建。如下罗列了其中需要的步骤。

    2.1 Jenkins插件开发时的环境配置

    Jenkins插件开发,需要JDK和Maven环境。下面以windows下的环境配置为例说明。

    2.1.1 JDK配置

    JDK的版本要求在1.6以上,需要在配置文件中配置JDK的变量:

    JAVA_HOME = C:\Program Files (x86)\Java\jdk1.6.0_38
    CLASSPATH = …;%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;
    PATH = …;%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;

2.1.2 Maven的配置

M2_HOME =  D:\maven
M2 = %M2_HOME%\bin
MAVEN_OPTS  = -Xms256m -Xmx512m

CLASSPATH = ...;%M2%
PATH = ...;%M2%

可以通过mvn --version,查看maven是否配置成功。

2.1.3 Maven开发环境的配置

在~/.m2/settings.xml中,或者/maven/conf/settings.xml中,配置如下的Jenkins库依赖:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<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>
<mirrors>
<mirror>
<id>repo.jenkins-ci.org</id>
<url>http://repo.jenkins-ci.org/public/</url>
<mirrorOf>m.g.o-public</mirrorOf>
</mirror>
</mirrors>
</settings>

2.2 生成插件的框架程序

配置好maven后,即可使用maven命令建立插件的框架,并且命令行会提示你输入groupId和artifactId:

mvn hpi:create

Enter the groupId of your plugin: com.baidu.ite.hudson
Enter the artifactId of your plugin: samplePlugin

这样会建立一个工程,名字为samplePlugin,包路径com.baidu.ite.hudson
或者使用如下的命令:

mvn -U org.jenkins-ci.tools:maven-hpi-plugin:create -DgroupId={your.gound.id} -DartifactId={your.plugin.id}

说明:
1,-u代表jenkins需要更新自己所有的插件内容。
2,jenkins中提供的archetype-resources,文件的名字为HelloWorldBuilder.java。我们需要手工修改成自己需要的内容。

2.2.1 代码结构

使用 hpi:create生成的文件结构如下:

+- src
|    +- main
|    |    +- java
|    |    |    +- groupId.HelloWorldBuilder.java
|    |    +- resources
|    |    |    +-  groupId.HelloWorldBuilder
   |    |    |    |    +- config.jelly

​ | | | | +- help-name.html
​ | | | +- index.jelly

Jenkins定义了一些扩展点(Extension Points),这些扩展点是接口或者抽象类。你可以根据自己的需要来修改文件的名字和扩展点。我们使用命令生成的框架程序中,HelloWorldBuilder继承了Builder。

2.2.2 代码的解释

数据的绑定:

<!--config.jelly-->
<f:entry title="Name" field="name">
    <f:textbox />
  </f:entry>

//--HelloWorldBuilder.java--
@DataBoundConstructor
public HelloWorldBuilder(String name) {
    this.name = name;
}

首先,在config.jelly中包含需要传入的参数配置信息的文本框,field为name,这样可以在Jenkins中进行配置,然后通过DataBoundConstructor的方式,传到类中。

Jenkins插件任务的执行

@Override
public boolean perform(AbstractBuild build, Launcher launcher, BuildListener listener) {
    // This is where you 'build' the project.

    // This also shows how you can consult the global configuration of the builder
        listener.getLogger().println("Hello, "+name+"!");
    return true;
}

根据注释可以了解:该处是你在Job进行构建时进行操作的地方,并且这里可以根据你在配置中的设置执行你需要的工作。通常,根据需要修改perform函数即可。

1
2
3
4
5
6
7
8
9
10
传入数据的检查

public FormValidation doCheckName(@QueryParameter String value)
throws IOException, ServletException {
if (value.length() == 0)
return FormValidation.error("Please set a name");
if (value.length() < 4)
return FormValidation.warning("Isn't the name too short?");
return FormValidation.ok();
}

在该函数中,实现在配置页面中填写内容时,进行校验的过程。如函数所述,当填入内容为空时,提示:Please set a name。你可以根据你的需要进行逻辑的控制。

2.3 转换为eclipse工程

为了便于在编辑器中进行修改,我们需要将生成的maven代码转化为eclipse工程,使用的命令如下:

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

第二条较长的命令中,参数是可选的。

2.4 生成hpi文件

使用如下命令可以生成./target/pluginname.hpi:

mvn install
或者
mvn package

其中mvn install 生成hpi文件,并放置到本地maven仓库中,mvn package只进行打包操作。

2.5 使用.hpl进行调试

maven中使用.hpl(hudson plugin link)格式来进行插件的调试。hpl文件中只包含一个链接,链接到类似META-INF/MANIFEST.MF的说明文件../path/to/your/plugin/workspace/manifest-debug.mf。该文件其中额外定义了一些属性来指定文件目录位置,这样资源的修改可以立即生效(需要配置stapler.jelly.noCache=true),不需要重新打包安装。
在maven中可以使用命令:

1
mvn hpi:hpl -DhudsonHome=/...

2.6 使用.hpi进行测试

在调试通过后,可以使用.hpi文件来启动jenkins,查看结果,命令如下:

1
mvn hpi:run -DhudsonHome=/...

说明:-DhudsonHome可以不选,默认Jenkins安装到工程的./target目录中。


致谢:lizejun

申艳超 wechat
欢迎关注微信订阅号~
您的支持是我原创的动力!