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))
 
(42 intermediate revisions by 20 users not shown)
Line 1: Line 1:
If you maintain an application which makes sense for a user to select during installation, check out the
== How comps is used ==
comps module and make sure that your package is listed in a reasonable
 
group in the comps-f''n''.xml.in files (''n'' = number of release; note the files for Fedora Extras ≤ 6 are named comps-fe''n''.xml.in).  If it's not, please add it
=== Installation ===
using the following as a template if your package were named "foo":
 
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.
 
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'.


<packagereq type="optional">foo</packagereq>
=== Running System ===


* Make sure to preserve the alphabetical order in each group.
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.
* 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:
=== Tree, Release, and Image Composition ===


<pre>
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.
$ 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.
== Comps structure ==


If you think there needs to be a new group, please post on fedora-devel-list.
Comps are composed of elements and flags.


== How comps is used ==
=== 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


comps is used by the installer during package selection. In the package selection dialog (insert screenshot here), categories (as defined by the <code>category</code> keyword in <file>comps.xml</file>) are in the left-hand dialog. If a category is selected, any groups in that category with <code>uservisible</code> set are displayed in the right-hand pane. Groups have an icon associated with them. These icons come from the <code>comps-extras</code> package; icons are read from <code>/usr/share/pixmaps/comps/<group-id>.png</code>. If an icon does not exist for a group id, the one for the category that the group is in is used.
==== Package basearchonly flag ====


In yum, groups are used by the <code>yum groupinstall</code> and <code>yum groupremove</code> commands.
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.


In any group, there are four levels of packages: optional, default, mandatory, and conditional:
=== Comps element - arch flag ===


* <code>optional</code> are not automatic
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>).
* <code>default</code> are, but can be unchecked in a gui tool
* <code>mandatory</code> are always brought in (if group is selected)
* <code>conditional</code> are brought in if their <code>requires</code> package is installed


<insert some bits about PackageKit here>
=== Examples ===


Usually optional is the way, however if you feel that your package deserves a default or required level bring it up for discussion on fedora-devel-list.  Remember that this has effect on whether or not your package winds up on distribution media such as Live images and spins.
  <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>


== Package selection ==
== When to submit changes to comps ==


* If your app will show up in the application menu of the desktop, 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
* If you're creating a new option for an installation environment
* Libraries should not be included - they will be pulled in via dependencies
* 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.
* 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 fedora-devel-list.
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.
Some guidelines on specific groups in comps follows.
Line 48: Line 91:
=== New groups ===
=== New groups ===


Please consult fedora-devel-list before adding new groups.
Please consult {{fplist|devel}} before adding new groups.


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


=== 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.


=== [[SIGs/Desktop | GNOME Desktop ]] ===
=== [[SIGs/Desktop | GNOME Desktop ]] ===


The gnome-desktop group is maintained by the [[SIGs/Desktop | Desktop SIG]]. Please run changes through fedora-desktop-list.
The gnome-desktop group and GNOME environment definition is maintained by the [[SIGs/Desktop | Desktop SIG]]. Please run changes through {{fplist|desktop}}.


=== [[SIGs/KDE | KDE Desktop ]] ===
=== [[SIGs/KDE | KDE Desktop ]] ===


The kde-desktop group is maintained by the [[SIGs/KDE | KDE SIG]]. Please run changes by them.
The kde-desktop group and KDE environment definition is maintained by the [[SIGs/KDE | KDE SIG]]. Please run changes by them.


=== [[:Category:Fonts | Fonts]] ===
=== [[:Category:Fonts | Fonts]] ===
Line 73: Line 114:
{{:Fonts_SIG_signature}}
{{:Fonts_SIG_signature}}


=== Language support groups ===
=== All other groups ===
 
Language support groups are selected automatically if you are installing in the specified language, and manually otherwise. Language support groups require the <code>langonly</code> key, which should be set to ISO 639-1 two-letter language code for that language, or the ISO 639-2 bibliography code, if that does not exist.
These codes can be looked up in the <code>iso-codes</code> package.
 
Each language support group should have the following conditional packages, if the packages exist:
 
* hunspell dictionary for the language (requires hunspell)
* aspell dictionary for the language (requires aspell)
* openoffice.org langpack (requires openoffice.org-core)
* KDE 4 translations (kde-l10n-XXX,requires kdelibs)
* KDE 3 translations (kde-i18n-XXX,requires kdelibs3)
* KOffice langpack (requires koffice)
* Eclipse NLS support (requires eclipse-platform)
* man page translation (requires man-pages)
* gcompris sounds for the language (requires gcompris)
* moodle translations (requires moodle)
 
There may be other language specific subpackages necessary; this is not a fully inclusive list.
 
Each language support group should have mandatory packages for:
 
* fonts required for that locale (consult the [[:Category:Fonts SIG| Fonts SIG]])
* input methods, and data, required for that locale (consult the [[I18N| I18N SIG]])
 
Each language support group can have optional packages for:


* additional fonts that support that locale (consult the [[:Category:Fonts SIG| Fonts SIG]])
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.


New language support groups need added to the <code>language-support</code> category in the comps file.
== Developing comps ==


== How it works ==
For Fedora packagers:


Checkout the comps CVS module:
git clone ssh://git@pagure.io/fedora-comps.git


<code>cvs -d :ext:<username>@cvs.fedoraproject.org:/cvs/pkgs co comps</code>
For others:


then edit the proper <code>comps-f<x>.xml.in</code> file and commit your changes.
git clone https://pagure.io/fedora-comps.git


Please make sure to run <code>cvs update</code> right before <code>cvs commit</code> to
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].
avoid overwriting other people's changes as much as possible


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


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


[[Category:Comps_SIG]]
[[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.