Modulemd.ModuleIndexMerger: Modulemd Reference Manual

Modulemd.ModuleIndexMerger

Modulemd.ModuleIndexMerger — Class to aid in merging metadata from multiple repositories.

Stability Level

Stable, unless otherwise indicated

Functions

ModulemdModuleIndexMerger *	modulemd_module_index_merger_new ()
void	modulemd_module_index_merger_associate_index ()
ModulemdModuleIndex *	modulemd_module_index_merger_resolve ()
ModulemdModuleIndex *	modulemd_module_index_merger_resolve_ext ()

Types and Values

#define	MODULEMD_TYPE_MODULE_INDEX_MERGER
	ModulemdModuleIndexMerger

Object Hierarchy

    GObject
    ╰── ModulemdModuleIndexMerger

Description

ModuleIndexMerger is used to resolve merges between multiple repository metadata sources, possibly with varying priorities.

It is expected to be used as follows (python example) by tools such as yum:

merger = Modulemd.ModuleIndexMerger.new()

merger.associate_index(fedora_repo_index, 0)
merger.associate_index(updates_repo_index, 0)
merger.associate_index(updates_testing_repo_index, 0)

merged_index = merger.resolve()

In the above code, merged_index will be a complete, merged view of the metadata from all of the added ModulemdModuleIndex instances.

When merging module streams, entries will be deduplicated based on whether they share the same module name, stream name, version number, and context. If the repository configuration is broken and there exists two ModulemdModuleStream entries that have different content for the same NSVCA, the behavior is undefined.

Merging ModulemdDefaults entries behaves as follows (note that this behavior has changed slightly as of 2.8.1):

Any module defaults object that is provided by a single ModulemdModuleIndex will be the defaults object in the resulting merged ModulemdModuleIndex.
If the ModulemdModuleIndex inputs have different priorities (not common), then the defaults from the highest priority ModulemdModuleIndex will be used and the others entirely discarded. The modified value will not be considered at all. (Priority is intended for providing a total override, including an on-disk configuration).
If the repos have the same priority (such as "fedora" and "updates" in the Fedora Project) and modified value, the entries will be merged as follows for default streams:
- If both ModulemdModuleIndex objects specify the same default stream for the module, that one will be used.
- If either ModulemdModuleIndex specifies a default stream for the module and the other does not, the provided one will be used.
- If both ModulemdModuleIndex objects specify different default streams and have different modified values, the default stream from the ModulemdDefaults object with the higher modified value will be used.
- If both ModulemdModuleIndex objects specify different default streams and have the same modified value, the merge will unset the default stream and leave no default stream in the resulting merged ModulemdModuleIndex. This behavior can be controlled by using modulemd_module_index_merger_resolve_ext() and setting strict_default_streams to TRUE. In that case, an error will be returned if conflicting default streams have been provided.
and for profile defaults:
- If both ModulemdModuleIndex objects specify a set of default profiles for a particular module and stream and the sets are equivalent, use that set.
- If one ModulemdModuleIndex object specifies a set of default profiles for a module and stream and the other does not, use the provided set.
- If both ModulemdModuleIndex objects specify a set of default profiles for a stream, each are providing a different set and the modified value differs, the set from the object with the higher modified value will be used.
- If both ModulemdModuleIndex objects specify a set of default profiles for a stream, each are providing a different set and the modified value is the same, this is an unresolvable merge conflict and the merge resolution will fail and return an error.
- Intents behave in exactly the same manner as described for the top-level defaults, except that they merge beneath each intent name. Intents are deprecated.

Merging ModulemdTranslations entries behaves as follows:

For each translated summary, description and profile description, compare the modified value of the Translation document matching this module name and stream. Whichever has the higher value will be used. Any translation containing the empty string will be interpreted as removing the translation. Subsequent processing of a higher modified value may restore it.

Merging ModulemdObsoletes entries with identical module, stream, context and modified values behaves as follows (when accessed through module):

