• Defining Shared Libraries
• Trusted Versus Untrusted Libraries
• Internal Versus External Libraries
• Library Scope Within Jenkins Items
• Using Libraries
• Loading Libraries
• @Library syntax:
• The libraries directive
• Writing libraries
• Library Structure
• src
• vars
• Defining global variables
• Defining custom steps
• Defining a more structured DSL
• resources
• Using Third-Party Libraries
• Troubleshooting
• Replaying External Code and Libraries
• Sample Library Routine
• Summary
• Reference

Defining Shared Libraries

Trusted Versus Untrusted Libraries

Internal Versus External Libraries

Library Scope Within Jenkins Items

Using Libraries

Loading Libraries

@Library syntax:

• The library name is required.
• The version should be preceded by the @ sign.
• The version can be a tag, branch name, or other specification of a revision in the source code repository.
• Specific subsets of methods can be imported by including an import statement at the end of the annotation or on the next line.
• An import statement is not required. If one is not specified, all methods will be imported.
• If no import statement is specified, then an underscore (_) must be placed at the end of the annotation, directly after the closing parenthesis. (This is required since an annotation needs something to annotate by definition. In this case, the _ is simply serving as a placeholder.)
• Multiple library names (with respective versions if desired) can be specified in the same annotation. Just separate them with commas.

// Load the default version of a library
@Library('myLib')_

// Override the default version and load a specific version of a library
@Library('yourLib@2.0')_

// Accessing multiple libraries with one statement
@Library(['myLib', 'yourLib@master'])_

// Annotation with import
@Library('myLib@1.0') import static org.demo.Utilities.*

The libraries directive

pipeline {
     agent any
     libraries {
        lib("mylib@master")
        lib("alib")
    }

Writing libraries

Library Structure

(root)
+- src                     # Groovy source files
|   +- org
|       +- foo
|           +- Bar.groovy  # for org.foo.Bar class
+- vars
|   +- foo.groovy          # for global 'foo' variable
|   +- foo.txt             # help for 'foo' variable
+- resources               # resource files (external libraries only)
|   +- org
|       +- foo
|           +- bar.json    # static helper data for org.foo.Bar

src

• Library classes cannot directly call steps such as sh or git. They can however implement methods, outside of the scope of an enclosing class, which in turn invoke Pipeline steps, for example:

  // src/org/foo/Zot.groovy
  package org.foo
  
  def checkOutFrom(repo) {
    git url: "git@github.com:jenkinsci/${repo}"
  }
  
  return this

  Which can then be called from a Scripted Pipeline:

  def z = new org.foo.Zot()
  z.checkOutFrom(repo)

  This approach has limitations; for example, it prevents the declaration of a superclass.

• Alternately, a set of DSL steps can be passed explicitly using this to a library class, in a constructor, or just one method:

  package org.foo
  class Utilities implements Serializable {
    def steps
    Utilities(steps) {this.steps = steps}
    def mvn(args) {
      steps.sh "${steps.tool 'Maven'}/bin/mvn -o ${args}"
    }
  }

  When saving state on classes, such as above, the class must implement the Serializable interface. This ensures that a Pipeline using the class, as seen in the example below, can properly suspend and resume in Jenkins.

  @Library('utils') import org.foo.Utilities
  def utils = new Utilities(this)
  node {
    utils.mvn 'clean package'
  }

  If the library needs to access global variables, such as env, those should be explicitly passed into the library classes, or methods, in a similar manner.

  package org.foo
  class Utilities implements Serializable {
    def steps
  	def env
    Utilities(steps, env) {
  		this.steps = steps
  		this.env = env
  	}
    def mvn(args) {
      steps.sh "${steps.tool 'Maven'}/bin/mvn -o ${args}"
  		steps.sh "echo Building for ${env.BUILD_TAG}"
    }
  }

• Instead of passing numerous variables from the Scripted Pipeline into a library:

  package org.foo
  class Utilities {
    static def mvn(script, args) {
      script.sh "${script.tool 'Maven'}/bin/mvn -s ${script.env.HOME}/jenkins.xml -o ${args}"
    }
  }

  The above example shows the script being passed in to one static method, invoked from a Scripted Pipeline as follows:

  @Library('utils') import static org.foo.Utilities.*
  node {
    mvn this, 'clean package'
  }

vars

Defining global variables

def info(message) {
    echo "INFO: ${message}"
}

def warning(message) {
    echo "WARNING: ${message}"
}

@Library('utils') _

log.info 'Starting'
log.warning 'Nothing to do!'

@Library('utils') _

pipeline {
    agent none
    stages {
        stage ('Example') {
            steps {
                // log.info 'Starting'
                script {
                    log.info 'Starting'
                    log.warning 'Nothing to do!'
                }
            }
        }
    }
}

Defining custom steps

def call(String name = 'human') {
    // Any valid steps can be called from this code, just like in other
    // Scripted Pipeline
    echo "Hello, ${name}."
}

sayHello 'Joe'
sayHello() /* invoke with default arguments */

def call(Closure body) {
    node('windows') {
        body()
    }
}

windows {
    bat "cmd /?"
}

Defining a more structured DSL

def call(Map config) {
    node {
        git url: "https://github.com/jenkinsci/${config.name}-plugin.git"
        sh 'mvn install'
        mail to: '...', subject: "${config.name} plugin build", body: '...'
    }
}

buildPlugin name: 'git'

def call(body) {
    // collect assignments passed in into our mapping
    def settings = [:]
    body.resolveStrategy = Closure.DELEGATE_FIRST
    body.delegate = settings
    body()

    // now, time the commands
   timestamps {
      cmdOutput = echo sh (script:"${settings.cmd}", returnStdout:true).trim()
   }
   echo cmdOutput
   writeFile file: '${settings.logFilePath}', text: '${cmdOutput}'
}

timedCommand4 {
        cmd = 'sleep 5'
        logfilePath = 'log.out'
    }
}

resources

def request = libraryResource 'com/mycorp/pipeline/somelib/request.json'

Using Third-Party Libraries

Troubleshooting

Replaying External Code and Libraries

Sample Library Routine

Summary

Reference