开始第一个Jenkins Plugin

Posted on Edited on In Views:

一 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生成的文件结构如下：

1
2
3
4
5
6
7
8
9
+- src
|	+- main
|	|	+- java
|	|	|	+- groupId.HelloWorldBuilder.java
|	|	+- resources
|	|	|	+-  groupId.HelloWorldBuilder
 |	|	|	|	+- config.jelly
 |	|	|	|	+- help-name.html
|	|	|	+- index.jelly

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

2.2.2 代码的解释

数据的绑定：

1
2
3
4
<!--config.jelly-->
<f:entry title="Name" field="name">
	<f:textbox />
</f:entry>
1
2
3
4
5
//--HelloWorldBuilder.java--
@DataBoundConstructor
public HelloWorldBuilder(String name) {
    this.name = name;
}

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

Jenkins插件任务的执行

1
2
3
4
5
6
7
8
@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
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