xref: /dports/misc/libmodulemd/modulemd-2.13.0/yaml_specs/modulemd_packager_v3.yaml

##############################################################################
# Glossary:                                                                  #
#                                                                            #
# build system: The process by which a module is built and packaged. In many #
# cases, this will be the Module Build Service tool, but this term is used   #
# as a catch-all to describe any mechanism for producing a yum repository    #
# containing modular content from input module metadata files.               #
#                                                                            #
#                                                                            #
# == Attribute Types ==                                                      #
#                                                                            #
# MANDATORY: Attributes of this type must be filled in by the packager of    #
# this module. They must also be preserved and provided in the output        #
# metadata produced by the build system for inclusion into a repository.     #
#                                                                            #
# OPTIONAL: Attributes of this type may be provided by the packager of this  #
# module, when appropriate. If they are provided, they must also be          #
# preserved and provided in the output metadata produced by the build        #
# system for inclusion into a repository.                                    #
#                                                                            #
# AUTOMATIC: Attributes of this type must be present in the repository       #
# metadata, but they may be left unspecified by the packager. In this case,  #
# the build system is responsible for generating an appropriate value for    #
# the attribute and including it in the repository metadata. If the packager #
# specifies this attribute explicitly, it must be preserved and provided in  #
# the output metadata for inclusion into a repository.                       #
#                                                                            #
# The definitions above describe the expected behavior of the build system   #
# operating in its default configuration. It is permissible for the build    #
# system to override user-provided entries through non-default operating     #
# modes. If such changes are made, all items indicated as being required for #
# the output repository must still be present.                               #
##############################################################################


# Document type identifier
# `document: modulemd-packager` describes the contents of a packager's input
# for a module stream.
document: modulemd-packager

# Module metadata format version
version: 3

