· 5 years ago · Oct 02, 2020, 05:48 PM
1##############################################################################
2# Glossary: #
3# #
4# build system: The process by which a module is built and packaged. In many #
5# cases, this will be the Module Build Service tool, but this term is used #
6# as a catch-all to describe any mechanism for producing a yum repository #
7# containing modular content from input module metadata files. #
8# #
9# #
10# == Attribute Types == #
11# #
12# MANDATORY: Attributes of this type must be filled in by the packager of #
13# this module. They must also be preserved and provided in the output #
14# metadata produced by the build system for inclusion into a repository. #
15# #
16# OPTIONAL: Attributes of this type may be provided by the packager of this #
17# module, when appropriate. If they are provided, they must also be #
18# preserved and provided in the output metadata produced by the build #
19# system for inclusion into a repository. #
20# #
21# AUTOMATIC: Attributes of this type must be present in the repository #
22# metadata, but they may be left unspecified by the packager. In this case, #
23# the build system is responsible for generating an appropriate value for #
24# the attribute and including it in the repository metadata. If the packager #
25# specifies this attribute explicitly, it must be preserved and provided in #
26# the output metadata for inclusion into a repository. #
27# #
28# The definitions above describe the expected behavior of the build system #
29# operating in its default configuration. It is permissible for the build #
30# system to override user-provided entries through non-default operating #
31# modes. If such changes are made, all items indicated as being required for #
32# the output repository must still be present. #
33##############################################################################
34
35
36# Document type identifier
37# `document: modulemd-packager` describes the contents of a packager's input
38# for a module stream.
39document: modulemd-packager
40
41# Module metadata format version
42version: 3
43
44data:
45
46 # summary:
47 # A short summary describing the module
48 #
49 # Type: MANDATORY
50 #
51 # Mandatory for module metadata in a yum/dnf repository.
52 summary: An example module
53
54 # description:
55 # A verbose description of the module
56 #
57 # Type: MANDATORY
58 #
59 # Mandatory for module metadata in a yum/dnf repository.
60 description: >-
61 A module for the demonstration of the metadata format. Also,
62 the obligatory lorem ipsum dolor sit amet goes right here.
63
64 # license:
65 # Module and content licenses in the Fedora license identifier
66 # format
67 #
68 # Type: MANDATORY
69 license:
70 # module:
71 # Module license
72 # This list covers licenses used for the module metadata and
73 # possibly other files involved in the creation of this specific
74 # module.
75 #
76 # Type: MANDATORY
77 module:
78 - MIT
79
80 # configurations:
81 # A list of build and dependency configurations
82 #
83 # Each entry in the list represents a build of this module stream against
84 # one platform (usually a distribution release name/number) and optionally
85 # a set of dependencies.
86 #
87 # Type: MANDATORY
88 configurations:
89 # context:
90 # A string of up to ten [a-zA-Z0-9] characters representing a
91 # a build and runtime configuration for this stream. This string is
92 # arbitrary but must be unique in this module stream.
93 # Type: MANDATORY
94 - context: CTX1
95 # platform:
96 # Defines the distribution and release to build on and run against.
97 # Type: MANDATORY
98 platform: f32
99 # buildrequires:
100 # A dictionary of the build-time dependencies on other module streams
101 # Each configuration may depend on a single stream of a dependency.
102 #
103 # Type: Optional
104 buildrequires:
105 appframework: v1
106 # requires:
107 # A dictionary of the run-time dependencies on other module streams
108 # Each configuration may depend on a single stream of a dependency.
109 #
110 # Type: Optional
111 requires:
112 appframework: v1
113
114 # Alternate example with no dependencies
115 - context: CTX2
116 platform: f33
117
118 # references:
119 # References to external resources, typically upstream
120 #
121 # Type: OPTIONAL
122 references:
123 # community:
124 # Upstream community website, if it exists
125 #
126 # Type: OPTIONAL
127 community: http://www.example.com/
128
129 # documentation:
130 # Upstream documentation, if it exists
131 #
132 # Type: OPTIONAL
133 documentation: http://www.example.com/
134
135 # tracker:
136 # Upstream bug tracker, if it exists
137 #
138 # Type: OPTIONAL
139 tracker: http://www.example.com/
140
141 # profiles:
142 # Profiles define the end user's use cases for the module. They consist of
143 # package lists of components to be installed by default if the module is
144 # enabled. The keys are the profile names and contain package lists by
145 # component type. There are several profiles defined below. Suggested
146 # behavior for package managers is to just enable repository for selected
147 # module. Then users are able to install packages on their own. If they
148 # select a specific profile, the package manager should install all
149 # packages of that profile.
150 # Defaults to no profile definitions.
151 #
152 # Type: OPTIONAL
153 profiles:
154
155 # An example profile that defines a set of packages which are meant to
156 # be installed inside a container image artifact.
157 #
158 # Type: OPTIONAL
159 container:
160 rpms:
161 - bar
162 - bar-devel
163
164 # An example profile that delivers a minimal set of packages to
165 # provide this module's basic functionality. This is meant to be used
166 # on target systems where size of the distribution is a real concern.
167 #
168 # Type: Optional
169 minimal:
170 # A verbose description of the module, optional
171 description: Minimal profile installing only the bar package.
172 rpms:
173 - bar
174
175 # buildroot:
176 # This is a special reserved profile name.
177 #
178 # This provides a listing of packages that will be automatically
179 # installed into the buildroot of all component builds that are started
180 # after a component builds with its `buildroot: True` option set.
181 #
182 # The primary purpose of this is for building RPMs that change
183 # the build environment, such as those that provide new RPM
184 # macro definitions that can be used by subsequent builds.
185 #
186 # Specifically, it is used to flesh out the build group in koji.
187 #
188 # Type: OPTIONAL
189 buildroot:
190 rpms:
191 - bar-devel
192
193 # srpm-buildroot:
194 # This is a special reserved profile name.
195 #
196 # This provides a listing of packages that will be automatically
197 # installed into the buildroot of all component builds that are started
198 # after a component builds with its `srpm-buildroot: True` option set.
199 #
200 # The primary purpose of this is for building RPMs that change
201 # the build environment, such as those that provide new RPM
202 # macro definitions that can be used by subsequent builds.
203 #
204 # Very similar to the buildroot profile above, this is used by the
205 # build system to specify any additional packages which should be
206 # installed during the buildSRPMfromSCM step in koji.
207 #
208 # Type: OPTIONAL
209 srpm-buildroot:
210 rpms:
211 - bar-extras
212
213 # api:
214 # Module API
215 # Defaults to no API.
216 #
217 # Type: OPTIONAL
218 api:
219 # rpms:
220 # The module's public RPM-level API.
221 # A list of binary RPM names that are considered to be the
222 # main and stable feature of the module; binary RPMs not listed
223 # here are considered "unsupported" or "implementation details".
224 # In the example here we don't list the xyz package as it's only
225 # included as a dependency of xxx. However, we list a subpackage
226 # of bar, bar-extras.
227 # Defaults to an empty list.
228 #
229 # Type: OPTIONAL
230 rpms:
231 - bar
232 - bar-extras
233 - bar-devel
234 - baz
235 - xxx
236
237 # filter:
238 # Module component filters
239 # Defaults to no filters.
240 #
241 # Type: OPTIONAL
242 filter:
243 # rpms:
244 # RPM names not to be included in the module.
245 # By default, all built binary RPMs are included. In the example
246 # we exclude a subpackage of bar, bar-nonfoo from our module.
247 # Defaults to an empty list.
248 #
249 # Type: OPTIONAL
250 rpms:
251 - baz-nonfoo
252
253 # components:
254 # Functional components of the module
255 #
256 # Type: OPTIONAL
257 components:
258 # rpms:
259 # RPM content of the module
260 # Keys are the VCS/SRPM names, values dictionaries holding
261 # additional information.
262 #
263 # Type: OPTIONAL
264 rpms:
265 bar:
266 # name:
267 # The real name of the package, if it differs from the key in
268 # this dictionary. Used when bootstrapping to build a
269 # bootstrapping ref before building the package for real.
270 #
271 # Type: OPTIONAL
272 name: bar-real
273
274 # rationale:
275 # Why is this component present.
276 # A simple, free-form string.
277 #
278 # Type: MANDATORY
279 rationale: We need this to demonstrate stuff.
280
281 # repository:
282 # Use this repository if it's different from the build
283 # system configuration.
284 #
285 # Type: AUTOMATIC
286 repository: https://pagure.io/bar.git
287
288 # cache:
289 # Use this lookaside cache if it's different from the
290 # build system configuration.
291 #
292 # Type: AUTOMATIC
293 cache: https://example.com/cache
294
295 # ref:
296 # Use this specific commit hash, branch name or tag for
297 # the build. If ref is a branch name, the branch HEAD
298 # will be used. If no ref is given, the master branch
299 # is assumed.
300 #
301 # Type: AUTOMATIC
302 ref: 26ca0c0
303
304 # buildafter:
305 # Use the "buildafter" value to specify that this component
306 # must be be ordered later than some other entries in this map.
307 # The values of this array come from the keys of this map and
308 # not the real component name to enable bootstrapping.
309 #
310 # In this example, 'baz' makes some changes to the default
311 # buildroot that 'bar' must use.
312 #
313 # Type: AUTOMATIC
314 buildafter:
315 - baz
316
317 # buildonly:
318 # Use the "buildonly" value to indicate that all artifacts
319 # produced by this component are intended only for building
320 # this component and should be automatically added to the
321 # data.filter.rpms list after the build is complete.
322 # Defaults to "false" if not specified.
323 #
324 # Type: AUTOMATIC
325 buildonly: false
326
327 # baz builds RPM macros for the other components to use
328 baz:
329 rationale: Demonstrate updating the buildroot contents.
330
331 # buildroot:
332 # If buildroot is set to True, the packages listed in this
333 # module's 'buildroot' profile will be installed into the
334 # buildroot of any component built in buildorder/buildafter
335 # batches begun after this one, without requiring that those
336 # packages are listed among BuildRequires.
337 #
338 # The primary purpose of this is for building RPMs that change
339 # the build environment, such as those that provide new RPM
340 # macro definitions that can be used by subsequent builds.
341 #
342 # Defaults to "false" if not specified.
343 #
344 # Type: OPTIONAL
345 buildroot: true
346
347 # srpm-buildroot:
348 # If srpm-buildroot is set to True, the packages listed in this
349 # module's 'srpm-buildroot' profile will be installed into the
350 # buildroot of any component built in buildorder/buildafter
351 # batches begun after this one, without requiring that those
352 # packages are listed among BuildRequires.
353 #
354 # The primary purpose of this is for building RPMs that change
355 # the build environment, such as those that provide new RPM
356 # macro definitions that can be used by subsequent builds.
357 #
358 # Defaults to "false" if not specified.
359 #
360 # Type: OPTIONAL
361 srpm-buildroot: true
362
363 xxx:
364 rationale: xxx demonstrates arches and multilib.
365
366 # arches:
367 # xxx is only available on the listed architectures.
368 # Includes specific hardware architectures, not families.
369 # See the data.arch field for details.
370 # Instructs the build system to only build the
371 # component on this specific set of architectures.
372 # If data.buildopts.arches is also specified,
373 # this must be a subset of those architectures.
374 # Defaults to all available arches.
375 #
376 # Type: AUTOMATIC
377 arches: [i686, x86_64]
378
379 # multilib:
380 # A list of architectures with multilib
381 # installs, i.e. both i686 and x86_64
382 # versions will be installed on x86_64.
383 # Includes specific hardware architectures, not families.
384 # See the data.arch field for details.
385 # Defaults to no multilib.
386 #
387 # Type: AUTOMATIC
388 multilib: [x86_64]
389
390 # This package requires a particular version of 'bar' to be
391 # present in order to build correctly, so we inform the build
392 # system not to build this until 'bar' has completed
393 # successfully.
394 buildafter:
395 - bar
396
397 # modules:
398 # Module content of this module
399 # Included modules are built in the shared buildroot, together with
400 # other included content. Keys are module names, values additional
401 # component information. Note this only includes components and their
402 # properties from the referenced module and doesn't inherit any
403 # additional module metadata such as the module's dependencies or
404 # component buildopts. The included components are built in their
405 # defined buildorder as sub-build groups.
406 #
407 # Type: OPTIONAL
408 modules:
409 includedmodule:
410
411 # rationale:
412 # Why is this module included?
413 #
414 # Type: MANDATORY
415 rationale: Included in the stack, just because.
416
417 # repository:
418 # Link to VCS repository that contains the modulemd file
419 # if it differs from the buildsystem default configuration.
420 #
421 # Type: AUTOMATIC
422 repository: https://pagure.io/includedmodule.git
423
424 # ref:
425 # See the rpms ref.
426 #
427 # Type: AUTOMATIC
428 ref: somecoolbranchname