This tutorial describes the way of creating Gradle standalone custom plugin. It covers the following topics

  • Creating task, and using it in Custom plugin
  • Stand alone Custom plugin
  • Short plugin id
  • Customize Gradle setting using settings.gradle

Project info :
Gradle version : 1.1
OS platform : Ubuntu 12.10
Prerequisite : Basic understanding of Gradle script.

Creating the Stand alone custom plugin

  1. create the directory structure

       |-custom-plugin
       |  |-plugin
       |    |-src
       |      |-main
       |      |  |-groovy
       |      |  | |-com
       |      |  |   |-code4reference 
       |      |  |     |-gradle
       |      |  |-resources   
       |      |  | |-META-INF
       |      |  |   |-gradle-plugins 
       |      |-test
       |      |  |-groovy
       |      |  | |-com
       |      |  |   |-code4reference 
       |      |  |     |-gradle 
       |-user

    Here plugin directory contains all source code and resource files whereas the user directory contains the consumer script which uses custom plugin. Execute the following command to create the directory structure. Here groovy folder contains the source code package.

      $ mkdir -p custom-plugin/plugin/src/main/groovy/com/code4reference/gradle
      $ mkdir -p custom-plugin/plugin/src/main/resources/META-INF/gradle-plugins
      $ mkdir -p custom-plugin/user
      
  2. Custom plugin source code

    Every plugin should have a implementation class to extend the Plugin class. Let’s define the plugin class.

    package com.code4reference.gradle;
    
    import org.gradle.api.*;
    
    class Code4ReferencePlugin implements Plugin {
        def void apply(Project project) {
            //c4rTask task has been defined below.
            project.task('c4rTask') << {
                println "Hi from Code4Reference plugin!"
            }
        }
    }
      

    Put this file in custom-plugin/plugin/src/main/groovy/com/code4reference/gradle directory. Here, c4rTask task has been defined to print a simple line.

  3. Short plugin ID

    In order to apply a plugin, we usually use a short ID e.g apply plugin : ‘java’. Here ‘java’ is the short plugin id for the class org.gradle.api.plugins.JavaPlugin. The short plugin id can be defined in easy steps. For this, we need to create a property file and put it in the META-INF/gradle-plugins directory which comes under the class path. The name of the file will be our short id. This property file must contain the line shown below and it should point to the plugin implementation class. Let’s create the property file as code4reference.properties and point it to the Code4ReferencePlugin class.

       implementation-class=com.code4reference.gradle.Code4ReferencePlugin
      
  4. Gradle script to generate the plugin

    For compiling and building this plugin, we will write the gradle script. Create the file named build.gradle in plugin directory and copy the content below in it.

    apply plugin: 'groovy'
    apply plugin: 'maven'
    dependencies {
        compile gradleApi()
        groovy localGroovy()
    }
    repositories {
        mavenCentral()
    }
    
    group='com.code4reference'   //Group name makes easier to manager the packages.
    version='1.1-SNAPSHOT'
    
    uploadArchives {
        repositories {
            mavenDeployer {
                repository(url: uri('../repo'))
            }
        }
    }
      

    In this gradle script, we use groovy plugin to compile groovy source code and declare gradleAPI as the compile time dependencies. You may have noticed that we use maven plugin. It basically creates the plugin jar file and stores in the maven repository. Here we create the maven repository named repo in the parent directory and store the jar file in it.

  5. Building plugin and putting in repository

     $ gradle uploadArchives   #This will put the plugin-version.jar in maven repository.
    
    :compileJava UP-TO-DATE
    :compileGroovy UP-TO-DATE
    :processResources UP-TO-DATE
    :classes UP-TO-DATE
    :jar
    :uploadArchives
    Uploading: com/code4reference/plugin/1.1-SNAPSHOT/plugin-1.1-20120816.163101-1.jar to repository remote at file:/home/rakesh/programming/mygitrepo/Code4Reference/GradleExample/custom-plugin-1/repo/
    Transferring 5K from remote
    Uploaded 5K
    
    BUILD SUCCESSFUL
    
    Total time: 34.892 secs
     
  6. Porject settings using settings.gradle

    When the above command is executed, gradle tires to get the project name from the settings.gradle. If settings.gradle file is not present in the current directory, then it gets the name of the current directory and assumes it as the project name.  It then forms the path to store the jar file. The file path convention is as following /group/name/projectName/version/projectname-version-timestamp.jar. You may notice in the above output that the jar path name and the jar file name have plugin word because the the current directory name is plugin and gradle assumes it as project name. If we want to override this property and put code4ReferencePlugin as the project name, we need to create a settings.gradle file in the plugin directory and put the following line.

    rootProject.name = 'code4ReferencePlugin'
    

    Now again execute the command to generate the plugin jar file.

    $gradle uploadArchives
    compileJava UP-TO-DATE
    :compileGroovy UP-TO-DATE
    :processResources UP-TO-DATE
    :classes UP-TO-DATE
    :jar UP-TO-DATE
    :uploadArchives
    Uploading: com/code4reference/code4ReferencePlugin/1.1-SNAPSHOT/code4ReferencePlugin-1.1-20120816.164441-5.jar to repository remote at file:/home/rakesh/programming/mygitrepo/Code4Reference/GradleExample/custom-plugin-1/repo/
    Transferring 5K from remote
    Uploaded 5K
    
    BUILD SUCCESSFUL
    
    Total time: 8.61 secs
    

    Now the problem is solved. The jar is getting generated with name code4ReferencePlugin-[version]-timestamp.jar . If you want to find more about the gradle and system properties, find it here.

Using the custom plugin

This is really a simple step. Although we use the other plugin, the custom plugin can also be used in similar way. Now create another build.gradle file in user directory and copy the code given below.

buildscript {
    repositories {
        maven {
            url uri('../repo')
        }
    }
    dependencies {
        classpath group: 'com.code4reference',
                  name: 'code4ReferencePlugin',
                  version: '1.1-SNAPSHOT'
    }
}
apply plugin: 'code4reference'

build.gradle script accesses maven repository present in the parent directory. We have also defined dependency which basically accesses the particular version of jar file from the maven. Last but not the least, we apply the short plugin id “code4reference”. To run this gradle script, execute the command below on the terminal in the user directory.

$ gradle c4rTask   #Remember we have created c4rTask in Code4ReferencePlugin class.
                   #You will get the following output.
:c4rTask
Hi from Code4Reference plugin!

BUILD SUCCESSFUL

Total time: 3.908 secs

Voilà!! you just created custom plugin and used it in a different project script. You can find the source code for this tutorial over here. In next tutorial, we will learn the following topics

  • Define custom Task class
  • Passing arguments to custom plugin task
  • Testing the custom plugin

Please fill free to comment on the post or the website. Thanks!!!

, ,
Trackback

3 comments untill now

  1. how/where can I get the org.gradle.api.*; to work with my eclipse project??

  2. org.gradle.api.* is part of standard Gradle library. I guess, you should download Gradle from http://www.gradle.org/ and provide reference of library as external library in Eclipse.

  3. I was wondering if you ever thought of changing the page
    layout of your blog? Its very well written; I love what youve got to say.
    But maybe you could a little more in the way of content so people could
    connect with it better. Youve got an awful lot of text for only
    having one or 2 pictures. Maybe you could space it out better?

Add your comment now