############################################################################## # 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` describes the contents of a module stream document: modulemd # Module metadata format version version: 2 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" # version: # Module version, 64-bit unsigned integer # If this value is unset (or set to zero), it will be filled in by the # buildsystem, using the VCS commit timestamp. Module version defines the # upgrade path for the particular update stream. # # Type: AUTOMATIC # # Mandatory for module metadata in a yum/dnf repository. version: 20160927144203 # context: # Module context flag # The context flag serves to distinguish module builds with the # same name, stream and version and plays an important role in # automatic module stream name expansion. # # If 'static_context' is unset or equal to FALSE: # Filled in by the buildsystem. A short hash of the module's name, # stream, version and its expanded runtime dependencies. The exact # mechanism for generating the hash is unspecified. # # Type: AUTOMATIC # # Mandatory for module metadata in a yum/dnf repository. # # If 'static_context' is set to True: # The context flag is a string of up to thirteen [a-zA-Z0-9_] characters # representing a build and runtime configuration for this stream. This # string is arbitrary but must be unique in this module stream. # # Type: MANDATORY static_context: false context: c0ffee43 # arch: # Module artifact architecture # Contains a string describing the module's artifacts' main hardware # architecture compatibility, distinguishing the module artifact, # e.g. a repository, from others with the same name, stream, version and # context. This is not a generic hardware family (i.e. basearch). # Examples: i386, i486, armv7hl, x86_64 # Filled in by the buildsystem during the compose stage. # # Type: AUTOMATIC # # Mandatory for module metadata in a yum/dnf repository. arch: x86_64 # 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. # servicelevels: # Service levels # This is a dictionary of important dates (and possibly supplementary data # in the future) that describes the end point of certain functionality, # such as the date when the module will transition to "security fixes only" # or go completely end-of-life. # Filled in by the buildsystem. Service level names might have special # meaning to other systems. Defined externally. # # Type: AUTOMATIC servicelevels: rawhide: # EOL dates are the ISO 8601 format. eol: 2077-10-23 stable_api: eol: 2077-10-23 bug_fixes: eol: 2077-10-23 security_fixes: eol: 2077-10-23 # license: # Module and content licenses in the Fedora license identifier # format # # Type: MANDATORY license: # module: # Module license # This list covers licenses used for the module metadata and # possibly other files involved in the creation of this specific # module. # # Type: MANDATORY module: - MIT # content: # Content license # A list of licenses used by the packages in the module. # This should be populated by build tools, not the module author. # # Type: AUTOMATIC # # Mandatory for module metadata in a yum/dnf repository if the # module contains any artifacts. content: - Apache-2.0 - GPL-1.0-or-later OR Artistic-1.0-Perl # xmd: # Extensible metadata block # A dictionary of user-defined keys and values. # Defaults to an empty dictionary. # # Type: OPTIONAL xmd: some_key: some_data # dependencies: # Module dependencies, if any # A list of dictionaries describing build and runtime dependencies # of this module. Each list item describes a combination of dependencies # this module can be built or run against. # Dependency keys are module names, dependency values are lists of # required streams. The lists can be both inclusive (listing compatible # streams) or exclusive (accepting every stream except for those listed). # An empty list implies all active existing streams are supported. # Requiring multiple streams at build time will result in multiple # builds. Requiring multiple streams at runtime implies the module # is compatible with all of them. If the same module streams are listed # in both the build time and the runtime block, the build tools translate # the runtime block so that it matches the stream the module was built # against. Multiple builds result in multiple output modulemd files. # See below for an example. # The example below illustrates how to build the same module in four # different ways, with varying build time and runtime dependencies. # # Type: OPTIONAL dependencies: # Build on all available platforms except for f27, f28 and epel7 # After build, the runtime dependency will match the one used for # the build. - buildrequires: platform: [-f27, -f28, -epel7] requires: platform: [-f27, -f28, -epel7] # For platform:f27 perform two builds, one with buildtools:v1, another # with buildtools:v2 in the buildroot. Both will also utilize # compatible:v3. At runtime, buildtools isn't required and either # compatible:v3 or compatible:v4 can be installed. - buildrequires: platform: [f27] buildtools: [v1, v2] compatible: [v3] requires: platform: [f27] compatible: [v3, v4] # For platform:f28 builds, require either runtime:a or runtime:b at # runtime. Only one build is performed. - buildrequires: platform: [f28] requires: platform: [f28] runtime: [a, b] # For platform:epel7, build against against all available extras # streams and moreextras:foo and moreextras:bar. The number of builds # in this case will be 2 * . # At runtime, both extras and moreextras will match whatever stream was # used for build. - buildrequires: platform: [epel7] extras: [] moreextras: [foo, bar] requires: platform: [epel7] extras: [] moreextras: [foo, bar] # 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 # 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 # buildopts: # Component build options # Additional per component type module-wide build options. # # 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 for details. # Defaults to all available arches. # # Type: OPTIONAL arches: [i686, x86_64] # 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 master branch # is assumed. # # 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. # # 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 # See component xyz for a complete description of buildorder # # build this component before any others so that the macros it # creates are available to all of them. buildorder: -1 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] xyz: rationale: xyz is a bundled dependency of xxx. # 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, from an interval [-(2^63), +2^63-1]. # In this example, bar, baz and xxx are built first in # no particular order, then tagged into the buildroot, # then, finally, xyz 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 # artifacts: # Artifacts shipped with this module # This section lists binary artifacts shipped with the module, allowing # software management tools to handle module bundles. This section is # populated by the module build system. # # Type: AUTOMATIC artifacts: # rpms: # RPM artifacts shipped with this module # A set of NEVRAs associated with this module. An epoch number in the # NEVRA string is mandatory. # # Type: AUTOMATIC rpms: - bar-0:1.23-1.module_deadbeef.x86_64 - bar-devel-0:1.23-1.module_deadbeef.x86_64 - bar-extras-0:1.23-1.module_deadbeef.x86_64 - baz-0:42-42.module_deadbeef.x86_64 - xxx-0:1-1.module_deadbeef.x86_64 - xxx-0:1-1.module_deadbeef.i686 - xyz-0:1-1.module_deadbeef.x86_64 # rpm-map: # The rpm-map exists to link checksums from repomd to specific # artifacts produced by this module. Any item in this list must match # an entry in the data.artifacts.rpms section. # # Type: AUTOMATIC rpm-map: # The digest-type of this checksum. # # Type: MANDATORY sha256: # The checksum of the artifact being sought. # # Type: MANDATORY ee47083ed80146eb2c84e9a94d0836393912185dcda62b9d93ee0c2ea5dc795b: # name: # The RPM name. # # Type: Mandatory name: bar # epoch: # The RPM epoch. # A 32-bit unsigned integer. # # Type: OPTIONAL epoch: 0 # version: # The RPM version. # # Type: MANDATORY version: 1.23 # release: # The RPM release. # # Type: MANDATORY release: 1.module_deadbeef # arch: # The RPM architecture. # # Type: MANDATORY arch: x86_64 # nevra: # The complete RPM NEVRA. # # Type: MANDATORY nevra: bar-0:1.23-1.module_deadbeef.x86_64