Any obsoletes object that is provided by a single ModulemdModuleIndex will be the obsoletes object in the resulting merged ModulemdModuleIndex.
If the ModulemdModuleIndex inputs have different priorities (not common), then the obsoletes from the highest priority ModulemdModuleIndex will be used and the others entirely discarded. (Priority is intended for providing a total override, including an on-disk configuration).
If the repos have the same priority (such as "fedora" and "updates" in the Fedora Project) the behaviour is undefined.

Functions

modulemd_module_index_merger_new ()

ModulemdModuleIndexMerger *
modulemd_module_index_merger_new (void);

Returns

A newly-allocated ModulemdModuleIndexMerger object.

[transfer full]

Since: 2.0

modulemd_module_index_merger_associate_index ()

void
modulemd_module_index_merger_associate_index
                               (ModulemdModuleIndexMerger *self,
                                ModulemdModuleIndex *index,
                                gint32 priority);

Enqueues a ModulemdModuleIndex representing the parsed metadata from a repository into this ModulemdModuleIndexMerger for merging and deduplication of other repositories.

Once all repositories have been added, call modulemd_module_index_merger_resolve() to perform the merge.

Parameters

self	This ModulemdModuleIndexMerger object.	[in]
index	A ModulemdModuleIndex, usually constructed by reading the module metadata from a repository with `modulemd_module_index_update_from_file()`, `modulemd_module_index_update_from_string()`, or `modulemd_module_index_update_from_stream()`. This function take a reference on `index` , so the caller must not modify it while the ModulemdModuleIndexMerger is in use.	[in][transfer none]
priority	The priority of the repository that the entries in `index` came from. This is used to determine when `index` should override rather then merge. In most cases, this will be zero. See the Description section for the ModulemdModuleIndexMerger class for details on the merge logic. Acceptable values are in the range of 0-1000.	[in]

Since: 2.0

modulemd_module_index_merger_resolve ()

ModulemdModuleIndex *
modulemd_module_index_merger_resolve (ModulemdModuleIndexMerger *self,
                                      GError **error);

Merges all added ModulemdModuleIndex objects according to their priority. The logic of this merge is described in the Description of ModulemdModuleIndexMerger.

Once this function has been called, the internal state of the ModulemdModuleIndexMerger is undefined. The only valid action on it after that point is g_object_unref().

This function is equivalent to calling modulemd_module_index_merger_resolve_ext() with strict_default_streams=FALSE.

Parameters

self	This ModulemdModuleIndexMerger object.	[in]
error	A GError containing the reason for a failure to resolve the merges.	[out]

Returns

A newly-allocated ModulemdModuleIndex object containing the merged results. If this function encounters an unresolvable merge conflict, it will return NULL and set error appropriately.

[transfer full]

Since: 2.0

modulemd_module_index_merger_resolve_ext ()

ModulemdModuleIndex *
modulemd_module_index_merger_resolve_ext
                               (ModulemdModuleIndexMerger *self,
                                gboolean strict_default_streams,
                                GError **error);

Merges all added ModulemdModuleIndex objects according to their priority. The logic of this merge is described in the Description of ModulemdModuleIndexMerger.

Once this function has been called, the internal state of the ModulemdModuleIndexMerger is undefined. The only valid action on it after that point is g_object_unref().

Parameters

self	This ModulemdModuleIndexMerger object.	[in]
strict_default_streams	If TRUE, merging two ModulemdDefaults with conflicting default streams will raise an error. If FALSE, the module will have its default stream blocked.	[in]
error	A GError containing the reason for a failure to resolve the merges.	[out]

Returns

A newly-allocated ModulemdModuleIndex object containing the merged results. If this function encounters an unresolvable merge conflict, it will return NULL and set error appropriately.

[transfer full]

Since: 2.6

Types and Values

MODULEMD_TYPE_MODULE_INDEX_MERGER

#define             MODULEMD_TYPE_MODULE_INDEX_MERGER

ModulemdModuleIndexMerger

typedef struct _ModulemdModuleIndexMerger ModulemdModuleIndexMerger;