Plugins

Note

This chapter covers the Buildah based workflow v2.

An edi project configuration can be modularized using reusable plugins:

Ansible Collections

The edi-pi project configuration pulls in the Ansible collection debian_setup as a git submodule.

Please take a look at the comprehensive documentation of Ansible if you want to write your own collections.

A project configuration can make use of multiple collections.

Pre- and Postprocessing Commands

Preprocessing commands can be used to prepare a minimal root file system that can then be imported into Buildah. Postprocessing commands can be used to gradually transform a Buildah container into the desired artifacts (e.g. an image that can get flashed to an SD card).

A typical pre- or postprocessing command can be configured as follows:

Configuration Example

 postprocessing_commands:
 ...
   300_rootfs2image:
     path: postprocessing_commands/genimage/rootfs2image.edi
     require_root: "fakeroot"
     output:
       pp_image:
         location: {{ edi_configuration_name }}.img
         type: path
       pp_partition_image:
         location: {{ edi_configuration_name }}_rootfs.ext4
         type: path
     parameters:
       hostname: raspberry
  ...

edi will render the file postprocessing_commands/genimage/rootfs2image.edi using the Jinja2 template engine and then execute it. It is a good practice to use this file as a thin shim between edi and the scripts or executables that do the heavy lifting.

The statement require_root: fakeroot tells edi that a fakeroot environment is needed to execute the command.

Each pre- or postprocessing command shall create at least one (intermediate) artifact that gets specified within the output node. The resulting artifact can be used as an input for any subsequent pre- or postprocessing command.

The specified output can be either a single file or a folder (if multiple files get generated by the command) (type path), a Podman image (type podman-image) or a Buildah container (type buildah-container).

The preprocessing commands must create an artifact named edi_bootstrapped_rootfs.

The second processing step will create an output artifact named edi_project_container of type buildah-container. The edi_project_container artifact can be used as an input for the postprocessing steps.

The postprocessing commands are implemented in a very generic way and to get an idea of what they can do please take a look at the the edi-pi configuration.

Note

Neither pre- nor postprocessing commands shall modify artifacts that have been generated by a previous command.

Documentation Steps

edi ships with a few Jinja2 templates that can be re-used in many projects. This templates can also serve as an example if you want to write custom templates for your own project.

To develop custom templates and learn more about the Jinja2 rendering context the documentation command can be executed in debug mode:

edi --log=DEBUG documentation render PATH_TO_USR_SHARE_DOC_FOLDER OUTPUT_FOLDER CONFIG.yml

--log=LEVEL: Changes the log level of the command to the desired log level (DEBUG,INFO,WARNING,ERROR,CRITICAL).

The output of the provided templates is reStructuredText that can be further tweaked and then be transformed into a nice pdf document using Sphinx. For more details please take a look at the edi-pi example configuration.

Please note that you can generate other output formats such as markdown by providing custom templates.

The templates get applied chunk by chunk. The booleans edi_doc_first_chunk and edi_doc_last_chunk can be used within the templates to add a header or a footer where needed.

Index

The index template can be used to generate an index file:

Configuration Example

documentation_steps:
...
  100_index:
    path: documentation_steps/rst/templates/index.rst.j2
    output:
      file: index.rst
    parameters:
      edi_doc_include_packages: []
      toctree_items: ['setup', 'versions', 'changelog']
...

Setup

The setup template can be used to document the build setup:

Configuration Example

documentation_steps:
...
  200_setup:
    path: documentation_steps/rst/templates/setup.rst.j2
    output:
      file: setup.rst
    parameters:
      edi_doc_include_packages: []
...

Versions

The versions template can be used to document the package versions:

Configuration Example

documentation_steps:
...
  300_versions:
    output:
      file: versions.rst
    path: documentation_steps/rst/templates/versions.rst.j2
...

Changelog

The changelog template can be used to document the changes of each package:

Configuration Example

documentation_steps:
...
  400_changelog:
    path: documentation_steps/rst/templates/changelog.rst.j2
    output:
      file: changelog.rst
    parameters:
      edi_doc_include_changelog: True
      edi_doc_changelog_baseline: 2023-12-01 00:00:00 GMT
      edi_doc_replacements:
      - pattern: '(CVE-[0-9]{4}-[0-9]{4,6})'
        replacement: '`\1 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=\1>`_'
      - pattern: '(?i)[#]*(Closes:\s[#])([0-9]{6,10})'
        replacement: '`\1\2 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=\2>`_'
      - pattern: '(?i)[#]*(LP:\s[#])([0-9]{6,10})'
        replacement: '`\1\2 <https://bugs.launchpad.net/ubuntu/+source/nano/+bug/\2>`_'
...