157 lines
6 KiB
ReStructuredText
157 lines
6 KiB
ReStructuredText
Managing comps data for tags
|
|
============================
|
|
|
|
Koji can record comps data for each tag and uses that data to write a comps
|
|
file whenever it generates a yum repo for that tag. This document describes
|
|
how this data is stored, how to read it, and how to change it.
|
|
|
|
For background on comps files, see
|
|
|
|
* https://dnf5.readthedocs.io/en/latest/misc/comps.7.html
|
|
* https://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups
|
|
|
|
The comps data *affects how rpm builds are performed*.
|
|
Various buildroots generated by Koji use these groups for their base install.
|
|
E.g.
|
|
|
|
* rpm builds use the ``build`` group
|
|
* source rpm builds use the ``srpm-build`` group
|
|
* maven builds use the ``maven-build`` group
|
|
* wrapper rpm builds use the ``wrapper-rpm-build`` group
|
|
* appliance builds use the ``appliance-build`` group
|
|
* livecd builds use the ``livecd-build`` group
|
|
* livemedia builds use the ``livemedia-build`` group
|
|
|
|
|
|
Reading the data
|
|
----------------
|
|
|
|
The ``koji list-groups`` cli command will output the comps data for a given tag
|
|
|
|
.. code-block:: text
|
|
|
|
Usage: koji list-groups [options] <tag> [<group>]
|
|
(Specify the --help global option for a list of other help options)
|
|
|
|
Options:
|
|
-h, --help show this help message and exit
|
|
--event=EVENT# query at event
|
|
--ts=TIMESTAMP query at last event before timestamp
|
|
--repo=REPO# query at event for a repo
|
|
--show-blocked Show blocked packages and groups
|
|
|
|
The command will optionally accept a group name to limit the output to a single group.
|
|
|
|
Like many other types of data in Koji, the comps data is versioned and Koji remembers its history.
|
|
The ``--event/--ts/--repo`` options can be used to query this data from an earlier point in time.
|
|
|
|
The ``show-blocked`` option will include blocked entries in the output.
|
|
|
|
Alternately ``show-groups`` command can be used to present the groups data in different formats.
|
|
This command is a historical oddity, but still useful to export the data in comps format.
|
|
|
|
Example
|
|
-------
|
|
|
|
The following command prints the srpm-build group data for the f41-build tag.
|
|
|
|
.. code-block:: text
|
|
|
|
$ koji list-groups f41-build srpm-build
|
|
srpm-build [f41]
|
|
bash: None, mandatory [f41]
|
|
fedora-release: None, mandatory [f41]
|
|
fedpkg-minimal: None, mandatory [f41]
|
|
glibc-minimal-langpack: None, mandatory [f41]
|
|
gnupg2: None, mandatory [f41]
|
|
redhat-rpm-config: None, mandatory [f41]
|
|
rpm-build: None, mandatory [f41]
|
|
shadow-utils: None, mandatory [f41]
|
|
|
|
Because our command included a specific group name, the command only outputs that one group.
|
|
Under this group, we see the list of packages in the group and their parameters.
|
|
The bracketed value at the end shows the tag that the entry is inherited from.
|
|
|
|
|
|
Groups data and inheritance
|
|
---------------------------
|
|
|
|
Like most other data associated with tags, groups data is inheritable.
|
|
Because the groups data is complex, so is the inheritance.
|
|
The groups data is inherited piecemeal, with individual groups, group package
|
|
entries, and group dependencies separately inheritable.
|
|
|
|
You can prevent an entry from being inherited by blocking it.
|
|
This can be done via the ``block-group``, ``block-group-pkg``, and ``block-group-req``
|
|
commands respectively (and undone with the corresponding unblock command).
|
|
|
|
As noted above, you can see which tags an entry comes from via the ``list-groups`` command.
|
|
|
|
So, a given tag will have a list of groups that includes inherited entries.
|
|
Each of those groups will have a list of packages and a list of group dependencies
|
|
which include inherited entries.
|
|
|
|
For admin sanity, we recommend defining a comps in a base tag in your inheritance
|
|
and keeping adjustments in child tags to a minimum.
|
|
A common case is to add additional packages to the build group for a specialized
|
|
build tag.
|
|
|
|
|
|
Changing comps data
|
|
-------------------
|
|
|
|
You can add, remove, block, and unblock individual entries with the relevant command
|
|
|
|
.. code-block:: text
|
|
|
|
add-group Add a group to a tag
|
|
remove-group Remove group from tag
|
|
block-group Block group in tag
|
|
unblock-group Unblock a group from tag
|
|
add-group-pkg Add a package to a group's package listing
|
|
remove-group-pkg Remove packages from a group's package listing
|
|
block-group-pkg Block a package from a group's package listing
|
|
unblock-group-pkg Unblock a package from a group's package listing
|
|
add-group-req Add a group to a group's required list
|
|
block-group-req Block a group's requirement listing
|
|
remove-group-req Remove entries from a group's requirement listing
|
|
unblock-group-req Unblock a group's requirement listing
|
|
|
|
Additionally, you can also import groups data directly from a comps file with the ``import-comps`` command.
|
|
This is useful when setting up a new tag from scratch.
|
|
|
|
.. code-block:: text
|
|
|
|
Usage: koji import-comps [options] <file> <tag>
|
|
(Specify the --help global option for a list of other help options)
|
|
|
|
Options:
|
|
-h, --help show this help message and exit
|
|
--force force import
|
|
|
|
|
|
Blocking vs removing
|
|
--------------------
|
|
|
|
The various remove commands remove a specific entry from a specific tag.
|
|
They will fail if the entry is not actually in the specified tag.
|
|
This commonly happens when an entry is inherited.
|
|
|
|
When your tag has an inherited comps entry that you want to remove, you have two
|
|
options:
|
|
|
|
* block the entry in the tag
|
|
* remove the entry from the ancestor tag it is inherited from
|
|
|
|
It is generally safest to block, as this only affects the tag of concern.
|
|
Removing the entry in an ancestor could affect other tags negatively.
|
|
However, there are certainly cases where it makes sense to remove the entry
|
|
from the ancestor.
|
|
|
|
|
|
Group dependencies
|
|
------------------
|
|
|
|
For historical reasons, Koji's comps data allows specifying group dependecies/requirements.
|
|
This is antiquated feature of comps that is longer used by dnf,
|
|
so in practice there is no need to specify such entries (i.e. the various ``*-req`` commands).
|