data:
    # name:
    # The name of the module
    # Filled in by the build system, using the VCS repository name as the name
    # of the module.
    #
    # Type: AUTOMATIC
    #
    # Mandatory for module metadata in a yum/dnf repository.
    name: foo

    # stream:
    # Module update stream
    # Filled in by the buildsystem, using the VCS branch name as the name of
    # the stream.
    #
    # Type: AUTOMATIC
    #
    # Mandatory for module metadata in a yum/dnf repository.
    stream: latest

    # summary:
    # A short summary describing the module
    #
    # Type: MANDATORY
    #
    # Mandatory for module metadata in a yum/dnf repository.
    summary: An example module

    # description:
    # A verbose description of the module
    #
    # Type: MANDATORY
    #
    # Mandatory for module metadata in a yum/dnf repository.
    description: >-
        A module for the demonstration of the metadata format. Also,
        the obligatory lorem ipsum dolor sit amet goes right here.

    # license:
    # Module license
    # This list covers licenses used for the module metadata and
    # possibly other files involved in the creation of this specific
    # module. If unspecified, the default license for documents of this
    # type and version is MIT (https://opensource.org/licenses/MIT)
    #
    # Type: OPTIONAL
    license:
        - MIT
    # xmd:
    # Extensible metadata block
    # A dictionary of user-defined keys and values.
    # Defaults to an empty dictionary.
    #
    # Type: OPTIONAL
    xmd:
        some_key: some_data

    # configurations:
    # A list of build and dependency configurations
    #
    # Each entry in the list represents a build of this module stream against
    # one platform (usually a distribution release name/number) and optionally
    # a set of dependencies.
    #
    # Type: MANDATORY
    configurations:
        # context:
        # A string of up to ten [a-zA-Z0-9] characters representing a
        # a build and runtime configuration for this stream. This string is
        # arbitrary but must be unique in this module stream.
        # Type: MANDATORY
        - context: CTX1
          # platform:
          # Defines the distribution and release to build on and run against.
          # Type: MANDATORY
          platform: f32
          # buildrequires:
          # A dictionary of the build-time dependencies on other module streams.
          # Each configuration may depend on a single stream of a dependency.
          # The dictionary key is the name of the module and the dictionary value
          # is a single-element list containing the name of the stream.
          #
          # Type: Optional
          buildrequires:
              appframework: [v1]
          # requires:
          # A dictionary of the run-time dependencies on other module streams.
          # Each configuration may depend on a single stream of a dependency.
          # The dictionary key is the name of the module and the dictionary value
          # is a single-element list containing the name of the stream.
          #
          # Type: Optional
          requires:
              appframework: [v1]
          # buildopts:
          # Component build options
          # Additional per component type module-wide build options.
          #
          # IMPORTANT: Due to limitations in the modulemd-stream v2 format, the
          # buildopts from the first configuration in the list will apply to
          # ALL configurations when building for modulemd-stream v2. They will
          # apply separately when building for module-stream v3.
          #
          # Type: OPTIONAL
          buildopts:
            # rpms:
            # RPM-specific build options
            #
            # Type: OPTIONAL
            rpms:
                # macros:
                # Additional macros that should be defined in the
                # RPM buildroot, appended to the default set.  Care should be
                # taken so that the newlines are preserved.  Literal style
                # block is recommended, with or without the trailing newline.
                #
                # Type: OPTIONAL
                macros: |
                    %demomacro 1
                    %demomacro2 %{demomacro}23

                # whitelist:
                # Explicit list of package build names this module will produce.
                # By default the build system only allows components listed under
                # data.components.rpms to be built as part of this module.
                # In case the expected RPM build names do not match the component
                # names, the list can be defined here.
                # This list overrides rather then just extends the default.
                # List of package build names without versions.
                #
                # Type: OPTIONAL
                whitelist:
                    - fooscl-1-bar
                    - fooscl-1-baz
                    - xxx
                    - xyz
            # arches:
            # Instructs the build system to only build the
            # module on this specific set of architectures.
            # Includes specific hardware architectures, not families.
            # See the data.arch field in the modulemd-stream spec for details.
            # Defaults to all available arches.
            #
            # Type: OPTIONAL
            arches: [i686, x86_64]

        # Alternate example with no dependencies
        - context: CTX2
          platform: f33

    # references:
    # References to external resources, typically upstream
    #
    # Type: OPTIONAL
    references:
        # community:
        # Upstream community website, if it exists
        #
        # Type: OPTIONAL
        community: http://www.example.com/

        # documentation:
        # Upstream documentation, if it exists
        #
        # Type: OPTIONAL
        documentation: http://www.example.com/

        # tracker:
        # Upstream bug tracker, if it exists
        #
        # Type: OPTIONAL
        tracker: http://www.example.com/

    # profiles:
    # Profiles define the end user's use cases for the module. They consist of
    # package lists of components to be installed by default if the module is
    # enabled. The keys are the profile names and contain package lists by
    # component type. There are several profiles defined below. Suggested
    # behavior for package managers is to just enable repository for selected
    # module. Then users are able to install packages on their own. If they
    # select a specific profile, the package manager should install all
    # packages of that profile.
    # Defaults to no profile definitions.
    #
    # Type: OPTIONAL
    profiles:

        # An example profile that defines a set of packages which are meant to
        # be installed inside a container image artifact.
        #
        # Type: OPTIONAL
        container:
            rpms:
                - bar
                - bar-devel

        # An example profile that delivers a minimal set of packages to
        # provide this module's basic functionality. This is meant to be used
        # on target systems where size of the distribution is a real concern.
        #
        # Type: Optional
        minimal:
            # A verbose description of the module, optional
            description: Minimal profile installing only the bar package.
            rpms:
                - bar
            # default (boolean):
            # Whether this profile should be installed if none is explicitly
            # specified.
            #
            # Defaults to "false" if not specified.
            #
            # Type: OPTIONAL
            default: true

        # buildroot:
        # This is a special reserved profile name.
        #
        # This provides a listing of packages that will be automatically
        # installed into the buildroot of all component builds that are started
        # after a component builds with its `buildroot: True` option set.
        #
        # The primary purpose of this is for building RPMs that change
        # the build environment, such as those that provide new RPM
        # macro definitions that can be used by subsequent builds.
        #
        # Specifically, it is used to flesh out the build group in koji.
        #
        # Type: OPTIONAL
        buildroot:
            rpms:
                - bar-devel

        # srpm-buildroot:
        # This is a special reserved profile name.
        #
        # This provides a listing of packages that will be automatically
        # installed into the buildroot of all component builds that are started
        # after a component builds with its `srpm-buildroot: True` option set.
        #
        # The primary purpose of this is for building RPMs that change
        # the build environment, such as those that provide new RPM
        # macro definitions that can be used by subsequent builds.
        #
        # Very similar to the buildroot profile above, this is used by the
        # build system to specify any additional packages which should be
        # installed during the buildSRPMfromSCM step in koji.
        #
        # Type: OPTIONAL
        srpm-buildroot:
            rpms:
                - bar-extras

    # api:
    # Module API
    # Defaults to no API.
    #
    # Type: OPTIONAL
    api:
        # rpms:
        # 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; binary RPMs not listed
        # here are considered "unsupported" or "implementation details".
        # In the example here we don't list the xyz package as it's only
        # included as a dependency of xxx.  However, we list a subpackage
        # of bar, bar-extras.
        # Defaults to an empty list.
        #
        # Type: OPTIONAL
        rpms:
            - bar
            - bar-extras
            - bar-devel
            - baz
            - xxx

    # filter:
    # Module component filters
    # Defaults to no filters.
    #
    # Type: OPTIONAL
    filter:
        # rpms:
        # RPM names not to be included in the module.
        # By default, all built binary RPMs are included.  In the example
        # we exclude a subpackage of bar, bar-nonfoo from our module.
        # Defaults to an empty list.
        #
        # Type: OPTIONAL
        rpms:
            - baz-nonfoo

    # demodularized:
    # Artifacts which became non-modular
    # Defaults to no demodularization.
    # Type: OPTIONAL
    demodularized:
        # rpms:
        # A list of binary RPM package names which where removed from
        # a module. This list explains to a package mananger that the packages
        # are not part of the module anymore and up-to-now same-named masked
        # non-modular packages should become available again. This enables
        # moving a package from a module to a set of non-modular packages. The
        # exact implementation of the demodularization (e.g. whether it
        # applies to all modules or only to this stream) is defined by the
        # package manager.
        # Defaults to an empty list.
        #
        # Type: OPTIONAL
        rpms:
            - bar-old

    # components:
    # Functional components of the module
    #
    # Type: OPTIONAL
    components:
        # rpms:
        # RPM content of the module
        # Keys are the VCS/SRPM names, values dictionaries holding
        # additional information.
        #
        # Type: OPTIONAL
        rpms:
            bar:
                # name:
                # The real name of the package, if it differs from the key in
                # this dictionary. Used when bootstrapping to build a
                # bootstrapping ref before building the package for real.
                #
                # Type: OPTIONAL
                name: bar-real

                # rationale:
                # Why is this component present.
                # A simple, free-form string.
                #
                # Type: MANDATORY
                rationale: We need this to demonstrate stuff.

                # repository:
                # Use this repository if it's different from the build
                # system configuration.
                #
                # Type: AUTOMATIC
                repository: https://pagure.io/bar.git

                # cache:
                # Use this lookaside cache if it's different from the
                # build system configuration.
                #
                # Type: AUTOMATIC
                cache: https://example.com/cache

                # ref:
                # Use this specific commit hash, branch name or tag for
                # the build.  If ref is a branch name, the branch HEAD
                # will be used.  If no ref is given, the build system is
                # permitted to make reasonable assumptions about the correct
                # default value. Otherwise, the fall-back is the default branch
                # for the git repository (commonly 'master').
                #
                # Type: AUTOMATIC
                ref: 26ca0c0

                # buildafter:
                # Use the "buildafter" value to specify that this component
                # must be be ordered later than some other entries in this map.
                # The values of this array come from the keys of this map and
                # not the real component name to enable bootstrapping.
                # Use of both buildafter and buildorder in the same document is
                # prohibited, as they will conflict.
                #
                # In this example, 'baz' makes some changes to the default
                # buildroot that 'bar' must use.
                #
                # Note: The use of buildafter is not currently supported by the
                # Fedora module build system.
                #
                # Type: AUTOMATIC
                # buildafter:
                #     - baz

                # buildonly:
                # Use the "buildonly" value to indicate that all artifacts
                # produced by this component are intended only for building
                # this component and should be automatically added to the
                # data.filter.rpms list after the build is complete.
                # Defaults to "false" if not specified.
                #
                # Type: AUTOMATIC
                buildonly: false

            # baz builds RPM macros for the other components to use
            baz:
                rationale: Demonstrate updating the buildroot contents.

                # buildroot:
                # If buildroot is set to True, the packages listed in this
                # module's 'buildroot' profile will be installed into the
                # buildroot of any component built in buildorder/buildafter
                # batches begun after this one, without requiring that those
                # packages are listed among BuildRequires.
                #
                # The primary purpose of this is for building RPMs that change
                # the build environment, such as those that provide new RPM
                # macro definitions that can be used by subsequent builds.
                #
                # Defaults to "false" if not specified.
                #
                # Type: OPTIONAL
                buildroot: true

                # srpm-buildroot:
                # If srpm-buildroot is set to True, the packages listed in this
                # module's 'srpm-buildroot' profile will be installed into the
                # buildroot of any component built in buildorder/buildafter
                # batches begun after this one, without requiring that those
                # packages are listed among BuildRequires.
                #
                # The primary purpose of this is for building RPMs that change
                # the build environment, such as those that provide new RPM
                # macro definitions that can be used by subsequent builds.
                #
                # Defaults to "false" if not specified.
                #
                # Type: OPTIONAL
                srpm-buildroot: true

            xxx:
                rationale: xxx demonstrates arches and multilib.

                # arches:
                # xxx is only available on the listed architectures.
                # Includes specific hardware architectures, not families.
                # See the data.arch field for details.
                # Instructs the build system to only build the
                # component on this specific set of architectures.
                # If data.buildopts.arches is also specified,
                # this must be a subset of those architectures.
                # Defaults to all available arches.
                #
                # Type: AUTOMATIC
                arches: [i686, x86_64]

                # multilib:
                # A list of architectures with multilib
                # installs, i.e. both i686 and x86_64
                # versions will be installed on x86_64.
                # Includes specific hardware architectures, not families.
                # See the data.arch field for details.
                # Defaults to no multilib.
                #
                # Type: AUTOMATIC
                multilib: [x86_64]

                # This package requires a particular version of 'bar' to be
                # present in order to build correctly, so we inform the build
                # system not to build this until 'bar' has completed
                # successfully.
                # buildafter:
                #     - bar

                # buildorder:
                # Build order group
                # When building, components are sorted by build order tag
                # and built in batches grouped by their buildorder value.
                # Built batches are then re-tagged into the buildroot.
                # Multiple components can have the same buildorder index
                # to map them into build groups.
                # Defaults to zero.
                # Integer, negative values are allowed.
                # In this example, bar and baz are built first in no particular
                # order, then tagged into the buildroot, then, finally, xxx is
                # built.
                # Use of both buildafter and buildorder in the same document is
                # prohibited, as they will conflict.
                #
                # Type: OPTIONAL
                buildorder: 10

        # modules:
        # Module content of this module
        # Included modules are built in the shared buildroot, together with
        # other included content.  Keys are module names, values additional
        # component information.  Note this only includes components and their
        # properties from the referenced module and doesn't inherit any
        # additional module metadata such as the module's dependencies or
        # component buildopts.  The included components are built in their
        # defined buildorder as sub-build groups.
        #
        # Type: OPTIONAL
        modules:
            includedmodule:

                # rationale:
                # Why is this module included?
                #
                # Type: MANDATORY
                rationale: Included in the stack, just because.

                # repository:
                # Link to VCS repository that contains the modulemd file
                # if it differs from the buildsystem default configuration.
                #
                # Type: AUTOMATIC
                repository: https://pagure.io/includedmodule.git

                # ref:
                # See the rpms ref.
                #
                # Type: AUTOMATIC
                ref: somecoolbranchname

                # buildorder:
                # See the rpms buildorder.
                #
                # Type: AUTOMATIC
                buildorder: 100