Debian Codegraph @

jenkins_jobs/modules/project_matrix.py

raw
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