Docs: Add example Jenkinsfile to documentation

This shows how each function is implemented in a functional
Jenkinsfile, and is intended to be updated with each additional
function added to the pipeline library.

Issue: RELENG-3716
Signed-off-by: Eric Ball <eball@linuxfoundation.org>
Change-Id: I24abb25153d27e9438fd88772a274195886127fc

diff --git a/Jenkinsfile.example.groovy b/Jenkinsfile.example.groovy
new file mode 100644 (file)
index 0000000..ac7c5e7
--- /dev/null
+++ b/Jenkinsfile.example.groovy
@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright (c) 2021 The Linux Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+loadGlobalLibrary()
+
+pipeline {
+    agent {
+        // This label should match an agent available on the target system
+        label "centos7-docker-4c-2g"
+    }
+
+    options {
+        timestamps()
+        timeout(360)
+    }
+
+    environment {
+        // The settings file needs to exist on the target Jenkins system
+        mvnSettings = "sandbox-settings"
+    }
+
+    stages {
+        stage("Java Build") {
+            steps {
+                lfJava(mvnSettings=env.mvnSettings)
+            }
+        }
+        stage("Parallel Testing") {
+            parallel {
+                stage("amd") {
+                    // This label should match an agent available on the target system
+                    node {"amdNode"}
+                    steps {
+                        sh "echo AMD tests"
+                    }
+                    post {
+                        always {
+                            lfParallelCostCapture()
+                        }
+                    }
+                }
+                stage("arm") {
+                    // This label should match an agent available on the target system
+                    node {"armNode"}
+                    steps {
+                        sh "echo ARM tests"
+                    }
+                    post {
+                        always {
+                            lfParallelCostCapture()
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    post {
+        always {
+            // The default logSettingsFile is "jenkins-log-archives-settings".
+            // If this file isn't present, a different value for logSettingsFile
+            // will need to be passed to lfInfraShipLogs.
+            lfInfraShipLogs()
+        }
+    }
+}
+
+// This loadGlobalLibrary call is only required if the library is not defined
+// in the Jenkins global or job settings. Otherwise, a simple "@Library" call
+// will suffice.
+def loadGlobalLibrary(branch = "*/master") {
+    library(identifier: "pipelines@master",
+        retriever: legacySCM([
+            $class: "GitSCM",
+            userRemoteConfigs: [[url: "https://github.com/lfit/releng-pipelines"]],
+            branches: [[name: branch]],
+            doGenerateSubmoduleConfigurations: false,
+            extensions: [[
+                $class: "SubmoduleOption",
+                recursiveSubmodules: true,
+            ]]]
+        )
+    ) _
+}

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 175c2a3..cbc3bbf 100644 (file)
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -19,3 +19,12 @@ directly in Jenkinsfile, without the need for further imports. For a more
 detailed explanation of pipeline libraries, please see the
 `Jenkins Shared Library docs
 <https://www.jenkins.io/doc/book/pipeline/shared-libraries/#using-libraries>`_.
+
+Example Jenkinsfile
+-------------------
+
+Below is a simple Jenkinsfile that shows a basic implementation of the functions
+supported by this library.
+
+.. literalinclude::
+   /../Jenkinsfile.example.groovy