From Fedora Project Wiki

m (Another typo fixed.)
 
(44 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
 
using the following as a template if your package were named "foo":
 
  
<packagereq type="optional">foo</packagereq>
+
=== Installation ===
 +
 
 +
comps is used by the installer during software selection. At the installer
 +
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
 +
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 ===
 +
 
 +
In [[dnf]], groups are used by:
 +
 
 +
dnf [options] group [summary] <group-spec>
 +
Display overview of how many groups are installed and available. With a spec, limit the output to the matching groups. summary is the default groups subcommand.
 +
 
 +
 
 +
dnf [options] group info <group-spec>
 +
Display package lists of a group. Shows which packages are installed or available from a repo when -v is used.
 +
 
 +
 
 +
dnf [options] group install [--with-optional] <group-spec>...
 +
Mark the specified group installed and install packages it contains. Also include optional packages of the group if --with-optional is specified.
 +
 
 +
 
 +
dnf [options] group list <group-spec>...
 +
List all matching groups, either among installed or available groups. If nothing is specified list all known groups. Records are ordered by display_order tag defined in comps.xml file.
 +
 
 +
 
 +
dnf [options] group remove <group-spec>...
 +
Mark the group removed and remove those packages in the group from the system which are neither comprising another installed group and were not installed explicitly by the user.
 +
 
 +
 
 +
dnf [options] group upgrade <group-spec>...
 +
Upgrades the packages from the group and upgrades the group itself. The latter comprises of installing pacakges that were added to the group by the distribution and removing packages that got removed from the group as far as they were not installed explicitly by the user.
 +
 
 +
 
 +
Groups can also be marked installed or removed without physically manipulating any packages:
 +
 
 +
dnf [options] group mark install <group-spec>...
 +
Mark the specified group installed. No packages will be installed by this command but the group is then considered installed.
 +
 
 +
 
 +
dnf [options] group mark remove <group-spec>...
 +
Mark the specified group removed. No packages will be removed by this command.
 +
 
 +
=== Tree, Release, and Image Composition ===
 +
 
 +
The kickstart files in [https://pagure.io/fedora-kickstarts fedora-kickstarts] use the group definitions from comps to compose
 +
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 environment instead as such:
 +
@standard
 +
@guest-agents
 +
 
 +
This is found in the comps.xml under the environment you wish to use.
 +
 
 +
== Comps structure ==
 +
 
 +
COMPS are composed from elements and flags
 +
 
 +
=== Comps element - category ===
 +
 
 +
=== Comps element - environment ===
 +
 
 +
Environmental group is composed of list of mandatory groups and optional groups. Mandatory groups have to be installed for successful install of environmental group.
 +
 
 +
  <environment>
 +
  <id>env1</id>
 +
  <name>Env One</name>
 +
    <grouplist>
 +
      <groupid>group1</groupid>
 +
    </grouplist>
 +
    <optionlist>
 +
      <groupid>group2</groupid>
 +
    </optionlist>
 +
  </environment>
 +
 
 +
=== Comps element - group ===
  
* Make sure to preserve the alphabetical order in each group.
+
Groups are composed from list of packages of four types (see Comps element - package)
* 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:
+
=== Comps element - package ===
  
<pre>
+
There are four types of packages
$ xsltproc --novalid -o sorted-file comps-cleanup.xsl original-file
+
* mandatory
</pre>
+
** 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>
 +
* conditional
 +
** are brought in transaction if their required package is installed or about to be installed
  
The filter will warn you if it removes redundant information or if something needs to be checked by a human.
+
==== Package basearchonly flag ====
  
If you think there needs to be a new group, please post on fedora-devel-list.
+
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 ===
  
== Some background ==
+
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. Like if I have <code><packagereq type="mandatory" arch="i686,s390">pkg-c</packagereq></code> in comps the package will be installed only on systems with <code>basearch</code> <code>i686</code> or <code>s390</code>. It means that the pkg-c will be even not installed on system with compatible architecture like <code>x86_64</code>.
  
There are three levels of packages: optional, default, and required
+
=== Examples ===
* <code>optional</code> are not automatic
 
* <code>default</code> are, but can be unchecked in a gui tool
 
* <code>required</code> are always brought in (if group is selected)
 
* <code>conditional</code> are brought in if their <code>requires</code> 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 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 42: Line 133:
 
=== 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.
 
  
In the installer, visible 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.
+
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 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.
+
Core is installed on every installation, so adding packages to it is discouraged. Please run changes by the [[SIGs/Minimal_Core | Minimal Core SIG]].
  
 
=== [[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]] ===
{{CompactHeader|fonts-sig}}
+
 
 
The following is part of the [[:Category:Fonts SIG| Fonts SIG]]  [[:Category:Fonts_packaging | packaging rules]].
 
The following is part of the [[:Category:Fonts SIG| Fonts SIG]]  [[:Category:Fonts_packaging | packaging rules]].
  
Line 69: Line 158:
 
{{: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.
+
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.
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:
+
== How to submit changes to comps ==
  
* hunspell dictionary for the language (requires hunspell)
+
Fork the fedora-comps git module in Pagure at https://pagure.io/fedora-comps. Then you can clone your fork:
* 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.
+
<pre>git clone ssh://git@pagure.io/forks/&lt;username&gt;/fedora-comps.git</pre>
  
Each language support group should have mandatory packages for:
+
Substitute your FAS username for &lt;username&gt; above.  Then checkout a branch, using whatever name you prefer (a descriptive name is helpful):
  
* fonts required for that locale (consult the [[:Category:Fonts SIG| Fonts SIG]])
+
<pre>git checkout -b &lt;branch-name&gt;</pre>
* input methods, and data, required for that locale (consult the [[I18N| I18N SIG]])
 
  
Each language support group can have optional packages for:
+
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":
  
* additional fonts that support that locale (consult the [[:Category:Fonts SIG| Fonts SIG]])
+
<packagereq type="optional">foo</packagereq>
  
New language support groups need added to the <code>language-support</code> category in the comps file.
+
* 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.
  
== How it works ==
+
You can use the provided xslt filter to sort, indent and check the syntax of your comps file in one run:
  
Checkout the comps CVS module:
+
<pre>
 +
$ xsltproc --novalid -o sorted-file comps-cleanup.xsl original-file
 +
</pre>
  
<code>cvs -d :ext:<username>@cvs.fedoraproject.org:/cvs/pkgs co comps</code>
+
The filter will warn you if it removes redundant information or if something needs to be checked by a human.
  
then edit the proper <code>comps-f<x>.xml.in</code> file and commit your changes.
+
Commit your changes (<code>git commit -a</code>). You
 +
can then push your changes to the repository with <code>git push origin &lt;branch-name&gt;</code>.
  
Please make sure to run <code>cvs update</code> right before <code>cvs commit</code> to
+
You can then file a pull request from your new branch in the Pagure interface.
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 09:42, 30 August 2018

How comps is used

Installation

comps is used by the installer during software selection. At the installer 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 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

In dnf, groups are used by:

dnf [options] group [summary] <group-spec>

Display overview of how many groups are installed and available. With a spec, limit the output to the matching groups. summary is the default groups subcommand.


dnf [options] group info <group-spec>

Display package lists of a group. Shows which packages are installed or available from a repo when -v is used.


dnf [options] group install [--with-optional] <group-spec>...

Mark the specified group installed and install packages it contains. Also include optional packages of the group if --with-optional is specified.


dnf [options] group list <group-spec>...

List all matching groups, either among installed or available groups. If nothing is specified list all known groups. Records are ordered by display_order tag defined in comps.xml file.


dnf [options] group remove <group-spec>...

Mark the group removed and remove those packages in the group from the system which are neither comprising another installed group and were not installed explicitly by the user.


dnf [options] group upgrade <group-spec>...

Upgrades the packages from the group and upgrades the group itself. The latter comprises of installing pacakges that were added to the group by the distribution and removing packages that got removed from the group as far as they were not installed explicitly by the user.


Groups can also be marked installed or removed without physically manipulating any packages:

dnf [options] group mark install <group-spec>...

Mark the specified group installed. No packages will be installed by this command but the group is then considered installed.


dnf [options] group mark remove <group-spec>...

Mark the specified group removed. No packages will be removed by this command.

Tree, Release, and Image Composition

The kickstart files in fedora-kickstarts use the group definitions from comps to compose 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 environment instead as such: @standard @guest-agents

This is found in the comps.xml under the environment you wish to use.

Comps structure

COMPS are composed from elements and flags

Comps element - category

Comps element - environment

Environmental group is composed of list of mandatory groups and optional groups. Mandatory groups have to be installed for successful install of environmental 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 from list 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’
  • 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. Like if I have <packagereq type="mandatory" arch="i686,s390">pkg-c</packagereq> in comps the package will be installed only on systems with basearch i686 or s390. It means that the pkg-c will be even not installed on system with compatible architecture like 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 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 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.

How to submit changes to comps

Fork the fedora-comps git module in Pagure at https://pagure.io/fedora-comps. Then you can clone your fork:

git clone ssh://git@pagure.io/forks/<username>/fedora-comps.git

Substitute your FAS username for <username> above. Then checkout a branch, using whatever name you prefer (a descriptive name is helpful):

git checkout -b <branch-name>

Then, find a reasonable group in the comps-fnxml.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:

$ xsltproc --novalid -o sorted-file comps-cleanup.xsl original-file

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

Commit your changes (git commit -a). You can then push your changes to the repository with git push origin <branch-name>.

You can then file a pull request from your new branch in the Pagure interface.

Current status

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