Configs in distgen

distgen provides lots of useful predefined values that you can use in your templates. These are called configs or distros. When executing distgen from commandline, you can use --distro <file> to select desired config. You can either select a config that’s shipped with distgen or you can create and pass your own config.

You can browse through configs shipped with your distgen version in the /usr/share/distgen/distconf directory.

Builtin Configs

Following is a list of values that configs shipped with distgen provide. Each item in the list contains a value example for centos-7-x86_64 config.

  • config.os.arch (e.g. x86_64) - Architecture of the selected distro
  • config.os.id (e.g. centos) - Id of this distro inside distgen
  • config.os.name (e.g. CentOS Linux) - A verbose name of the distro
  • config.os.version (e.g. 7) - Version of the distro
  • config.docker.from (e.g. centos:7) - Name (and possibly a tag) of the base image with this distro
  • config.docker.registry (e.g. index.docker.io) - Name of the registry where image specified by docker.from can be obtained
  • macros - Macros provide paths to some useful directories of given distro; for more information on “why and how”, see macros documentation section. Complete list of macros follows:
    • macros.bindir (e.g. /usr/bin)
    • macros.datadir (e.g. /usr/share)
    • macros.docdir (e.g. /usr/share/doc)
    • macros.libdir (e.g. /usr/lib64)
    • macros.libexecdir (e.g. /usr/libexec)
    • macros.pkgdatadir - this will expand to /usr/share/$name, if name is defined in the config - this is not true for default configs
    • macros.pkgdocdir - this will expand to /usr/share/doc/$name, if name is defined in the config - this is not true for default configs
    • macros.prefix (e.g. /usr)
    • macros.sbindir (e.g. /usr/sbin)
    • macros.sysconfdir (e.g. /etc)
    • macros.unitdir (e.g. /usr/lib/systemd/system)
    • macros.userunitdir (e.g. /usr/lib/systemd/user)
  • config.package_installer.name (e.g. yum) - name of the command that invokes distro package installer

Using Config Values in Templates

Usage of config values in templates is simple. Here’s a very simple example:

FROM {{ config.docker.from }}

COPY script.sh {{ macros.bindir }}

Creating Your Own Config

When creating your own config, you don’t need to specify any of these values, a config can contain any values you want. In that case however, your template must only use the values that your config has.

Dynamic Values in Templates

It may happen to you, that you need a value available in template which is not static – not known before. This could be time, values to generate a help file or others.

The way to this in distgen is to create a new file: project.py in root of your project dir. The python code present in the file will be executed by distgen.

import subprocess
from distgen.project import AbstractProject

class Project(AbstractProject):
    """ This class has to be named "Project" """

    def inst_init(self, specfiles, template, sysconfig):
        """
        Executed before the project.py/spec files/template is loaded and
        before all the dynamic stuff and specification is calculated.
        Now is still time to dynamically change the list of specfiles or
        adjust the system configuration. You can define a variable as an
        attribute of this project:

          self.variable = "42"

        which can be later utilized in a template like this:

          {{ project.variable }}
        """
        self.current_date = subprocess \
            .check_output(["date"]) \
            .decode("utf-8")

    def inst_finish(self, specfiles, template, sysconfig, spec):
        """
        Executed after the project.py/spec files/template is loaded, and
        the specification (spec) calculated (== instantiated).  This is
        the last chance to dynamically change sysconfig or spec.
        """
        # you can easily add or change values here based on sourced
        # spec, template, config...
        if spec["..."]:
            sysconfig["..."] = "..."

And then in your template, you can use the current_date values like this:

LABEL build_time="{{ project.current_date }}"