Basic CLI Plugin

Introduction

This basic tutorial provides instructions to create a Basic CLI Plugin called SampleGradle that demonstrates how a plugin can be used to automate interaction with an application using command line executable. The showcase includes usage of the ComponentManager and a CLI component.

Prerequisites

These are assumptions for this Tutorial.

Introductory Tutorial has been completed.
pdk is installed and setup.
An active CloudBees CD/RO instance.
Git and Java Runtime Environment installed on the CloudBees CD/RO host.
Internet connection.
A GitHub account.

Step 1 : Generate a plugin using sample spec fromGitHub

After making sure pdk is available in your PATH, create a plugin workspace, typing the name SampleGradle and plugin language groovy for the plugin. Copy pluginspec.yaml from the cloned repository to the config directory of your plugin and generate the plugin.

cd ~/work
git clone https://github.com/electric-cloud-community/flowpdf  ~/temp/flowpdf
pdk generate workspace
cp ~/temp/flowpdf/groovy/SampleGradle/config/pluginspec.yaml SampleGradle/config
cd SampleGradle
pdk generate plugin▼

You can examine the generated plugin structure. There is a procedure called 'RunGradle' that we will use to perform the Gradle activities.

Step 2 : Add the plugin procedure logic

Open dsl/properties/groovy/lib/SampleGradle.groovy.

Import the ComponentManager class and the cli package

import com.cloudbees.flowpdf.components.ComponentManager
import com.cloudbees.flowpdf.components.cli.*▼

Copy the the runGradle method from given sample code and replace the method.

def runGradle(StepParameters p, StepResult sr) {
    /** Reading parameters */
    String tasksRaw = p.getRequiredParameter('tasks').getValue() as String
    String optionsRaw = p.getParameter('options').getValue() as String
    String workspaceDir = p.getParameter('workspaceDir').getValue() as String
    boolean useWrapper = p.getParameter('useWrapper').getValue() as boolean
    boolean saveLogs = p.getParameter('saveLogs').getValue() as boolean

    /** Processing the parameters*/
    ArrayList<String> tasks = tasksRaw.split(' ')
    ArrayList<String> options = optionsRaw.split(';')

    String executableName = 'gradle'
    if (useWrapper) {
        executableName = (CLI.isWindows()) ? 'gradlew.bat' : './gradlew'
    }

    if (!workspaceDir) {
        workspaceDir = System.getProperty('user.dir')
    }

    /** Instantiating CLI component with a ComponentManager */
    CLI cli = (CLI) ComponentManager.loadComponent(CLI.class, [workingDirectory: workspaceDir], this)

    /** Creating a Command instance */
    Command cmd = cli.newCommand(executableName, tasks)

    if (options.size() > 0) {
        cmd.addArguments(options)
    }

    log.infoDiag("Command to run is " + cmd.renderCommand().command().join(' '))

    try {
        ExecutionResult result = cli.runCommand(cmd)

        if (saveLogs) {
            String stdOut = result.getStdOut()
            String stdErr = result.getStdErr()

            if (stdOut)
                sr.setOutcomeProperty('/myJob/gradleStdOut', result.getStdOut())

            if (stdErr)
                sr.setOutcomeProperty('/myJob/gradleStdErr', result.getStdErr())
        }

        if (!result.isSuccess()) {
            log.errorDiag("Standard output: " + result.getStdOut())
            log.errorDiag("Standard err: " + result.getStdErr())
            sr.setJobStepOutcome('error')
        }

        sr.setJobStepSummary('All tasks have been finished.')
    }
    catch (Exception ex) {
        ex.printStackTrace()
        sr.setJobStepOutcome('error')
        sr.setJobStepSummary(ex.getMessage())
    }

    log.info("Finished")
    sr.apply()
}▼

Step 3 : Build, Install, and Promote the Plugin

Use flowpdk to build the plugin. Install the zip in CloudBees CD/RO and promote it.

Step 4 : Use Plugin to performGradle run

Prepare the Gradle project on the CloudBees CD/RO host:

Preparing the Gradle project on the CloudBees CD/RO host is required to run plugin on the local agent and is only intended for simplicity. If you are familiar with agents, you can use any host with a Java capability.

git clone https://github.com/electric-cloud-community/gradle-test-build /tmp/gradle-test-build
chown -R build /tmp/gradle-test-build▼

Create new pipeline. Refer to /pdfgroovy/tutorialintroductory if you need help with creating a pipeline.

Add a task for SampleGradle:Run Gradle to the default stage with following parameter values:

Tasks: build
Options: -PtestMessage="SampleGradle Tutorial";--no-daemon
Workspace Dir: /tmp/gradle-test-build
Use Wrapper?: yes (checked)
Save Log?: yes (checked)

Now run the pipeline and wait for it to finish:

You can open job details and see the build output in a job property:

Step 5 : Summary

This Summary is provided in order to help a Developer conceptualize the steps involved in the creation of this plugin.

Specification

pluginspec.yaml provides the declarative interface for the plugin procedure RunGradle.

Generated Code

All the plugin boilerplate code was generated by the flowpdk. The only thing we had to change was the step logic.

User Modifications

Implemented logic for parsing parameter values, running the command and capturing the results.
Using ComponentManager to instantiate CLI component instance

Used Libraries
Package com.cloudbees.flowpdf.components.cli.
Component Manager.
Component.