12 Contributing #

Note

Abstract

KIWI NG is provided as a Python module under the kiwi namespace. It is available for the Python 3 version. The following description applies for KIWI NG version 10.2.2.

KIWI NG can also function as a module for other Python projects. The following example demonstrates how to read an existing image description, add a new repository definition, and export the modified description on stdout.

import sys
import logging

from kiwi.xml_description import XMLDescription
from kiwi.xml_state import XMLState

description = XMLDescription('path/to/kiwi/XML/config.xml')

xml_data = description.load()

xml_state = XMLState(
    xml_data=xml_data, profiles=[], build_type='iso'
)

xml_state.add_repository(
    repo_source='http://repo',
    repo_type='rpm-md',
    repo_alias='myrepo',
    repo_prio=99
)

xml_data.export(
    outfile=sys.stdout, level=0
)

Each class in the example is responsible for a single tasks, so they can be reused in other user cases. Therefore it is possible to use KIWI NG beyond the main image building scope, for example to manage setup of loop devices, filesystems, partitions, etc.

This means KIWI NG offers a way to describe a system, but you can choose whether you want to use the KIWI NG description format or not. The following example shows how to use KIWI NG to create a simple filesystem image which contains your host tmp directory.

import logging

from kiwi.storage.loop_device import LoopDevice
from kiwi.filesystem import FileSystem

with LoopDevice(
    filename='my_tmp.ext4', filesize_mbytes=100
) as loop_provider:
    loop_provider.create()

    filesystem = FileSystem.new(
        'ext4', loop_provider, '/tmp/'
    )
    filesystem.create_on_device(
        label='TMP'
    )
    filesystem.sync_data()

Each command provided by KIWI NG is written as a task plugin under the kiwi.tasks namespace. As a developer, you can extend KIWI NG with custom task plugins, following the conventions below.

12.2.2 Example plugin #

 

Note

The following example assumes an existing Python project which was set up according to the Python project rules and standards.

1. Assuming the project namespace is kiwi_relax_plugin, create the task plugin directory kiwi_relax_plugin/tasks

2. Create the entry point in setup.py.

   Assuming we want to create the service named relax that has the command justdoit, this is the following entry point definition in setup.py:

   'packages': ['kiwi_relax_plugin'],
   'entry_points': {
       'kiwi.tasks': [
           'relax_justdoit=kiwi_relax_plugin.tasks.relax_justdoit'
       ]
   }

3. Create the plugin code in the file kiwi_relax_plugin/tasks/relax_justdoit.py with the following content:

   """
   usage: kiwi-ng relax justdoit -h | --help
          kiwi-ng relax justdoit --now
   
   commands:
       justdoit
           time to relax
   
   options:
       --now
           right now. For more details about docopt
           see: http://docopt.org
   """
   # These imports requires kiwi to be part of your environment
   # It can be either installed from pip into a virtual development
   # environment or from the distribution package manager
   from kiwi.tasks.base import CliTask
   from kiwi.help import Help
   
   class RelaxJustdoitTask(CliTask):
       def process(self):
           self.manual = Help()
           if self.command_args.get('help') is True:
               # The following will invoke man to show the man page
               # for the requested command. Thus for the call to
               # succeed a manual page needs to be written and
               # installed by the plugin
               return self.manual.show('kiwi::relax::justdoit')
   
           print(
               'https://genius.com/Frankie-goes-to-hollywood-relax-lyrics'
           )

4. Test the plugin

   $ ./setup.py develop
   $ kiwi-ng relax justdoit --now

KIWI NG comes with a set of helper functions that can be used in config.sh (see also: Section 7.6, “User-Defined Scripts”). These functions utilize containers to run the individual tasks and verify the final result.

Ensure that you have either podman or docker installed and configured on your system. With Podman, the integration tests use podman in rootless mode by default. You can select docker instead by setting the environment variable CONTAINER_RUNTIME to docker. Then you can run the integration tests via tox:

$ tox -e scripts -- -n NUMBER_OF_THREADS

