Fedora Packaging Guidelines for Modules¶

Document header and the data section¶

Every modulemd file MUST contain a modulemd document header which consists of the document type tag and the document format version, and a data section holding the module data.

document: modulemd
version: 1
data:
    (...)

The version is an integer and denotes the version of the metadata format the rest of the document is written in. As of now, only one officialy released version of the format exists, version 1.

Module summary and description¶

Every module MUST include human-readable short summary and description. Both should be written in US English.

summary: An example module
description: >
    An example long description of an example module, written just
    to demonstrate the purpose of this field.

The summary is a one sentence concise description of the module and SHOULD NOT end in a period.

The description expands on this and SHOULD end in a period. Description SHOULD NOT contain installation instructions or configuration manuals.

Module licensing¶

Every module MUST contain a license section and declare a list of the module’s licenses. Note these aren’t the module’s components’ licenses.

license:
    module:
        - MIT

Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. Therefore MIT might be a reasonable default for most module authors as well.

See the module content licensing section for details on how to declare components’ licenses.

Module name, update stream and version¶

Every module SHOULD define its name, update stream and version.

name: example
stream: another-example
version: 20161109235500

Note, however, that module packagers SHOULD NOT define these values manually but rather expect the Module Build Service to do it for them, using the module’s dist-git repository name as the module name, the dist-git repository branch name as the stream name and the particular commit timestamp as the version. This simplifies module rebuilds and moving modules between branches or repositories.

Packagers MAY override this behaviour by defining these fields themselves. This behavior may change in the future.

There are currently no formal restrictions for the format of the name and stream properties. The version, however, must be an unsigned integer.

Module content licensing¶

If the module includes some RPM or non-RPM content, the packager MAY also define a list of content licenses.

license:
    module:
        - MIT
    content:
        - GPL+
        - BSD

Not every module includes packages and therefore doesn’t necessarily have to include this field.

Furthermore, the content licenses list should ideally be automatically filled by module build tools rather than the module author.

Module dependencies¶

Modules MAY depend on other modules. These module relationships are listed in the depepdencies section. Dependencies are expressed using module names and their stream names.

dependencies:
    buildrequires:
        generational-core: master
    requires:
        generational-core: master

So far modulemd supports two kinds of dependencies:

• buildrequires for listing build dependencies of the module, i.e. modules that define the buildroot for building the module’s components; this will typically be the generational-core module, at minimum
• requires for listing runtime dependencies of the module, i.e. modules that need to be available on the target system for this module to work properly; this too will typically be the generational-core module, at minimum

Either or both of these sections may be omitted, if necessary.

Extensible module metadata block¶

Modules MAY also contain an extensible metadata block, a list of vendor-defined key-value pairs.

xmd:
    user-defined-key: 42
    another-user-defined-key:
        - the first value of the list
        - the second value of the list

Module references¶

Modules MAY define links referencing various upstream resources, such as community website, project documentation or upstream bug tracker.

references:
    community: http://www.example.com/
    documentation: http://www.example.com/docs/1.23/
    tracker: http://www.example.com/bugs/

Module profiles¶

The module author MAY define lists of packages that would be installed by default, and a minimum, when the module is enabled and the particular profile is selected. Whether the packages actually get installed depends on the user’s configuration. It is possible to define a profile that doesn’t install any packages.

Profile names are arbitrary strings. There is currently one special-purpose profile name defined — default. More special-purpose profile names might be defined in the future.

The default profile lists packages that would be installed unless the user’s configuration dictates otherwise.

In the case of RPM content, the profile package lists reference binary RPM package names.

profiles:
    default:
        rpms:
            - myapplication
            - myapplication-plugins
    minimal:
        description: An example minimal profile installing only the myapplication package.
        rpms:
            - myapplication

Module API¶

Module API are components, symbols, files or abstract features the module explicitly declares to be its supported interface. Everything else is considered an internal detail and shouldn’t be relied on by any other module.

Every module SHOULD define its public API.

api:
    rpms:
        - mypackage
        - mylibrary
        - mylibrary-devel

Currently the only supported type of API are binary RPM packages, that is the list of RPMs that are guaranteed to a) be present in the module, and b) not break their interfaces such as binaries their provide or their ABI.

Module filters¶

Module filters define lists of components or other content that should not be part of the resulting, composed module deliverable. They can be used to only ship a limited subset of generated RPM packages, for instance.

