Recursive Rendering

Note: This is an experimental feature introduced in version 0.16. It is subject to change or removal in future versions. Use at your own risk.

Recursive rendering is a concept similar to macros, perhaps aimed at obsoleting it altogether one day. For now, both of these live side by side.

The idea behind recursive rendering is simple:

• The template is rendered recursively until it stops changing.
• Spec values can contain references to other spec or config values.

Note two things:

• Maximum number of rendering passes is always limited to a reasonably small integer (currently passed via --max-passes X on command line) to make sure the re-rendering loop ends.
• Recursive rendering is currently turned off, as --max-passes is set to 1.

Example

Let’s consider the following spec:

name: "myname"
help: "This is a help for {{ config.os.id }}/{{ spec.myname }} image."

Let’s try rendering a very simple template that looks like this:

{{ spec.help }}

• In the first rendering pass, {{ spec.help }} will get substitued.
• In the second rendering pass, {{ config.os.id }} and {{ spec.myname }} will get substitued.
• The third rendering pass will find out that there are no changes and will end recursive rendering (so 3 passes are necessary).

Usage

As of now, recursive rendering is turned off by default (in other words, there’s just one rendering pass). To turn it on, pass a number higher than 2 to dg‘s --max-passes commandline switch. For example:

dg --distro fedora-26-x86_64.yaml --spec myspec.yaml --template Dockerfile --max-passes 10