.. _plugins_v2: 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. .. _Ansible: https://www.ansible.com .. _documentation: https://docs.ansible.com/ .. _debian_setup: https://github.com/lueschem/debian_setup 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: .. code-block:: yaml :caption: Configuration Example postprocessing_commands: ... 300_rootfs2image: path: postprocessing_commands/genimage/rootfs2image.edi require_root: "unshare" output: pp_image: location: {{ edi_configuration_name }}.img type: path pp_partition_image: location: {{ edi_configuration_name }}_rootfs.ext4 type: path parameters: hostname: raspberry ... :code:`edi` will render the file :code:`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 :code:`edi` and the scripts or executables that do the heavy lifting. The statement :code:`require_root: unshare` tells edi that a modified user namespace is needed to execute the command. The command :code:`buildah unshare` will be used to create the namespace and if the :code:`edi_project_container` is already available, its root file system will be mounted to :code:`${edi_project_container_root}`. Remark: :code:`require_root: unshare` is preferable to :code:`require_root: fakeroot` as extended attributes are not properly supported within a :code:`fakeroot` environment. Each pre- or postprocessing command shall create at least one (intermediate) artifact that gets specified within the :code:`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 :code:`path`), a Podman image (type :code:`podman-image`) or a Buildah container (type :code:`buildah-container`). The preprocessing commands must create an artifact named :code:`edi_bootstrapped_rootfs`. The second processing step will create an output artifact named :code:`edi_project_container` of type :code:`buildah-container`. The :code:`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: .. code:: bash edi --log=DEBUG documentation render PATH_TO_USR_SHARE_DOC_FOLDER OUTPUT_FOLDER CONFIG.yml .. option:: --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 :code:`edi_doc_first_chunk` and :code:`edi_doc_last_chunk` can be used within the templates to add a header or a footer where needed. .. _Sphinx: https://www.sphinx-doc.org/ .. _edi-pi: https://github.com/lueschem/edi-pi Index ^^^^^ The index template can be used to generate an index file: .. code-block:: yaml :caption: 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: .. code-block:: yaml :caption: 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: .. code-block:: yaml :caption: 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: .. code-block:: yaml :caption: 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 `_' - pattern: '(?i)[#]*(Closes:\s[#])([0-9]{6,10})' replacement: '`\1\2 `_' - pattern: '(?i)[#]*(LP:\s[#])([0-9]{6,10})' replacement: '`\1\2 `_' ...