Jenkins插件开发手册.docx

Jenkins插件开发搭建开发环境为了能开发插件，开发环境需要安装Maven和JDK 6.0以上版本。1、安装JDK打开cmd， 输入java version如下图，说明安装完成。图1如果没安装，点击链接/article/bea41d435bc695b4c41be648.html2、安装Maven1. 下载Maven /download.html如下图：图2将安装包解压到任意地址，我的路径是D:apache-maven-3.0.5新建环境变量M2_HOME 指向D:apache-maven-3.0.5在path添加路径%M2_HOME%bin打开cmd 输入mvn v，如下图：图3安装成功。给eclipse安装插件m2eclipse。1、 打开eclipse2、 Help-Install New Software出现下图：图43、 点击Add图5在name输入 m2e在Location输入 /sites/m2e4、 确定后出现下图：图65、 勾选Maven Integration for Eclipse6、 然后一直下一步直到安装完毕7、 检查是否安装成功（1） 点击Help about eclipse installation details,看是否存在Maven Integration for Eclipse(Required),如下图：图7（2） 再检查eclipse是否可以创建Maven项目了，File-New-Other图8到此Maven安装完成了。3、安装jenkins下载jenkins 链接/将jenkins.war，拷贝到D:jenkins下，打开cmd，转到D:jenkins目录下然后运行java jar jenkins.war最后出现jenkins is fully up an running。说明安装成功。访问http:/localhost:8080界面如下图：图9插件开发流程1、设置环境由于是使用maven进行开发，需要对%USERPROFILE%.m2settings.xml（USERPROFILE为用户名路径如C:Documents and Settings下的用户）文件添加以下内容： org.jenkins-ci.tools jenkins true /public/ /public/ /public/ m.g.o-public 这将可以使用缩短的命令来执行运行。2、生成新的插件开发新的插件，执行以下命令：mvn U hpi:create将会提示出现需要输入groupid和artifactid，如下：groupid：com.jysong.jenkinsartifactid: newplugin这样便生成了新的插件，会生成一个简单的例子，同时在当前目录下生成新的文件夹newplugin，然后再执行下面的命令。cd newpluginmvn package使用这个命令将工程进行打包，不过由于版本的不同可能会出现错误。如果出现错误参考下面的源代码部分进行修改。在第一次执行命令时会下载很多的文件，需要耐心的等待。3、编译插件mvn install运行此命令将会生成文件 ./target/newplugin.hpi。可以把它加载到jenkins中。并且将./target/newplugin.hpi、pom.xml、./target/newplugin.jar这几个文件安装到maven的本地仓库中，就可以被其他的工程调用了。也可以使用mvn package,只是进行打包生成所需文件，并不安装到本地仓库中。4、为IDE设置开发环境使用eclipse进行代码开发。mvn -DdownloadSources=true -DdownloadJavadocs=true DoutputDirectory= target/eclipse-classes eclipse:eclipse或者mvn eclipse:eclipse在此目录中生成eclipse工程，可以使用eclipse将工程进行导入。如下图：图105、工作空间布局导入之后目录结构如下图：图11src/main/java :存放java源文件。src/main/resources：jelly/Groovy视图文件。src/main/webapp：静态资源文件，例如图片，HTML文件。pom.xml：配置文件，Maven使用此文件编译插件。6、源代码由于版本的不同，在src/main/java/com/jysong/jenkins目录下可能有个null文件夹，在文件夹下面有HelloWorldBuilder.java文件，将HelloWorldBuilder.java文件拷贝到jenkins文件夹下面，将null文件夹删除。并且将HelloWorldBuilder.java文件中的第一行的package最后面的.null删除。HelloWorldBuilder.java文件是一个开发插件的模板，包含了开发一个简单插件的所有内容。后面将对这个文件代码进行详细分析。在src/main/resources/com/jysong/jenkins目录下可能有个null文件夹，在文件夹下面有个HelloWorldBuilder文件夹，将HelloWorldBuilder文件夹拷贝到jenkins文件夹下面，将null文件夹删除。在HelloWorldBuilder文件夹下面有global.jelly和config.jelly配置文件。这两个文件是进行页面配置的文件。7、调试插件在windows系统上，执行以下命令：set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket, server=y, address =8000, suspend=nmvn hpi:run使用http:/localhost:8080/在浏览器中登录，将会看到jenkins页在Jetty中运行。MAVEN_OPTS启动了端口为8000的调试器，可以在这个端口开启一个调试会话。如果8080的端口被占用，将会出现错误，不会运行jetty服务器。可以更改端口使用以下命令：mvn hpi:run Djetty.port=8090可以使用http:/localhost:8090/进行登录了。设置上下文路径mvn hpi:run Dhpi.prefix=/jenkins执行这个命令之后登录地址将变为http:/localhost:8090/jenkins8、发布插件运行以下命令，生成你的插件的图片。mvn package生成 ./target/*.hpi文件，其他使用者可以使用jenkins的web界面上传到jenkins。9、安装插件在jenkins的web界面中由Manage JenkinsManage PluginsAdvanced图12点击Choose File,选择你的插件的target目录下的hpi文件。选择之后点击Upload，插件就会配置到jenkins中。到此一个简单的插件开发完成了，可以在此基础上进行更复杂的开发。详细开发插件流程的地址/display/JENKINS/Plugin+tutorial源码分析1、java源代码在目录src/main/java/com/jysong/jenkins下有文件HelloWorldBuilder.java。代码如下：public class HelloWorldBuilder extends Builder private final String name; / Fields in config.jelly must match the parameter names in the DataBoundConstructor DataBoundConstructor public HelloWorldBuilder(String name) = name; /* * Well use this from the config.jelly. */ public String getName() return name; Override public boolean perform(AbstractBuild build, Launcher launcher, BuildListener listener) / This is where you build the project. / Since this is a dummy, we just say hello world and call that a build. / This also shows how you can consult the global configuration of the builder if (getDescriptor().getUseFrench() listener.getLogger().println(Bonjour, +name+!); else listener.getLogger().println(Hello, +name+!); return true; / Overridden for better type safety. / If your plugin doesnt really define any property on Descriptor, / you dont have to do this. Override public DescriptorImpl getDescriptor() return (DescriptorImpl)super.getDescriptor(); /* * Descriptor for link HelloWorldBuilder. Used as a singleton. * The class is marked as public so that it can be accessed from views. * * * See src/main/resources/hudson/plugins/hello_world/HelloWorldBuilder/*.jelly * for the actual HTML fragment for the configuration screen. */ Extension / This indicates to Jenkins that this is an implementation of an extension point. public static final class DescriptorImpl extends BuildStepDescriptor /* * To persist global configuration information, * simply store it in a field and call save(). * * * If you dont want fields to be persisted, use transient. */ private boolean useFrench; /* * Performs on-the-fly validation of the form field name. * * param value * This parameter receives the value that the user has typed. * return * Indicates the outcome of the validation. This is sent to the browser. */ 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(Isnt the name too short?); return FormValidation.ok(); public boolean isApplicable(Class aClass) / Indicates that this builder can be used with all kinds of project types return true; /* * This human readable name is used in the configuration screen. */ public String getDisplayName() return Say hello world; Override public boolean configure(StaplerRequest req, JSONObject formData) throws FormException / To persist global configuration information, / set that to properties and call save(). useFrench = formData.getBoolean(useFrench); / Can also use req.bindJSON(this, formData); / (easier when there are many fields; need set* methods for this, like setUseFrench) save(); return super.configure(req,formData); /* * This method returns true if the global configuration says we should speak French. * * The method name is bit awkward because global.jelly calls this method to determine * the initial state of the checkbox by the naming convention. */ public boolean getUseFrench() return useFrench; 这里主要使用了jenkins的Builder作为扩展点，Builder扩展点是编译时的功能。更多扩展点/display/JENKINS/Extension+points。HelloWorldBuilder类中的构造函数使用DataBoundConstructor来声明。构造函数要对变量进行赋值。HelloWorldBuilder类中perform重载函数。构建的执行通过实现perform方法来进行自定义。每次执行编译时都会运行perform函数。它有三个参数：Build参数是描述了当前任务的一次构建，通过它可以访问到一些比较重要的模型对象如：project当前项目的对象、workspace构建的工作空间、Result当前构建步骤的结果。Launcher参数用于启动构建。BuildListener该接口用于检查构建过程的状态（开始、失败、成功.），通过它可以在构建过程中发送一些控制台信息给jenkins。perform方法的返回值告诉jenkins当前步骤是否成功，如果失败了jenkins将放弃后续的步骤。在这个例子中if.else.语句是向控制台端输出日志信息，其中name的信息由构造函数有关。将if.else.语句进行删除，添加以下代码。int number = build.getNumber();String version = build.getHudsonVersion();Calendar startedTime = build.getTimestamp();SimpleDateFormat simpleDateFormat = new SimpleDateFormat (yyyy-MM-ddTHH:mm:ss.SSSZ);String started = simpleDateFormat.format (startedTime.getTime();String durationMillis = build.getDuration();String log = build.getLog();String fileName = D:workspacenewpluginBuildLog + number + .txt;String content;content = version + nt + name + nt+ started + nt+ durationMillis + nt+ log;tryFileWriter writer = new FileWriter(fileName,true);writer.write(content);writer.close();catch(IOException e)e.printStackTrace();这段代码是获得编译时的一些信息，然后输出到一个文本文件中。其中AbstractBuild类包含了编译的大部分的信息，可以查看API获得更详细的信息 / Hudson.model.AbstractBuild。此外有一个内部静态类DescriptorImpl，该类通过Extension声明告诉jenkins，告诉系统该内部类是作为BuildStepDescriptor的扩展出现。有以下几个方法。isApplicable方法，是否对所有项目类型可用。其他的方法和配置文件有关，在下面介绍配置文件时在详细说明。2、视图配置文件Jenkins使用了Jelly页面渲染技术，这是一个基于XML的服务端页面渲染引擎，其将基于Jelly的xml标签转换为对应的Html标签并输出到客户端。模型对象的信息通过Jexl表达式被传递到页面上（相当于Jsp的JSTL）。jelly文件以.jelly为后缀，在hudson中使用类全名的形式来查找模型类对应的jelly页面文件，如名为src/main/java/com/jysong/jenkins/HelloWorldBuilder.java的类，其对应的页面文件应该存在于src/main/resources/com/jysong/jenkins/HelloWorldBuilder目录的下。此外hudson通过固定的命名方式来确定页面文件属于局部配置还是全局配置：config.jelly提供局部配置；global.jelly提供全局配置。config.jelly是具体的某个job的配置，global.jelly是指jenkins的系统配置。视图有三种:1,全局配置(global.jelly)2,Job配置(config.jelly),还有就是使用帮助(help-字段名).html1、 全局配置详解global.jelly为全局配置页面。 !- This Jelly script is used to produce the global configuration option. Jenkins uses a set of tag libraries to provide uniformity in forms. To determine where this tag is defined, first check the namespace URI, and then look under $JENKINS/views/. For example, is defined in $JENKINS/views/lib/form/section.jelly. Its also often useful to just check other similar scripts to see what tags they use. Views are always organized according to its owner class, so it should be straightforward to find them. - 其中title为标题，表示要显示的内容。field为将调用DescriptorImpl内部类的方法getUseFrench()，field域会将方法去掉get并且将第一个字母小写，找到相对应的方法。description将显示描述信息。f:checkbox为复选框控件。在每次保存全局配置时，jenkins都会调用该descriptor对象，并调用其configure方法，可以实现该方法并提供自己的定制在DescriptorImpl中的configure方法中，可以对全局配置进行操作。save方法用于将当前Descriptor所提供的配置持久化（通过get*方法），为了使save能正常工作，需要提供配置项的get方法。2、 局部配置详解config.jelly 的内容将被包含在扩展功能的配置中，在HelloWorldBuilder文件夹下面的配置内容是： 其中entry 表示用于交互的html表单域，title将作为表单域label的值，在界面中要显示的内容。 field表示的是HelloWorldBuilder的构造函数中的参数。如果有多个field，就要有多个相对应的参数。textbox 表示简单的渲染一个输入文本，输入的值将赋给name。将插件部署到jenkins后实际效果如下图：图13选择Say hello world，图14Say hello world是由于在DescriptorImpl内部类中有方法getDisplayName()，此方法返回的字符串作为pre-build step的名称。在DescriptorImpl内部类中doCheckName(QueryParameter String value)方法，在光标不再在输入框时，将执行这个方法，其中输入框的输入值以value值传入，在这个函数里可以进行验证，是否符合输入条件。允许为表单域增加帮助说明（在页面上对应于文本框后面出现问号按钮，一点击可出现提示）： 在同名目录下有help-fileName.html，在该文件中添加帮助内容；帮助内容允许是动态的，即可以从模型中拉取信息进行显示，这需要将html后缀改为jelly，而help-name.html文件的形式大致如下： Help file for fields are discovered through a file name convention. This file is help for the name field. You can have arbitrary HTML here. You can write this file as a Jelly script if you need a dynamic content (but if you do so, change the extension to .jelly).在输入框中输入相对目录。测试案例在此基础之上，实现一个简单的案例。1、编写代码在HelloWorldBuilder类中的perform方法中，添加代码：FilePath workspace = build.getWorkspace();String filePath = workspace.toString() + + path;File files = new File(filePath);File fileList = files.listFiles();String strFile = ;for(int i=0;ifileList.length;i+)strFile += fileListi.getName() + n;