From 136790d01707decaf0e6aee812f738951975549b Mon Sep 17 00:00:00 2001 From: Stephen Gallagher Date: Tue, 11 Feb 2020 08:52:39 -0500 Subject: [PATCH] Clarify v2 stream specification Signed-off-by: Stephen Gallagher --- yaml_specs/modulemd_packager_v2.yaml | 35 +++++++++- yaml_specs/modulemd_stream_v2.yaml | 96 +++++++++++++++++++++++----- 2 files changed, 114 insertions(+), 17 deletions(-) diff --git a/yaml_specs/modulemd_packager_v2.yaml b/yaml_specs/modulemd_packager_v2.yaml index 026c83654..402e4e5f5 100644 --- a/yaml_specs/modulemd_packager_v2.yaml +++ b/yaml_specs/modulemd_packager_v2.yaml @@ -3,15 +3,18 @@ # for a module stream. It is always a proper subset of a `document: modulemd` # of the same `version`. document: modulemd-packager + # Module metadata format version version: 2 data: # A short summary describing the module, required summary: An example module + # A verbose description of the module, required description: >- A module for the demonstration of the metadata format. Also, the obligatory lorem ipsum dolor sit amet goes right here. + # Module and content licenses in the Fedora license identifier # format, required license: @@ -36,8 +39,6 @@ data: # 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. - # TODO: Provides, conflicts, obsoletes, recommends, etc. - # Do we even need those? # The example below illustrates how to build the same module in four # different ways, with varying build time and runtime dependencies. dependencies: @@ -48,6 +49,7 @@ data: 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 @@ -59,6 +61,7 @@ data: 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: @@ -66,6 +69,7 @@ data: 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 * . @@ -79,14 +83,18 @@ data: platform: [epel7] extras: [] moreextras: [foo, bar] + # References to external resources, typically upstream, optional references: # Upstream community website, if it exists, optional community: http://www.example.com/ + # Upstream documentation, if it exists, optional documentation: http://www.example.com/ + # Upstream bug tracker, if it exists, optional tracker: http://www.example.com/ + # 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 @@ -104,6 +112,7 @@ data: - bar - bar-extras - baz + # Defines a set of packages which are meant to be installed inside # container image artifact. # Optional. @@ -111,6 +120,7 @@ data: rpms: - bar - bar-devel + # This profile provides minimal set of packages providing functionality # of this module. This is meant to be used on target systems where size # of the distribution is a real concern. @@ -120,6 +130,7 @@ data: description: Minimal profile installing only the bar package. rpms: - bar + # A set of packages which should be installed into the buildroot of a # module which depends on this module. Specifically, it is used to # flesh out the build group in koji. @@ -127,6 +138,7 @@ data: buildroot: rpms: - bar-devel + # 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. @@ -134,6 +146,7 @@ data: srpm-buildroot: rpms: - bar-extras + # Module API # Optional, defaults to no API. api: @@ -151,6 +164,7 @@ data: - bar-devel - baz - xxx + # Module component filters # Optional, defaults to no filters. filter: @@ -160,6 +174,7 @@ data: # Optional, defaults to an empty list. rpms: - baz-nonfoo + # Functional components of the module, optional components: # RPM content of the module, optional @@ -172,30 +187,36 @@ data: # bootstrapping ref before building the package for real. # Optional name: bar-real + # Why is this component present. # A simple, free-form string. # Required. rationale: We need this to demonstrate stuff. + # Use this repository if it's different from the build # system configuration. # Optional. repository: https://pagure.io/bar.git + # Use this lookaside cache if it's different from the # build system configuration. # Optional. cache: https://example.com/cache + # 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. # Optional. ref: 26ca0c0 + # 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. buildafter: - baz + # 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 subsequent @@ -203,22 +224,27 @@ data: # explicitly include these packages in its BuildRequires. # Optional. Defaults to "false" if not specified. buildroot: false + # If srpm-buildroot is set to True, the packages listed in this # module's srpm-buildroot profile will be installed into the # buildroot when performing the buildSRPMfromSCM step in # subsequent buildafter batches. # Optional. Defaults to "false" if not specified. srpm-buildroot: false + # baz has no extra options baz: rationale: This one is here to demonstrate other stuff. + xxx: rationale: xxx demonstrates arches and multilib. + # xxx is only available on the listed architectures. # Includes specific hardware architectures, not families. # See the data.arch field for details. # Optional, defaults to all available arches. arches: [i686, x86_64] + # A list of architectures with multilib # installs, i.e. both i686 and x86_64 # versions will be installed on x86_64. @@ -226,14 +252,17 @@ data: # See the data.arch field for details. # Optional, defaults to no multilib. multilib: [x86_64] + # This package requires a particular version of 'xyz' to be # present in order to build correctly, so we inform the build # system not to build this until 'xyz' has completed # successfully. buildafter: - xyz + xyz: rationale: xyz is a bundled dependency of xxx. + # Module content of this module # Included modules are built in the shared buildroot, together with # other included content. Keys are module names, values additional @@ -247,9 +276,11 @@ data: # Why is this module included? # Required rationale: Included in the stack, just because. + # Link to VCS repository that contains the modulemd file # if it differs from the buildsystem default configuration. # Optional. repository: https://pagure.io/includedmodule.git + # See the rpms ref. ref: somecoolbranchname diff --git a/yaml_specs/modulemd_stream_v2.yaml b/yaml_specs/modulemd_stream_v2.yaml index 93c1f1355..057643b57 100644 --- a/yaml_specs/modulemd_stream_v2.yaml +++ b/yaml_specs/modulemd_stream_v2.yaml @@ -4,40 +4,66 @@ document: modulemd # Module metadata format version version: 2 data: - # Module name, optional - # Typically filled in by the buildsystem, using the VCS repository - # name as the name of the module. + # Module name + # Filled in by the build system, using the VCS repository name as the name + # of the module. + # + # When included as input to the build system, the behavior is unspecified. + # + # Mandatory for module metadata in a yum/dnf repository. name: foo - # Module update stream, optional - # Typically filled in by the buildsystem, using the VCS branch name - # as the name of the stream. + + # Module update stream + # Filled in by the buildsystem, using the VCS branch name as the name of + # the stream. + # + # When included as input to the build system, the behavior is unspecified. + # + # Mandatory for module metadata in a yum/dnf repository. stream: latest - # Module version, integer, optional, cannot be negative - # Typically filled in by the buildsystem, using the VCS commit - # timestamp. Module version defines upgrade path for the particular - # update stream. + + # Module version, integer, cannot be negative + # Filled in by the buildsystem, using the VCS commit timestamp. Module + # version defines upgrade path for the particular update stream. + # + # When included as input to the build system, the behavior is unspecified. + # + # Mandatory for module metadata in a yum/dnf repository. version: 20160927144203 - # Module context flag, optional + + # Module context flag # The context flag serves to distinguish module builds with the # same name, stream and version and plays an important role in # future automatic module stream name expansion. # Filled in by the buildsystem. A short hash of the module's name, - # stream, version and its expanded runtime dependencies. + # stream, version and its expanded runtime dependencies. The exact + # mechanism of generating the has is unspecified except that it must be + # stable. + # When included as input to the build system, the behavior is unspecified. + # Mandatory for module metadata in a yum/dnf repository. context: c0ffee43 - # Module artifact architecture, optional + + # 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. + # + # When included as input to the build system, the behavior is unspecified. + # + # Mandatory for module metadata in a yum/dnf repository. arch: x86_64 + # A short summary describing the module, required summary: An example module + # A verbose description of the module, required description: >- A module for the demonstration of the metadata format. Also, the obligatory lorem ipsum dolor sit amet goes right here. + # Service levels, optional # This is a dictionary of important dates (and possibly supplementary data # in the future) that describes the end point of certain functionality, @@ -55,6 +81,7 @@ data: eol: 2077-10-23 security_fixes: eol: 2077-10-23 + # Module and content licenses in the Fedora license identifier # format, required license: @@ -64,18 +91,26 @@ data: # module. module: - MIT + # Content license, optional # A list of licenses used by the packages in the module. # This should be populated by build tools, not the module author. + # + # When included as input to the build system, the behavior is + # unspecified. + # + # Mandatory for module metadata in a yum/dnf repository. content: - Beerware - GPLv2+ - zlib + # Extensible metadata block # A dictionary of user-defined keys and values. # Optional. Defaults to an empty dictionary. xmd: some_key: some_data + # Module dependencies, if any. Optional. # A list of dictionaries describing build and runtime dependencies # of this module. Each list item describes a combination of dependencies @@ -91,8 +126,6 @@ data: # 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. - # TODO: Provides, conflicts, obsoletes, recommends, etc. - # Do we even need those? # The example below illustrates how to build the same module in four # different ways, with varying build time and runtime dependencies. dependencies: @@ -103,6 +136,7 @@ data: 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 @@ -114,6 +148,7 @@ data: 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: @@ -121,6 +156,7 @@ data: 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 * . @@ -134,14 +170,18 @@ data: platform: [epel7] extras: [] moreextras: [foo, bar] + # References to external resources, typically upstream, optional references: # Upstream community website, if it exists, optional community: http://www.example.com/ + # Upstream documentation, if it exists, optional documentation: http://www.example.com/ + # Upstream bug tracker, if it exists, optional tracker: http://www.example.com/ + # 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 @@ -159,6 +199,7 @@ data: - bar - bar-extras - baz + # Defines a set of packages which are meant to be installed inside # container image artifact. # Optional. @@ -166,6 +207,7 @@ data: rpms: - bar - bar-devel + # This profile provides minimal set of packages providing functionality # of this module. This is meant to be used on target systems where size # of the distribution is a real concern. @@ -175,6 +217,7 @@ data: description: Minimal profile installing only the bar package. rpms: - bar + # A set of packages which should be installed into the buildroot of a # module which depends on this module. Specifically, it is used to # flesh out the build group in koji. @@ -182,6 +225,7 @@ data: buildroot: rpms: - bar-devel + # 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. @@ -189,6 +233,7 @@ data: srpm-buildroot: rpms: - bar-extras + # Module API # Optional, defaults to no API. api: @@ -206,6 +251,7 @@ data: - bar-devel - baz - xxx + # Module component filters # Optional, defaults to no filters. filter: @@ -215,6 +261,7 @@ data: # Optional, defaults to an empty list. rpms: - baz-nonfoo + # Component build options # Additional per component type module-wide build options. # Optional @@ -242,12 +289,14 @@ data: - fooscl-1-baz - xxx - xyz + # 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. # Optional, defaults to all available arches. arches: [i686, x86_64] + # Functional components of the module, optional components: # RPM content of the module, optional @@ -260,24 +309,29 @@ data: # bootstrapping ref before building the package for real. # Optional name: bar-real + # Why is this component present. # A simple, free-form string. # Required. rationale: We need this to demonstrate stuff. + # Use this repository if it's different from the build # system configuration. # Optional. repository: https://pagure.io/bar.git + # Use this lookaside cache if it's different from the # build system configuration. # Optional. cache: https://example.com/cache + # 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. # Optional. ref: 26ca0c0 + # 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 @@ -286,12 +340,14 @@ data: # prohibited, as they will conflict. # buildafter: # - baz + # 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. # Optional. Defaults to "false" if not specified. buildonly: false + # 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 subsequent @@ -299,15 +355,18 @@ data: # explicitly include these packages in its BuildRequires. # Optional. Defaults to "false" if not specified. buildroot: false + # If srpm-buildroot is set to True, the packages listed in this # module's srpm-buildroot profile will be installed into the # buildroot when performing the buildSRPMfromSCM step in # subsequent buildorder/buildafter batches. # Optional. Defaults to "false" if not specified. srpm-buildroot: false + # baz has no extra options baz: rationale: This one is here to demonstrate other stuff. + xxx: rationale: xxx demonstrates arches and multilib. # xxx is only available on the listed architectures. @@ -319,6 +378,7 @@ data: # this must be a subset of those architectures. # Optional, defaults to all available arches. arches: [i686, x86_64] + # A list of architectures with multilib # installs, i.e. both i686 and x86_64 # versions will be installed on x86_64. @@ -326,6 +386,7 @@ data: # See the data.arch field for details. # Optional, defaults to no multilib. multilib: [x86_64] + xyz: rationale: xyz is a bundled dependency of xxx. # Build order group @@ -342,6 +403,7 @@ data: # Use of both buildafter and buildorder in the same document is # prohibited, as they will conflict. buildorder: 10 + # Module content of this module # Included modules are built in the shared buildroot, together with # other included content. Keys are module names, values additional @@ -356,13 +418,16 @@ data: # Why is this module included? # Required rationale: Included in the stack, just because. + # Link to VCS repository that contains the modulemd file # if it differs from the buildsystem default configuration. # Optional. repository: https://pagure.io/includedmodule.git + # See the rpms ref. ref: somecoolbranchname # See the rpms buildorder. + buildorder: 100 # Artifacts shipped with this module # This section lists binary artifacts shipped with the module, allowing @@ -381,6 +446,7 @@ data: - xxx-0:1-1.module_deadbeef.x86_64 - xxx-0:1-1.module_deadbeef.i686 - xyz-0:1-1.module_deadbeef.x86_64 + # 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.