50 lines
1.9 KiB
ReStructuredText
50 lines
1.9 KiB
ReStructuredText
|
Task Definition YAML Templates
|
||
|
|
==============================
|
||
|
|
|
||
|
|
A few kinds of tasks are described using templated YAML files. These files
|
||
|
|
allow some limited forms of inheritance and template substitution as well as
|
||
|
|
the usual YAML features, as described below.
|
||
|
|
|
||
|
|
Please do not use these features in new kinds. If you are tempted to use
|
||
|
|
variable substitution over a YAML file to define tasks, please instead
|
||
|
|
implement a new kind-specific transform to accopmlish your goal. For example,
|
||
|
|
if the current push-id must be included as an argument in
|
||
|
|
``task.payload.command``, write a transform function that makes that assignment
|
||
|
|
while building a job description, rather than parameterizing that value in the
|
||
|
|
input to the transforms.
|
||
|
|
|
||
|
|
Inheritance
|
||
|
|
-----------
|
||
|
|
|
||
|
|
One YAML file can "inherit" from another by including a top-level ``$inherits``
|
||
|
|
key. That key specifies the parent file in ``from``, and optionally a
|
||
|
|
collection of variables in ``variables``. For example:
|
||
|
|
|
||
|
|
.. code-block:: yaml
|
||
|
|
|
||
|
|
$inherits:
|
||
|
|
from: 'tasks/builds/base_linux32.yml'
|
||
|
|
variables:
|
||
|
|
build_name: 'linux32'
|
||
|
|
build_type: 'dbg'
|
||
|
|
|
||
|
|
Inheritance proceeds as follows: First, the child document has its template
|
||
|
|
substitutions performed and is parsed as YAML. Then, the parent document is
|
||
|
|
parsed, with substitutions specified by ``variables`` added to the template
|
||
|
|
substitutions. Finally, the child document is merged with the parent.
|
||
|
|
|
||
|
|
To merge two JSON objects (dictionaries), each value is merged individually.
|
||
|
|
Lists are merged by concatenating the lists from the parent and child
|
||
|
|
documents. Atomic values (strings, numbers, etc.) are merged by preferring the
|
||
|
|
child document's value.
|
||
|
|
|
||
|
|
Substitution
|
||
|
|
------------
|
||
|
|
|
||
|
|
Each document is expanded using the PyStache template engine before it is
|
||
|
|
parsed as YAML. The parameters for this expansion are specific to the task
|
||
|
|
kind.
|
||
|
|
|
||
|
|
Simple value substitution looks like ``{{variable}}``. Function calls look
|
||
|
|
like ``{{#function}}argument{{/function}}``.
|