davidlt
/
fedora-comps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Revise and update README.md 

The information in this file was wildly outdated. This overhauls
the whole thing to be accurate and updated (I hope). Note I've
synced https://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups
with the current state of this pull request.

Signed-off-by: Adam Williamson <awilliam@redhat.com>
This commit is contained in:
Adam Williamson 2022-08-29 15:00:08 -07:00
parent 087101147c
commit 87f65db716
1 changed files with 32 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@ -1,43 +1,49 @@
# Fedora Comps #
comps is a XML file used by various Fedora tools to perform grouping of packages into functional groups.
comps files are XML files used by various Fedora tools to perform grouping of packages into functional groups.
## How comps is used ##
### Installation ###
comps is used by the installer during package selection. At the Default Packages dialog , the user can choose to Customize Now, displaying the Category Selection dialog.
comps is used by the installer during package selection. On the Software Selection screen, environment groups (as defined by the `environment` keyword in `comps.xml`) are listed down the left-hand side. All optional groups (defined by the `group` keyword) for that environment (listed in the environment's `optionlist`) are shown at the top of the right-hand pane. Other groups which have `uservisible` set are displayed lower in the right-hand pane.
In the category selection dialog , categories (as defined by the `category` keyword in `comps.xml`) are listed down the left-hand side. If a category is selected, any groups in that category with `uservisible` set are displayed in the right-hand pane. Groups have an icon associated with them. These icons come from the `comps-extras` package; icons are read from `/usr/share/pixmaps/comps/<group-id>.png`. If an icon does not exist for a group id, the one for the category that the group is in is used.
Once a group is selected, clicking the Optional Packages button shows the Package Selection dialog.
In any group, there are four levels of packages: optional, default, mandatory, and conditional:
* `optional` are not automatic but can be checked
* `default` are, but can be unchecked in a gui tool
* `mandatory` are always brought in (if group is selected), and not visible in the Package Selection dialog.
* `conditional` are brought in if their `requires` package is installed
Usually optional is the way, however if you feel that your package deserves a default or required level bring it up for discussion on the development lists. Remember that this has effect on whether or not your package winds up on distribution media such as Live images and spins.
At install time, the installer will usually install the `mandatory`, `default` and appropriate `conditional` packages from all groups listed in the selected environment group's `grouplist`, plus those from any optional groups the user selected on the right-hand side. See below for more details on these 'levels'.
### Running System ###
In dnf, groups are used by `dnf group install` and `dnf group remove` commands, and can be queried with `dnf group list` command.
In `PackageKit` (Add / Remove Software) the upper left quadrant shows Package collections. When this is clicked, the grouping information is loaded from the configured software repositories, and the complete list of groups, stripped from their categories, are shown in the right hand pane. Selecting a group for installation causes only the default packages within the group to be installed.
### Developing comps ###
git clone ssh://git@pagure.io/fedora-comps.git
When changing the packages, make sure the file is sorted. This helps to make it more maintainable. Use `make sort` command to fix the sorting.
In dnf, groups and environment groups are used by the `dnf group install` and `dnf group remove` commands, and can be queried with the `dnf group list` command. There are many others besides these: see the [dnf documentation](https://dnf.readthedocs.io/en/latest/index.html) for more on this.
### Tree, Release, and Image Composition ###
The kickstart files in [fedora-kickstarts](https://pagure.io/fedora-kickstarts.git) use the group definitions from comps to compose images and release trees.
The kickstart files in [fedora-kickstarts](https://pagure.io/fedora-kickstarts.git) use the group and environment group definitions from comps. Multiple tools use these kickstarts to compose different types of images, and the release trees. The manifests for rpm-ostree-based Fedora variants in [workstation-ostree-config](https://pagure.io/workstation-ostree-config) (the name is a misnomer these days) are synced against comps using the `comps-sync.py` script, and used to define the package sets included in those variants.
### Package levels ###
In any group, there are four levels of packages: `optional`, `default`, `mandatory`, and `conditional`.
* `mandatory` - these packages must be installed for the group to be considered installed
* `default` - these packages are installed by default, but can be removed while the group is still considered installed
* `optional` - these packages are not installed by default, but can be pulled in by kickstart or dnf options
* `conditional` - these packages are brought in if their `requires` package is installed
When using the interactive installer, you cannot include `optional` packages. However, if using a kickstart, you can add the `--optional` option for a group to specify that its optional packages should be included. Similarly, when installing a group with `dnf`, you can pass `--with-optional` to include the optional packages.
### Categories ###
Categories are barely used any more. They used to be something like environment groups for an older form of the Fedora installer. Some older graphical package management tools can still display these categories.
### Developing comps ###
For Fedora packagers:
git clone ssh://git@pagure.io/fedora-comps.git
For others:
git clone https://pagure.io/fedora-comps.git
When changing the packages, make sure the file is sorted. This helps to make it more maintainable. Use `make sort` command to fix the sorting. Also run `make validate` to check for XML syntax errors. You can submit pull requests using the common Github-style workflow - fork the repository from [the web UI](https://pagure.io/fedora-comps), push your changes to your fork, and submit a pull request for it. If you are not familiar with this workflow, see the [Pagure documentation](https://docs.pagure.org/pagure/usage/pull_requests.html).
## For more info ##