| 1 |
# Copyright 2012 Julian Taylor <[email protected]> |
| 2 |
# |
| 3 |
# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 |
# you may not use this file except in compliance with the License. |
| 5 |
# You may obtain a copy of the License at |
| 6 |
# |
| 7 |
# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 |
# |
| 9 |
# Unless required by applicable law or agreed to in writing, software |
| 10 |
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| 11 |
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| 12 |
# License for the specific language governing permissions and limitations |
| 13 |
# under the License. |
| 14 |
|
| 15 |
|
| 16 |
""" |
| 17 |
The matrix project module handles creating Jenkins matrix |
| 18 |
projects. To create a matrix project specify ``matrix`` in the |
| 19 |
``project-type`` attribute to the :ref:`Job` definition. |
| 20 |
Currently it supports four axes which share the same |
| 21 |
internal YAML structure: |
| 22 |
|
| 23 |
* label expressions (``label-expression``) |
| 24 |
* user-defined values (``user-defined``) |
| 25 |
* slave name or label (``slave``) |
| 26 |
* JDK name (``jdk``) |
| 27 |
|
| 28 |
Requires the Jenkins :jenkins-plugins:`Matrix Project Plugin |
| 29 |
<matrix-project>`. |
| 30 |
|
| 31 |
The module also supports additional, plugin-defined axes: |
| 32 |
|
| 33 |
* DynamicAxis (``dynamic``), requires the Jenkins |
| 34 |
:jenkins-plugins:`DynamicAxis Plugin <dynamic-axis>` |
| 35 |
* GroovyAxis (``groovy``), requires the Jenkins |
| 36 |
:jenkins-github:`GroovyAxis Plugin <groovyaxis-plugin>` |
| 37 |
* YamlAxis (``yaml``), requires the Jenkins |
| 38 |
:jenkins-plugins:`Yaml Axis Plugin <yaml-axis>` |
| 39 |
|
| 40 |
To tie the parent job to a specific node, you should use ``node`` parameter. |
| 41 |
On a matrix project, this will tie *only* the parent job. To restrict axes |
| 42 |
jobs, you can define a single value ``slave`` axis. |
| 43 |
|
| 44 |
:Job Parameters: |
| 45 |
|
| 46 |
.. note:: |
| 47 |
|
| 48 |
You can only pick one of the strategies. |
| 49 |
|
| 50 |
* **execution-strategy** (optional, built in Jenkins): |
| 51 |
* **combination-filter** (`str`): axes selection filter |
| 52 |
* **sequential** (`bool`): run builds sequentially (default false) |
| 53 |
* **touchstone** (optional): |
| 54 |
* **expr** (`str`) -- selection filter for the touchstone build |
| 55 |
* **result** (`str`) -- required result of the job: \ |
| 56 |
stable (default) or unstable |
| 57 |
|
| 58 |
* **yaml-strategy** (optional, requires |
| 59 |
:jenkins-plugins:`Yaml Axis Plugin <yaml-axis>`): |
| 60 |
|
| 61 |
* **exclude-key** (`str`) -- top key containing exclusion rules |
| 62 |
* Either one of: |
| 63 |
* **filename** (`str`) -- Yaml file containing exclusions |
| 64 |
* **text** (`str`) -- Inlined Yaml. Should be literal |
| 65 |
``text: | exclude:...`` |
| 66 |
|
| 67 |
* **axes** (`list`): |
| 68 |
* **axis**: |
| 69 |
* **type** (`str`) -- axis type, must be either type defined by |
| 70 |
:jenkins-plugins:`Matrix Project Plugin <matrix-project>` |
| 71 |
(``label-expression``, ``user-defined``, ``slave`` or ``jdk``) or |
| 72 |
a type defined by a plugin (see top of this document for a list |
| 73 |
of supported plugins). |
| 74 |
* **name** (`str`) -- name of the axis |
| 75 |
* **values** (`list`) -- values of the axis |
| 76 |
|
| 77 |
The module supports also ShiningPanda axes: |
| 78 |
|
| 79 |
Example: |
| 80 |
|
| 81 |
.. literalinclude:: /../../tests/general/fixtures/matrix-axis003.yaml |
| 82 |
|
| 83 |
Requires the Jenkins :jenkins-plugins:`ShiningPanda Plugin <shiningpanda>`. |
| 84 |
|
| 85 |
Example: |
| 86 |
|
| 87 |
.. literalinclude:: /../../tests/yamlparser/job_fixtures/project-matrix001.yaml |
| 88 |
:language: yaml |
| 89 |
|
| 90 |
Examples for yaml axis: |
| 91 |
|
| 92 |
.. literalinclude:: /../../tests/general/fixtures/matrix-axis-yaml.yaml |
| 93 |
:language: yaml |
| 94 |
|
| 95 |
.. literalinclude:: |
| 96 |
/../../tests/general/fixtures/matrix-axis-yaml-strategy-file.yaml |
| 97 |
:language: yaml |
| 98 |
|
| 99 |
.. literalinclude:: |
| 100 |
/../../tests/general/fixtures/matrix-axis-yaml-strategy-inlined.yaml |
| 101 |
:language: yaml |
| 102 |
""" |
| 103 |
|
| 104 |
import xml.etree.ElementTree as XML |
| 105 |
|
| 106 |
import jenkins_jobs.modules.base |
| 107 |
from jenkins_jobs.errors import InvalidAttributeError |
| 108 |
from jenkins_jobs.modules import hudson_model |
| 109 |
|
| 110 |
|
| 111 |
class Matrix(jenkins_jobs.modules.base.Base): |
| 112 |
sequence = 0 |
| 113 |
# List the supported Axis names in our configuration |
| 114 |
# and map them to the Jenkins XML element name. |
| 115 |
supported_axis = { |
| 116 |
"label-expression": "hudson.matrix.LabelExpAxis", |
| 117 |
"user-defined": "hudson.matrix.TextAxis", |
| 118 |
"slave": "hudson.matrix.LabelAxis", |
| 119 |
"jdk": "hudson.matrix.JDKAxis", |
| 120 |
"dynamic": "ca.silvermaplesolutions.jenkins.plugins.daxis.DynamicAxis", |
| 121 |
"python": "jenkins.plugins.shiningpanda.matrix.PythonAxis", |
| 122 |
"tox": "jenkins.plugins.shiningpanda.matrix.ToxAxis", |
| 123 |
"groovy": "org.jenkinsci.plugins.GroovyAxis", |
| 124 |
"yaml": "org.jenkinsci.plugins.yamlaxis.YamlAxis", |
| 125 |
} |
| 126 |
|
| 127 |
supported_strategies = { |
| 128 |
# Jenkins built-in, default |
| 129 |
"execution-strategy": "hudson.matrix.DefaultMatrixExecutionStrategyImpl", |
| 130 |
"yaml-strategy": "org.jenkinsci.plugins.yamlaxis.YamlMatrixExecutionStrategy", |
| 131 |
"p4-strategy": "org.jenkinsci.plugins.p4.matrix.MatrixOptions", |
| 132 |
} |
| 133 |
|
| 134 |
def root_xml(self, data): |
| 135 |
root = XML.Element("matrix-project") |
| 136 |
|
| 137 |
# Default to 'execution-strategy' |
| 138 |
strategies = [s for s in data.keys() if s.endswith("-strategy")] or [ |
| 139 |
"execution-strategy" |
| 140 |
] |
| 141 |
|
| 142 |
# Job can not have multiple strategies |
| 143 |
if len(strategies) > 1: |
| 144 |
raise ValueError( |
| 145 |
"matrix-project does not support multiple strategies. " |
| 146 |
"Given %s: %s" % (len(strategies), ", ".join(strategies)) |
| 147 |
) |
| 148 |
strategy_name = strategies[0] |
| 149 |
|
| 150 |
if strategy_name not in self.supported_strategies: |
| 151 |
raise ValueError( |
| 152 |
"Given strategy %s. Only %s strategies are supported" |
| 153 |
% (strategy_name, self.supported_strategies.keys()) |
| 154 |
) |
| 155 |
|
| 156 |
ex_r = XML.SubElement( |
| 157 |
root, |
| 158 |
"executionStrategy", |
| 159 |
{"class": self.supported_strategies[strategy_name]}, |
| 160 |
) |
| 161 |
|
| 162 |
strategy = data.get(strategy_name, {}) |
| 163 |
|
| 164 |
if strategy_name == "execution-strategy": |
| 165 |
if "combination-filter" in strategy: |
| 166 |
XML.SubElement(root, "combinationFilter").text = str( |
| 167 |
strategy.get("combination-filter", "") |
| 168 |
).rstrip() |
| 169 |
XML.SubElement(ex_r, "runSequentially").text = str( |
| 170 |
strategy.get("sequential", False) |
| 171 |
).lower() |
| 172 |
if "touchstone" in strategy: |
| 173 |
XML.SubElement(ex_r, "touchStoneCombinationFilter").text = str( |
| 174 |
strategy["touchstone"].get("expr", "") |
| 175 |
) |
| 176 |
|
| 177 |
threshold = strategy["touchstone"].get("result", "stable").upper() |
| 178 |
supported_thresholds = ("STABLE", "UNSTABLE") |
| 179 |
if threshold not in supported_thresholds: |
| 180 |
raise InvalidAttributeError( |
| 181 |
"touchstone", threshold, supported_thresholds |
| 182 |
) |
| 183 |
|
| 184 |
# Web ui uses Stable but hudson.model.Result has Success |
| 185 |
if threshold == "STABLE": |
| 186 |
threshold = "SUCCESS" |
| 187 |
|
| 188 |
t_r = XML.SubElement(ex_r, "touchStoneResultCondition") |
| 189 |
for sub_elem in ("name", "ordinal", "color"): |
| 190 |
XML.SubElement(t_r, sub_elem).text = hudson_model.THRESHOLDS[ |
| 191 |
threshold |
| 192 |
][sub_elem] |
| 193 |
|
| 194 |
elif strategy_name == "yaml-strategy": |
| 195 |
filename = str(strategy.get("filename", "")) |
| 196 |
text = str(strategy.get("text", "")) |
| 197 |
exclude_key = str(strategy.get("exclude-key", "")) |
| 198 |
|
| 199 |
if bool(filename) == bool(text): # xor with str |
| 200 |
raise ValueError( |
| 201 |
"yaml-strategy must be given " 'either "filename" or "text"' |
| 202 |
) |
| 203 |
|
| 204 |
yamlType = (filename and "file") or (text and "text") |
| 205 |
XML.SubElement(ex_r, "yamlType").text = yamlType |
| 206 |
|
| 207 |
XML.SubElement(ex_r, "yamlFile").text = filename |
| 208 |
XML.SubElement(ex_r, "yamlText").text = text |
| 209 |
|
| 210 |
XML.SubElement(ex_r, "excludeKey").text = exclude_key |
| 211 |
|
| 212 |
elif strategy_name == "p4-strategy": |
| 213 |
XML.SubElement(ex_r, "runSequentially").text = str( |
| 214 |
strategy.get("sequential", False) |
| 215 |
).lower() |
| 216 |
|
| 217 |
XML.SubElement(ex_r, "buildParent").text = str( |
| 218 |
strategy.get("build-parent", False) |
| 219 |
).lower() |
| 220 |
|
| 221 |
ax_root = XML.SubElement(root, "axes") |
| 222 |
for axis_ in data.get("axes", []): |
| 223 |
axis = axis_["axis"] |
| 224 |
axis_type = axis["type"] |
| 225 |
if axis_type not in self.supported_axis: |
| 226 |
raise ValueError( |
| 227 |
"Only %s axes types are supported" % self.supported_axis.keys() |
| 228 |
) |
| 229 |
axis_name = self.supported_axis.get(axis_type) |
| 230 |
lbl_root = XML.SubElement(ax_root, axis_name) |
| 231 |
name, values = axis.get("name", ""), axis.get("values", [""]) |
| 232 |
if axis_type == "jdk": |
| 233 |
XML.SubElement(lbl_root, "name").text = "jdk" |
| 234 |
elif axis_type == "python": |
| 235 |
XML.SubElement(lbl_root, "name").text = "PYTHON" |
| 236 |
elif axis_type == "tox": |
| 237 |
XML.SubElement(lbl_root, "name").text = "TOXENV" |
| 238 |
else: |
| 239 |
XML.SubElement(lbl_root, "name").text = str(name) |
| 240 |
if axis_type != "groovy": |
| 241 |
v_root = XML.SubElement(lbl_root, "values") |
| 242 |
if axis_type == "dynamic": |
| 243 |
XML.SubElement(v_root, "string").text = str(values[0]) |
| 244 |
XML.SubElement(lbl_root, "varName").text = str(values[0]) |
| 245 |
v_root = XML.SubElement(lbl_root, "axisValues") |
| 246 |
XML.SubElement(v_root, "string").text = "default" |
| 247 |
elif axis_type == "groovy": |
| 248 |
command = XML.SubElement(lbl_root, "groovyString") |
| 249 |
command.text = axis.get("command") |
| 250 |
XML.SubElement(lbl_root, "computedValues").text = "" |
| 251 |
elif axis_type == "yaml": |
| 252 |
XML.SubElement(v_root, "string").text = axis.get("filename") |
| 253 |
else: |
| 254 |
for v in values: |
| 255 |
XML.SubElement(v_root, "string").text = str(v) |
| 256 |
|
| 257 |
return root |