############################################################################## # 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 'main'). # # 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, from an interval [-(2^63), +2^63-1]. # 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