docs updates
This commit is contained in:
Mike McLean
parent
0f06d749ef
commit
6b5eb875af
2 changed files with 158 additions and 0 deletions
|
|
@ -33,6 +33,7 @@ Contents
|
|||
repo_generation
|
||||
exporting_repositories
|
||||
tag_inheritance
|
||||
managing_comps_data
|
||||
misc
|
||||
release_notes/release_notes
|
||||
migrations/migrations
|
||||
|
|
|
|||
157
docs/source/managing_comps_data.rst
Normal file
157
docs/source/managing_comps_data.rst
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue