This section describes the basic architecture of an SCM plugin.
All SCM plugins are subclasses of hudson.scm.SCM. This class has a few methods that an SCM implementation will want to override:
Including createChangeLogParser which is abstract and has to be overridden:
The basic means of interaction between the plugin and the rest of hudson are the compareRemoteRevisionWith and checkout methods, which are used, respectively, to poll the SCM for changes and to check out updated files. The createChangeLogParser method is supposed to return something that can parse an XML file with change set information.
Create the configuration options as normal fields, by adding fields to the SCM class they will be persisted when Hudson is stopped and started. If you have a field that should not be persisted to XML it should be marked as transient.
The following sections describe the methods of the SCM class in more detail.
Create a constructor that takes non-transient fields, and add the annotation @DataBoundConstructor to it. Using the annotation helps the Stapler class to find which constructor that should be used when automatically copying values from a web form to a class.
The compareRemoteRevisionWith method is expected to return if there has been any changes on the SCM repository or not in the form of a PollingResult object. It is up to the plug-in developer to create a new SCMRevisionState from the remote repository, and compare this with the baseline SCMRevisionState to determine whether there are changes (which lets Jenkins know it should checkout and build or not). It is also up to the developer to extend the SCMRevisionState class with details specific to the SCM system, and to provide a way to compare objects of this class. This example shows what a very basic compareRemoteRevisionsWith might look like if SCMRevisionState is extended by class MyCustomRevisionState which has method isNewerThan for comparing two MyCustomRevisionState.
The checkout method is expected to check out modified files into the project workspace. As a checkout is generally the first step for a build, the build object is made available. Also, the former SCMRevisionState, baseline is made available.
While calcRevisionsFromBuild is designed to generate the SCMRevisionState, there is also the option of having checkout generate this state and having calcRevisionsFromBuild returning null. This is particularly useful if the generation of the SCMRevisionState overlaps with the checkout process and you want to optimize performance.
Simply set calcRevisionsFromBuild to return null, and add your SCMRevisionState to build during checkout:
Since you have access to your build, you can even add build parameters to your build during checkout. This is useful if you want to pass some information (like a version number) acquired during the polling process to a build job.
This method is called after checkout and generates and returns a SCMRevisionState, presumably based on the state of the workspace. Alternatively, this method can be set to return null and checkout can add SCMRevisionState to the build as an action.
The checkout method should, besides checking out the modified files, write a changelog.xml file that contains the changes for a certain build. The changelog.xml file is specific for each SCM implementation, and the createChangeLogParser returns a parser that can parse the file and return a ChangeLogSet. See below section for more information.
Returns the ScmDescriptor<?> for the SCM object. The ScmDescriptor is used to create new instances of the SCM. For more information see next section.
The relationship of Descriptor and SCM (the describable) is akin to class and object. What this means is that the descriptor is used to create instances of the describable. Usually the Descriptor is an internal class in the SCM class named DescriptorImpl. The Descriptor should also contain the global configuration options as fields, just like the SCM class contains the configurations options for a job. The @Extension annotation tells Jenkins to register the descriptor.
Methods that will be overriden
Returns the name of the SCM, this is the name that will show up next to CVS and Subversion when configuring a job.
The method is invoked when the global configuration page is submitted. In the method the data in the web form should be copied to the Descriptor's fields. To persist the fields to the global configuration XML file, the save() method must be called. Data is defined in the global.jelly page.
The jelly files for the Descriptor go into the src/main/resources/hudson/plugins/$plugin-name/$PluginScm/ folder where $plugin-name is the name of your plugin and $PluginScm is the plugin's SCM class implementation. For the Team Foundation Server plugin this path is /src/main/resources/hudson/plugins/tfs/TfsScm. The jelly files are the configuration view for the SCM class.
Contains global configuration that is displayed in system configuration page. Typical configuration parameters that is going to be used by all Hudson jobs, for example the path to the SCM tool.
The field tfs.tfExecutable will be populated with the string from DescriptorImpl.getTfExecutable(). The method should return "tfs" by default.
The field tfs.tfsExecutable will also validate the entered tool path through checkUrl. When the user has entered a path (and moves the focus away from field) Hudson will call DescriptorImpl.doExectuableCheck to validate that the path can be found.
Contains configuration for one Hudson job. Typical configuration parameters that used in a job, such as server URL, etc. The fields in the jelly file should correspond to the fields in the SCM class.
As with the Descriptor the web form fields are populate from the SCM object through properties, the value for "tfs.server" is retrieved from the TeamFoundationServerScm.getServer() method.
The tfs.project field is mandatory and will display an error text below it if the field is empty. The error text is defined by the checkUrl attribute, and can be also used to validate numbers. The checkUrl can be used for more advanced validating such as testing the server if it exists and needs credentials.
For each entry in a jelly file that has a help attribute Hudson will display a help icon to the right. When the icon is clicked the named HTML page will be inlined just below the entry field. The HTML page must reside in the src/main/webapp folder.
Skip to end of metadata Go to start of metadata