From Fedora Project Wiki

(revise and update to match the PR i'm sending for the comps repo README.md, drop some outdated stuff (env groups are fine in kickstarts these days))
 
(12 intermediate revisions by 8 users not shown)
Line 3: Line 3:
=== Installation ===
=== Installation ===


comps is used by the installer during software selection. At the installer
comps is used by the installer during package selection. On the Software Selection screen, environment groups (as defined by the {{code|environment}} keyword in {{filename|comps.xml}}) are listed down the left-hand side. All optional groups (defined by the {{code|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 {{code|uservisible}} set are displayed lower in the right-hand pane.
software selection dialog, the user can choose between a variety of
Environments on the left, and Options to those environments on the right.


Each environment consists of a list of groups, and a list of groups that are
At install time, the installer will usually install the {{code|mandatory}}, {{code|default}} and appropriate {{code|conditional}} packages from all groups listed in the selected environment group's {{code|grouplist}}, plus those from any optional groups the user selected on the right-hand side. See below for more details on these 'levels'.
options for that environment. The list of available options is supplemented
by any groups that are marked as 'uservisible' in the comps file.


=== Running System ===
=== Running System ===


In yum, groups are used by <code>yum groupinstall</code> and <code>yum groupremove</code> commands, and can be queried with <code>yum grouplist</code> command.  
In dnf, groups and environment groups are used by the {{command|dnf group install}} and {{command|dnf group remove}} commands, and can be queried with the {{command|dnf group list}} command. There are many others besides these: see the [https://dnf.readthedocs.io/en/latest/index.html dnf documentation] for more details.


=== Tree, Release, and Image Composition ===
=== Tree, Release, and Image Composition ===


The kickstart files in [http://git.fedorahosted.org/git/?p=spin-kickstarts.git spin-kickstarts] use the group definitions from comps to compose
The kickstart files in [https://pagure.io/fedora-kickstarts fedora-kickstarts] use the 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 [https://pagure.io/workstation-ostree-config workstation-ostree-config] (the name is a misnomer these days) are synced against comps using the {{filename|comps-sync.py}} script, and used to define the package sets included in those variants.
images and release trees.


Environment definitions should not be used in a kickstart, if you wish to use the environment of "Minimal Install" it should be the list of package groups that comprise the enviornment instead as such:
== Comps structure ==
@standard
@guest-agents


This is found in the comps.xml under the environment you wish to use.
Comps are composed of elements and flags.


== When to Edit comps ==
=== Comps element - category ===
 
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.
 
=== Comps element - environment ===
 
An environment group is composed of lists of mandatory groups and optional groups. Mandatory groups have to be installed for successful install of the environment group.
 
  <environment>
  <id>env1</id>
  <name>Env One</name>
    <grouplist>
      <groupid>group1</groupid>
    </grouplist>
    <optionlist>
      <groupid>group2</groupid>
    </optionlist>
  </environment>
 
=== Comps element - group ===
 
Groups are composed of lists of packages of four types (see Comps element - package).
 
=== Comps element - package ===
 
There are four types of packages:
* mandatory
** have to be installed to mark group as installed
** are essential for functionality of a group
* default
** are installed with mandatory packages, but can be excluded
** are not essential for core functionality of a group
* optional
** are not installed by default
** can be added to transaction <code>dnf group install -–with-optional ‘Group One’</code> or the kickstart {{code|--optional}} group option
* conditional
** are brought in transaction if their required package is installed or about to be installed
 
==== Package basearchonly flag ====
 
To make comps more adjustable it is possible to use basearchonly flag that forces package manager to install package only for system base-arch. If package with <code>basearchonly="true"</code> cannot be installed with <code>basearch</code> then the package should not be installed at all, therefore in case of mandatory package, install of the group should be unsuccessful. The absence of  <code>basearchonly</code> flag is equivalent to <code>basearchonly="False"</code>, where the package can be installed with any compatible architecture.
 
=== Comps element - arch flag ===
 
Each comps element can be used with arch flag to determine on which system should be element take in account. The arch values are compared with basearch value of system. The absence of arch flag means that comps element is valid for all architectures. For instance, <code><packagereq type="mandatory" arch="i686,s390x">pkg-c</packagereq></code> in comps the package will be installed only on systems with <code>basearch</code> <code>i686</code> or <code>s390x</code>. pkg-c will not be installed even on a system with a base architecture compatible with one of the listed architectures (e.g <code>x86_64</code>).
 
=== Examples ===
 
  <group>
    <id>group1</id>
    <name>Group One</name>
    <packagelist>
      <packagereq type="mandatory">pkg-a</packagereq>
      <packagereq type="default">pkg-b</packagereq>
      <packagereq type="default" basearchonly="true">pkg-c</packagereq>
      <packagereq type="optional">pkg-d</packagereq>
    </packagelist>
  </group>
 
== When to submit changes to comps ==


* If your app should be part of one of the installation environments, or part of an option for one of them, it should be included
* If your app should be part of one of the installation environments, or part of an option for one of them, it should be included
Line 44: Line 96:


=== [[SIGs/Minimal_Core | Core ]] ===
=== [[SIGs/Minimal_Core | Core ]] ===
Core is not visible, so adding 'default' or 'optional' packages to it isn't needed. Boot loaders are listed as 'default' in the group so that they're pulled in by compose tools.


Core is installed on every installation, so adding packages to it is discouraged. Please run changes by the [[SIGs/Minimal_Core | Minimal Core SIG]].
Core is installed on every installation, so adding packages to it is discouraged. Please run changes by the [[SIGs/Minimal_Core | Minimal Core SIG]].
Line 68: Line 118:
When making changes to the default or mandatory packages, strive for consensus, and consult the development lists as necessary. If you're unsure, you can also file a bug against the comps component in bugzilla.
When making changes to the default or mandatory packages, strive for consensus, and consult the development lists as necessary. If you're unsure, you can also file a bug against the comps component in bugzilla.


== How to edit comps ==
== Developing comps ==
 
Clone the comps GIT module in Fedora Hosted:
 
<code>git clone ssh://username@git.fedorahosted.org/git/comps.git</code>
 
Replace <code>username</code> with your FAS username. You need to be a member of the packager group to checkout the comps module over ssh.
 
Then, find a reasonable group in the comps-f''n''xml.in file (where ''n'' represents the release number) for
your package. If your package is not listed there, please add it using the following as a template if your package were named "foo":
 
<packagereq type="optional">foo</packagereq>
 
* Make sure to preserve the alphabetical order in each group.
* Make sure to run xmllint on the result to check you didn't make a mistake in the XML syntax.
 
You can use the provided xslt filter to sort, indent and check the syntax of your comps file in one run:
 
<pre>
$ xsltproc --novalid -o sorted-file comps-cleanup.xsl original-file
</pre>


The filter will warn you if it removes redundant information or if something needs to be checked by a human.
For Fedora packagers:


Commit your changes (<code>git commit -a</code>). You
git clone ssh://git@pagure.io/fedora-comps.git
can then push your changes to the repository with <code>git push</code>.


Please make sure to run <code>git pull --rebase</code> right before <code>git push</code> to
For others:
avoid overwriting other people's changes as much as possible.


=== Anonymous checkouts ===
git clone https://pagure.io/fedora-comps.git
If you are not a packager and would like to checkout comps, you can do so anonymously over https. You will not be able to push changes to comps using this method:


<code>git clone https://git.fedorahosted.org/git/comps.git </code>
When changing the packages, make sure the file is sorted. This helps to make it more maintainable. Use {{command|make sort}} command to fix the sorting. Also run {{command|make validate}} to check for XML syntax errors. You can submit pull requests using the standard Pagure (forge-like) workflow - fork the repository from [https://pagure.io/fedora-comps the web UI], push your changes to your fork, and submit a pull request for it. If you are not familiar with this workflow, see the [https://docs.pagure.org/pagure/usage/pull_requests.html Pagure documentation].


== Current status ==
== Current status ==


You can check our current comps status file [https://git.fedorahosted.org/git/comps.git in the git web interface].
You can check our current comps status file [https://pagure.io/fedora-comps in the git web interface].


[[Category:Comps_SIG]][[Category:Package Maintainers]]
[[Category:Comps_SIG]][[Category:Package Maintainers]]

Latest revision as of 21:59, 29 August 2022

How comps is used

Installation

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.

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 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 for more details.

Tree, Release, and Image Composition

The kickstart files in fedora-kickstarts use the 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 (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.

Comps structure

Comps are composed of elements and flags.

Comps element - category

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.

Comps element - environment

An environment group is composed of lists of mandatory groups and optional groups. Mandatory groups have to be installed for successful install of the environment group.

 <environment>
  <id>env1</id>
  <name>Env One</name>
   <grouplist>
     <groupid>group1</groupid>
   </grouplist>
   <optionlist>
     <groupid>group2</groupid>
   </optionlist>
 </environment>

Comps element - group

Groups are composed of lists of packages of four types (see Comps element - package).

Comps element - package

There are four types of packages:

  • mandatory
    • have to be installed to mark group as installed
    • are essential for functionality of a group
  • default
    • are installed with mandatory packages, but can be excluded
    • are not essential for core functionality of a group
  • optional
    • are not installed by default
    • can be added to transaction dnf group install -–with-optional ‘Group One’ or the kickstart --optional group option
  • conditional
    • are brought in transaction if their required package is installed or about to be installed

Package basearchonly flag

To make comps more adjustable it is possible to use basearchonly flag that forces package manager to install package only for system base-arch. If package with basearchonly="true" cannot be installed with basearch then the package should not be installed at all, therefore in case of mandatory package, install of the group should be unsuccessful. The absence of basearchonly flag is equivalent to basearchonly="False", where the package can be installed with any compatible architecture.

Comps element - arch flag

Each comps element can be used with arch flag to determine on which system should be element take in account. The arch values are compared with basearch value of system. The absence of arch flag means that comps element is valid for all architectures. For instance, <packagereq type="mandatory" arch="i686,s390x">pkg-c</packagereq> in comps the package will be installed only on systems with basearch i686 or s390x. pkg-c will not be installed even on a system with a base architecture compatible with one of the listed architectures (e.g x86_64).

Examples

 <group>
   <id>group1</id>
   <name>Group One</name>
   <packagelist>
     <packagereq type="mandatory">pkg-a</packagereq>
     <packagereq type="default">pkg-b</packagereq>
     <packagereq type="default" basearchonly="true">pkg-c</packagereq>
     <packagereq type="optional">pkg-d</packagereq>
   </packagelist>
 </group>

When to submit changes to comps

  • If your app should be part of one of the installation environments, or part of an option for one of them, it should be included
  • If you're creating a new option for an installation environment
  • Libraries should not be included - they will be pulled in via dependencies
  • Most text-mode utilities don't really fit in unless they have a pretty large established user-base.

If you have questions as to whether it makes sense or not, feel free to post to the development list.

Some guidelines on specific groups in comps follows.

New groups

Please consult devel before adding new groups.

New user-visible group names and descriptions are translatable strings. Do not add new groups, or change their descriptions, during a string freeze. Please check the release schedule for these dates.

Core

Core is installed on every installation, so adding packages to it is discouraged. Please run changes by the Minimal Core SIG.

GNOME Desktop

The gnome-desktop group and GNOME environment definition is maintained by the Desktop SIG. Please run changes through desktop.

KDE Desktop

The kde-desktop group and KDE environment definition is maintained by the KDE SIG. Please run changes by them.

Fonts

The following is part of the Fonts SIG packaging rules.


Fonts for a particular linguistic region used to be bundled in fonts-region packages. Nowadays this practice is frowned upon, fonts package naming reflects upstream naming like in any other Fedora package, and grouping is achieved through comps groups.

  • Font packages in a legacy format (not TTF or OTF) MUST be registered in the legacy-fonts group.
  • Font packages in a non-legacy format (TTF or OTF):
    1. MUST be registered in the fonts group:
      • except when they don't have an active upstream, in which case putting them in legacy-fonts is fine.
    2. SHOULD also be registered in every applicable xxx-support localization group:
      • except groups that only require glyphs in the basic latin range.
      • if a font package adds support for a script previously not supported by Fedora the associated localization groups MUST be created and filed, and the relevant localization teams notified.
    3. SHOULD be declared optional, unless:
      • they add support for a new script, in which case they MUST be declared required in the associated localization groups.
      • they add better support for already supported scripts, in which case, if the localization team in charge of each localization group agrees:
        • they can replace existing fonts as mandatory if this script is not covered by distribution-wide default fonts.
        • they can replace existing fonts as default if this script is covered by distribution-wide default fonts.



Idea.png
Fonts in Fedora
The Fonts SIG takes loving care of Fedora fonts. Please join this special interest group if you are interested in creating, improving, packaging, or just suggesting a font. Any help will be appreciated.

All other groups

When making changes to the default or mandatory packages, strive for consensus, and consult the development lists as necessary. If you're unsure, you can also file a bug against the comps component in bugzilla.

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 standard Pagure (forge-like) workflow - fork the repository from the web UI, 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.

Current status

You can check our current comps status file in the git web interface.