docs: Add a basic info about gathering packages

Signed-off-by: Lubomír Sedlář <lsedlar@redhat.com>
This commit is contained in:
Lubomír Sedlář 2017-05-16 15:36:05 +02:00
parent 65b75e7049
commit 65bc6969e2
3 changed files with 71 additions and 1 deletions

69
doc/gathering.rst Normal file
View File

@ -0,0 +1,69 @@
==================
Gathering packages
==================
A compose created by Pungi consists of one or more variants. A variant contains
a subset of the content targeted at a particular use case.
There are different types of variants. The type affects how packages are
gathered into the variant.
The inputs for gathering are defined by the ``gather_source`` option. It
provides a list of package names, comps groups names and a list of packages
that should be filtered out.
Next, ``gather_method`` defines how the list is processed. For ``nodeps``, the
results from source are used pretty much as is [#]_. For ``deps`` method, a
process will be launched to figure out what dependencies are needed and those
will be pulled in.
.. [#] The lists are filtered based on what packages are available in the
package set, but nothing else will be pulled in.
Variant types
=============
*Variant*
is a base type that has no special behaviour.
*Addon*
is built on top of a regular variant. Any packages that should go to both
the addon and its parent will be removed from addon. Packages that are only
in addon but pulled in because of ``gather_fulltree`` option will be moved
to parent.
*Integrated Layered Product*
works similarly to *addon*. Additionally, all packages from addons on the
same parent variant are removed integrated layered products.
The main difference between an *addon* and *integrated layered product* is
that *integrated layered product* has its own identity in the metadata
(defined with product name and version).
.. note::
There's also *Layered Product* as a term, but this is not related to
variants. It's used to describe a product that is not a standalone
operating system and is instead meant to be used on some other base
system.
*Optional*
contains packages that complete the base variants' package set. It always
has ``fulltree`` and ``selfhosting`` enabled, so it contains build
dependencies and packages which were not specifically requested for base
variant.
Some configuration options are overridden for particular variant types.
.. table:: Depsolving configuration
+-----------+--------------+--------------+
| Variant | Fulltree | Selfhosting |
+===========+==============+==============+
| base | configurable | configurable |
+-----------+--------------+--------------+
| addon/ILP | enabled | disabled |
+-----------+--------------+--------------+
| optional | enabled | enabled |
+-----------+--------------+--------------+

View File

@ -18,3 +18,4 @@ Contents:
configuration configuration
messaging messaging
phases phases
gathering

View File

@ -47,7 +47,7 @@ Gather
This phase uses data collected by ``pkgset`` phase and figures out what This phase uses data collected by ``pkgset`` phase and figures out what
packages should be in each variant. The basic mapping can come from comps file, packages should be in each variant. The basic mapping can come from comps file,
a JSON mapping or ``additional_packages`` config option. This inputs can then a JSON mapping or ``additional_packages`` config option. This inputs can then
be enriched by adding all dependencies. be enriched by adding all dependencies. See :doc:`gathering` for details.
Once the mapping is finalized, the packages are linked to appropriate places Once the mapping is finalized, the packages are linked to appropriate places
and the ``rpms.json`` manifest is created. and the ``rpms.json`` manifest is created.