Module sources consist of two main parts:

  1. RPM package sources

  2. module definition file

Both of these are stored in Fedora dist-git. Dist-git is organized into repositories, each having multiple branches.

When creating a new module, follow the process for adding new modules to Fedora.

Stream branching

Modularity introduced Stream Branching (formerly Arbitrary Branching) that is used for both module definitions and RPM packages that are part of modules.

Modules

Module definitions are stored in the /modules namespace and only consist of a modulemd file that defines the module itself.

Each module has a repository with branches corresponding to different streams. The repository and branch naming map to the module ID:

  • Repository name → module name

  • Branch name → stream name

  • Commit timestamp → module version

Packages

RPM Packages are stored in the /rpms namespace, and are also organized into stream branches. However, only the repository name map to the name of the package:

  • Repository name → package name

  • Branch name doesn’t map to anything, but is used as a reference in the module definition.

Defining modules using modulemd

Modules are defined using a modulemd file. It defines the following information:

  • summary and description

  • list of components (srpm name + branch)

  • "build" information

    • build groups

    • filter

    • macros

    • dependencies

  • "use" information

    • installation profiles

    • licenses

    • refs to community, docs, bug tracker

    • API

Example

The following example is modulemd version 1 that doesn’t support stream expansion. We are introducing a new version very soon.

modulemd.yaml

document: modulemd
version: 1
data:
    summary: An example module                          (1)
    description: >-
        A module for the demonstration                  (2)
        of the metadata format.
    license:
        module:
            - MIT                                       (3)
    dependencies:                                       (4)
        buildrequires:
            platform: f27
        requires:
            platform: f27
    references:                                         (5)
        community: http://www.example.com/
        documentation: http://www.example.com/
        tracker: http://www.example.com/
    profiles:                                           (6)
        default:
            rpms:
                - foo
                - foo-extras
        minimal:
            description: Minimal profile.
            rpms:
                - foo
    api:                                                (7)
        rpms:
            - foo
    components:                                         (8)
        rpms:
            foo:                                        (9)
                rationale: Our main package.            (10)
                ref: 2.4                                (11)
            bar:
                rationale: Some another package.
                ref: latest
1 A short summary describing the module.
2 A longer summary describing the module.
3 Licence of this modulemd file.
4 Other modules and their streams that are used as runtime and build dependencies. "platform" is a reserved word for the Fedora releases. The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. In this version of modulemd (v1) there is no support for stream expansion. That means that only one release can be selected. However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones.
5 Various references to the upstream.
6 Installation profiles that will help users to install the module. Keep in mind that not all the packages from the module need to be installed.
7 The module’s public RPM-level API. A list of binary RPM names that are considered to be the main and stable feature of the module
8 List of packages that are part of this module.
9 Name of a package.
10 A rationale why the package has been included. This is only for humans.
11 A dist-git branch of the package.