filter:
    rpms:
        - mypackage-plugins

Currently the only supported type of filter are binary RPM packages.

Module components¶

Modules MAY, and most modules do contain a components section defining the module’s content.

components:
    (...)

components:
    rpms:
        foo:
            rationale: The key component of this module.
            buildorder: 100
            repository: git://git.example.com/foo.git
            ref: branch-tag-or-commit-hash
            cache: http://www.example.com/lookasidecache/
            arches:
                - i686
                - x86_64
            multilib:
                - x86_64
        dependency-of-foo:
            rationale: Needed for foo.
            buildorder: 50
            repository: git://git.example.com/dependency-of-foo.git
            ref: master
            cache: http://www.example.com/lookasidecache/
            arches: [ i686, x86_64 ]
            multilib: [ x86_64 ]

components:
    modules:
        my-favourite-module:
            rationale: An example of an included module.
            buildorder: 20
            repository: git://git.example.com/my-favourite-module.git
            ref: 12ab34cd5

Minimal module¶

A minimal module distributed as example-master-20161109172409, stored in the modules/example dist-git repository and its master branch, built on November 9, 2016, at 17:24:09 UTC, containing no packages, having no dependencies whatsoever and defining only the minimal set of required metadata.

document: modulemd
version: 1
data:
    summary: An example summary
    description: And an example description.
    license:
        module:
            - MIT

Minimal module with RPM content¶

Another flavour of the abovementioned module, containing one RPM package with SRPM name foo. This module doesn’t define any dependencies or optional metadata.

document: modulemd
version: 1
data:
    summary: An example summary
    description: And an example description.
    license:
        module:
            - MIT
    components:
        rpms:
            foo:
                rationale: An example RPM component.

Minimal module with RPM content but with the -docs subpackage excluded¶

Yet another flavour of the minimal module, containing one RPM package with SRPM name foo. A build of foo creates binary packages foo-1.0-1 and the subpackage foo-doc-1.0-1. Both would get included in the module for any architecture if no filter were be used. This module doesn’t define any dependencies or optional metadata.

document: modulemd
version: 1
data:
    summary: An example summary
    description: And an example description.
    license:
        module:
            - MIT
    filter:
        rpms:
            - foo-docs
    components:
        rpms:
            foo:
                rationale: An example RPM component.

Minimal module with dependencies only (a variant of stack)¶

Another minimal module, containing no packages or any optional metadata besides dependencies. Modules of this type are, together with modules that include other modules, referred to as stacks.

document: modulemd
version: 1
data:
    summary: An example summary
    description: And an example description.
    license:
        module:
            - MIT
    dependencies:
        requires:
            generational-core: master
            a-framework-module: and-its-stream

Minimal module which includes another (another variant of stack)¶

Yet another minimal module, containing no optional metadata besides a single included module in the components section. Modules of this type are, together with modules that only depend on other modules, referred to as stacks.

document: modulemd
version: 1
data:
    summary: An example summary
    description: And an example description.
    license:
        module:
            - MIT
    content:
        modules:
            a-framework-module:
                rationale: Bundled for various reasons.

Common Fedora module¶

A typical Fedora module defines all the mandatory metadata plus some useful references, has build and runtime dependencies and contains one or more packages built from specific refs in dist-git. It relies on the Module Build Service to extract the name, stream and version properties from the VCS data and to fill in the licensing information from the included components and populate the data → license → content list.

document: modulemd
version: 1
data:
    summary: An example of a common Fedora module
    description: This module demonstrates what most Fedora modules look like.
    license:
        module: [ MIT ]
    dependencies:
        buildrequires:
            generational-core: master
            extra-build-environment: master
        requires:
            generational-core: master
    references:
        community: http://www.example.com/common-package
        documentation: http://www.example.com/common-package/docs/5.67/
    profiles:
        default:
            rpms:
                - common-package
                - common-plugins
        development:
            rpms:
                - common-package
                - common-package-devel
                - common-plugins
    api:
        rpms:
            - common-package
            - common-package-devel
            - common-plugins
    components:
        rpms:
            common-package:
                rationale: The key component of this module.
                ref: common-release-branch
            common-plugins:
                rationale: Extensions for common-package.
                buildorder: 1
                ref: common-release-branch

Complete module definition¶

See the modulemd specification.