The tests are written using the pytest-container plugin. If applicable, use the utility functions and fixtures of the plugin. For example, the auto_container and auto_container_per_test fixtures in conjunction with testinfra.

@pytest.mark.parametrize("container_per_test", (TUMBLEWEED, LEAP_15_3), indirect=True)
def test_RmWorks(container_per_test):
    # create the file /root/foobar
    container_per_test.connection.run_expect([0], "touch /root/foobar")
    assert container_per_test.connection.file("/root/foobar").exists

    # source the functions and execute our function under test
    container_per_test.connection.run_expect([0], ". /bin/functions.sh && Rm /root/foobar")

    # verify the result
    assert not container_per_test.connection.file("/root/foobar").exists

The core appliance builder is developed in Python and follows the test driven development rules.

If you want to implement a bigger feature, consider opening an issue on GitHub first to discuss the changes. Or join the discussion in the #kiwi channel on Riot.im.

KIWI NG requires additional packages at runtime which are not provided by pip. Those will be pulled in by installing the following package:

The package is provided on the Open Build Service in the Virtualization:Appliances:Builder project. For manual inspection of the packages that are pulled in from the above kiwi-systemdeps package, please refer to the package/python-kiwi-spec-template spec file from the checked out Git repository.

The following commands initializes and activates a development environment for Python 3:

Note

KIWI NG uses tox to create a devel environment and to run tests, linters and other tasks in the tox generated environment. A tox version >= 3.3 is required for this setup process. On your host a python version >= 3.9 is required for tox to work.

$ poetry install

The command above automatically creates the application script called kiwi-ng, which allows you to run KIWI NG from the Python sources inside the virtual environment using Poetry:

$ poetry run kiwi-ng --help

We use tox to run the unit tests. Tox sets up its own virtualenvs inside the .tox directory for multiple Python versions and should thus not be invoked from inside your development virtualenv.

Before submitting your changes via a pull request, ensure that all tests pass and that the code has the required test coverage via the command:

$ tox

We also include pytest-xdist in the development virtualenv which allows to run the unit tests in parallel. It is turned off by default but can be enabled via:

$ tox -- "-n NUMBER_OF_PROCESSES"

where you can insert an arbitrary number as NUMBER_OF_PROCESSES (or a shell command like $(nproc)). Note that the double quotes around -n NUMBER_OF_PROCESSES are required (otherwise tox will consume this command line flag instead of forwarding it to pytest).

The previous call would run the unit tests for different Python versions, check the source code for errors and build the documentation.

If you want to see the available targets, use the option -l to let tox print a list of them:

$ tox -l

To only run a special target, use the -e option. The following example runs the test cases for the Python 3.11 interpreter only:

$ tox -e unit_py3_11

Code changes should be done in an extra Git branch. This allows for creating GitHub pull requests in a clean way. See also: Collaborating with issues and pull requests

$ git checkout -b my-topic-branch

Make and commit your changes.

Note

You can make multiple commits which is generally useful to give your changes a clear structure and to allow us to better review your work.

Note

Your work is important and must be signed to ensure the integrity of the repository and the code. Thus we recommend to setup a signing key as documented in Signing Git Patches.

$ git commit -S -a

Run the tests and code style checks. All of these are also performed by GitLab CI when a pull request is created.

$ tox

Once everything is done, push your local branch to your forked repository and create a pull request into the upstream repository.

$ git push origin my-topic-branch

Thank you much for contributing to KIWI NG. Your time and work effort is very much appreciated!

KIWI NG follows the general PEP8 guidelines with the following exceptions:

tox -e doc

class Example:
    """
    **Example class**

    :param str param: A parameter
    :param bool : Source file name to compress
    :param list supported_zipper: List of supported compression tools
    :attr Optional[str] attr: A class attribute
    """
    def __init__(self, param, param_w_default=False):
        self.attr = param if param_w_default else None

    def method(self, param):
        """
        A method that takes a parameter.

        :param list param: a parameter
        :return: whether param is very long
        :rtype: bool
        """
        return len(param) > 50

The following sections provides further information about the repository integrity, version, package and documentation management.

$ make build