Merge pull request #712 from jglick/LibraryStep-JENKINS-31155

[JENKINS-39450] Documenting library step
jenkins-infra · Mar 15, 2017 · e1e6b15 · e1e6b15
2 parents 91d3521 + ab32bbc
commit e1e6b15
Showing 1 changed file with 92 additions and 0 deletions.
diff --git a/content/doc/book/pipeline/shared-libraries.adoc b/content/doc/book/pipeline/shared-libraries.adoc
@@ -185,6 +185,50 @@ echo useSomeLib(new Helper('some text'))
 
 Global Variables however, are resolved at runtime.
 
+=== Loading libraries dynamically
+
+As of version 2.7 of the _Pipeline: Shared Groovy Libraries_ plugin,
+there is a new option for loading (non-implicit) libraries in a script:
+a `library` step that loads a library _dynamically_, at any time during the build.
+
+If you are only interested in using global variables/functions (from the `vars/` directory),
+the syntax is quite simple:
+
+[source,groovy]
+----
+library 'my-shared-library'
+----
+
+Thereafter, any global variables from that library will be accessible to the script.
+
+Using classes from the `src/` directory is also possible, but trickier.
+Whereas the `@Library` annotation prepares the “classpath” of the script prior to compilation,
+by the time a `library` step is encountered the script has already been compiled.
+Therefore you cannot `import` or otherwise “statically” refer to types from the library.
+
+However you may use library classes dynamically (without type checking),
+accessing them by fully-qualified name from the return value of the `library` step.
+`static` methods can be invoked using a Java-like syntax:
+
+[source,groovy]
+----
+library('my-shared-library').com.mycorp.pipeline.Utils.someStaticMethod()
+----
+
+You can also access `static` fields, and call constructors as if they were `static` methods named `new`:
+
+[source,groovy]
+----
+def useSomeLib(helper) { // dynamic: cannot declare as Helper
+    helper.prepare()
+    return helper.count()
+}
+
+def lib = library('my-shared-library').com.mycorp.pipeline // preselect the package
+
+echo useSomeLib(lib.Helper.new(lib.Constants.SOME_TEXT))
+----
+
 === Library versions
 
 The "Default version" for a configured Shared Library is used when "Load
@@ -198,6 +242,33 @@ configuration, a `@Library` annotation may also override a default version
 defined for the library. This also allows a library with "Load implicitly" to
 be loaded from a different version if necessary.
 
+When using the `library` step you may also specify a version:
+
+[source,groovy]
+----
+library 'my-shared-library@master'
+----
+
+Since this is a regular step, that version could be _computed_
+rather than a constant as with the annotation; for example:
+
+[source,groovy]
+----
+library "my-shared-library@$BRANCH_NAME"
+----
+
+would load a library using the same SCM branch as the multibranch `Jenkinsfile`.
+As another example, you could pick a library by parameter:
+
+[source,groovy]
+----
+properties([parameters([string(name: 'LIB_VERSION', defaultValue: 'master')])])
+library "my-shared-library@${params.LIB_VERSION}"
+----
+
+Note that the `library` step may not be used to override the version of an implicitly loaded library.
+It is already loaded by the time the script starts, and a library of a given name may not be loaded twice.
+
 === Retrieval Method
 
 The best way to specify the SCM is using an SCM plugin which has been
@@ -218,6 +289,27 @@ this variable to checkout the appropriate version of the library.
 
 image::pipeline/global-pipeline-library-legacy-scm.png["Configuring a 'Legacy SCM' for a Pipeline Library", role=center]
 
+==== Dynamic retrieval
+
+If you only specify a library name (optionally with version after `@`) in the `library` step,
+Jenkins will look for a preconfigured library of that name.
+(Or in the case of a `github.com/owner/repo` automatic library it will load that.)
+
+But you may also specify the retrieval method dynamically,
+in which case there is no need for the library to have been predefined in Jenkins.
+Here is an example:
+
+[source,groovy]
+----
+library identifier: 'custom-lib@master', retriever: modernSCM(
+  [$class: 'GitSCMSource',
+   remote: 'git@git.mycorp.com:my-jenkins-utils.git',
+   credentialsId: 'my-private-key'])
+----
+
+It is best to refer to *Pipeline Syntax* for the precise syntax for your SCM.
+
+Note that the library version _must_ be specified in these cases.
 
 == Writing libraries