|
|
| (21 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| {{DISPLAYTITLE:Fedora Packaging Guidelines for Modules}}
| | #REDIRECT [[Module:Guidelines]] |
| <div style="float: right;" class="toclimit-2">__TOC__</div>
| |
| | |
| == Disclaimer ==
| |
| | |
| Note this document is just a draft. These aren't any official, approved Fedora guidelines. Neither the modulemd format we're working with here is finalized.
| |
| | |
| == Overview ==
| |
| | |
| The goal of this document is to describe how to create valid module files, document purposes of all the data fields in them, hint best practices and demonstrate some examples.
| |
| | |
| Each module is defined by a single YAML file and comprises of a number of key-value pairs describing the module's properties and components it contains. Not everything needs to (or even should) be filled in by the module packager; some of the fields get populated later during the module build or distribution phase. The module file format is commonly known as ''modulemd''.
| |
| | |
| The original format specification can be found in the [https://pagure.io/modulemd modulemd repository].
| |
| | |
| == Required fields ==
| |
| | |
| === Document header and the data section ===
| |
| | |
| Every modulemd file '''MUST''' contain a modulemd document header which consists of the document type tag and the document format version, and a data section holding the module data.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| (...)
| |
| | |
| The version is an integer and is not currently used for anything; this will change later in the modulemd development phase.
| |
| | |
| === Module name ===
| |
| | |
| Every module '''MUST''' define its name. The format isn't strictly defined yet but will most likely follow the format of SRPM names.
| |
| | |
| name: example
| |
| | |
| === Module version and release ===
| |
| | |
| Every module '''MUST''' also specify its version and release. The format isn't strictly defined yet but will most likely follow RPM versioning conventions. See [[Packaging:NamingGuidelines#Package_Versioning]] for details.
| |
| | |
| version: 1.23
| |
| release: 1
| |
| | |
| The version field '''SHOULD''' be the same as the main module component version, where applicable. For example a ''webserver'' module that contains the ''httpd-2.4.18'' webserver as its key component should use 2.4.18 for its version. If this cannot be done, the module maintainer may choose their own versioning scheme.
| |
| | |
| The release field is incremented when the module is updated in a way that doesn't warrant a version field bump or the module needs to be rebuilt. (Note: The fedora dist tag should not be included in the release field.)
| |
| | |
| === Module summary and description ===
| |
| | |
| Every module '''MUST''' include human-readable short summary and description. Both should be written in US English.
| |
| | |
| summary: An example module
| |
| description: >
| |
| An example long description of an example module, written just
| |
| to demonstrate the purpose of this field.
| |
| | |
| The summary is a one sentence concise description of the module and '''SHOULD NOT''' end in a period.
| |
| | |
| The description expands on this and '''SHOULD''' end in a period. Description '''SHOULD NOT''' contain installation instructions or configuration manuals.
| |
| | |
| === Module licensing ===
| |
| | |
| Every module '''MUST''' contain a license section and declare a list of the module's licenses. Note these aren't the module's components' licenses.
| |
| | |
| license:
| |
| module:
| |
| - MIT
| |
| | |
| Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. Therefore MIT might be a reasonable default for most module authors as well.
| |
| | |
| See [[Fedora_Packaging_Guidelines_for_Modules#Module_content_licensing]] to see how to declare components' licenses.
| |
| | |
| == Optional fields ==
| |
| | |
| === Module content licensing ===
| |
| | |
| If the module includes some RPM or non-RPM content, the packager '''MAY''' also define a list of content licenses.
| |
| | |
| license:
| |
| module:
| |
| - MIT
| |
| content:
| |
| - GPL+
| |
| - BSD
| |
| | |
| Not every module includes packages and therefore doesn't necessarily have to include this field.
| |
| | |
| Furthermore, the content licenses list should ideally be automatically filled by module build tools rather than the module author.
| |
| | |
| === Module dependencies ===
| |
| | |
| Modules '''MAY''' depend on other modules. These module relationships are listed in the depepdencies section.
| |
| | |
| '''Note:''' This section may change significantly in the future.
| |
| | |
| dependencies:
| |
| buildrequires:
| |
| example-build-dependency: 1.23-1
| |
| requires:
| |
| example-runtime-dependency: 45-1
| |
| | |
| So far modulemd supports two kinds of dependencies:
| |
| | |
| * <code>buildrequires</code> for listing build dependencies of the module, i.e. modules that define the buildroot for building the module's components
| |
| * <code>requires</code> for listing runtime dependencies of the module, i.e. modules that need to be available on the target system for this module to work properly
| |
| | |
| Both these sections contain key-value pairs where keys are the required module names and values the minimum required version in the ''version-release'' format.
| |
| | |
| Either or both of these sections may be omitted.
| |
| | |
| === Extensible module metadata block ===
| |
| | |
| Modules '''MAY''' also contain an extensible metadata block, a list of vendor-defined key-value pairs.
| |
| | |
| xmd:
| |
| user-defined-key: 42
| |
| another-user-defined-key:
| |
| - the first value of the list
| |
| - the second value of the list
| |
| | |
| === Module references ===
| |
| | |
| Modules '''MAY''' define links referencing various upstream resources, such as community website, project documentation or upstream bug tracker.
| |
| | |
| references:
| |
| community: http://www.example.com/
| |
| documentation: http://www.example.com/docs/1.23/
| |
| tracker: http://www.example.com/bugs/
| |
| | |
| === Module components ===
| |
| | |
| Modules '''MAY''', and most modules do contain a components section defining the module's content.
| |
| | |
| components:
| |
| (...)
| |
| | |
| ==== RPM content ====
| |
| | |
| Module RPM content is defined in the <code>rpms</code> subsection of <code>components</code> and typically consists of one or more <code>packages</code> described by their SRPM names and additional extra key-value pairs, some required and some optional, associated with them.
| |
| | |
| Besides <code>packages</code> the <code>rpms</code> section '''MAY''' also define the following keys:
| |
| | |
| * the <code>dependencies</code> switch which controls whether RPM-level dependencies should be automatically included, or ''bundled'', in the module if none of the modules required at runtime would provide these dependencies; this defaults to <code>False</code> and the value cannot be overridden for production module builds in Fedora.
| |
| * the <code>api</code> list of RPM binary package names that are considered the ''stable module API'', i.e. supported RPM components of this module that shouldn't break or disappear without a notice; binary RPM packages not listed here are considered ''internal details'' and other modules '''SHOULD NOT''' depend on them or even expect them to be shipped. Modules with RPM content '''SHOULD''' define some RPM module API.
| |
| | |
| components:
| |
| rpms:
| |
| dependencies: False
| |
| api:
| |
| - foo
| |
| - foo-devel
| |
| packages:
| |
| foo:
| |
| rationale: The key component of this module
| |
| commit: abcdef1
| |
| repository: git://git.example.com/foo.git
| |
| cache: http://www.example.com/lookasidecache/
| |
| arches:
| |
| - i686
| |
| - x86_64
| |
| multilib:
| |
| - x86_64
| |
| | |
| The following key-value pairs extend the SRPM name:
| |
| | |
| * <code>rationale</code> - every component '''MUST''' declare why it was added to the module; this is currently a free form string and might change in the future.
| |
| * <code>commit</code> - the git hash or other commit ID in the <code>repository</code> that should be built and included in this module; recommended. If not defined, the current HEAD or equivalent is used and the hash or other commit ID is recorded in the module by module build tools. So, for example, if we're looking at the <code>commit</code> for the Fedora httpd package, the git hash should come from the official Fedora httpd package repo.
| |
| * <code>repository</code> - specifies git or other VCS repository to use as the component's source; in Fedora, dist-git is used and this option cannot be overridden.
| |
| * <code>cache</code> - points to RPM lookaside cache; in Fedora this option cannot be overriden.
| |
| * <code>arches</code> - a list of architectures this component should be built for; defaults to all available architectures.
| |
| * <code>multilib</code> - a list of architectures where this component should be available as multilib, e.g. if <code>x86_64</code> is listed, x86_64 repositories will also include i686 builds. Defaults to no multilib.
| |
| | |
| ==== Non-RPM content ====
| |
| | |
| Non-RPM content isn't currently supported.
| |
| | |
| == Examples ==
| |
| | |
| === Minimal module ===
| |
| | |
| A minimal module ''example-1.23-1'', containing no packages, having no dependencies whatsoever and defining only the minimal set of required metadata.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| name: example
| |
| version: 1.23
| |
| release: 1
| |
| summary: An example summary
| |
| description: >
| |
| An example description.
| |
| license:
| |
| module:
| |
| - MIT
| |
| | |
| === Minimal module with RPM content ===
| |
| | |
| A minimal module, ''example-1.23-1'', containing one RPM package with SRPM name ''foo''. This module doesn't define any dependencies or optional metadata.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| name: example
| |
| version: 1.23
| |
| release: 1
| |
| summary: An example summary
| |
| description: >
| |
| An example description.
| |
| license:
| |
| module:
| |
| - MIT
| |
| components:
| |
| rpms:
| |
| packages:
| |
| foo:
| |
| rationale: An example RPM component
| |
| | |
| === Minimal module with dependencies only (stack) ===
| |
| | |
| A minimal module, ''example-stack-1.23-1'', containing no packages or any optional metadata besides dependencies. Modules of this type are referred to as ''stacks''.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| name: example-stack
| |
| version: 1.23
| |
| release: 1
| |
| summary: An example summary
| |
| description: >
| |
| An example description.
| |
| license:
| |
| module:
| |
| - MIT
| |
| dependencies:
| |
| requires:
| |
| another-module: 0
| |
| one-more: 22
| |
| | |
| === Common Fedora module ===
| |
| | |
| A typical Fedora module defines all the mandatory metadata plus some useful references, has build and runtime dependencies and contains one or more packages built from specific commits in dist-git. It relies on Fedora build tools to extract licensing information from the included component and populate the <code>data→license→content</code> list.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| name: common-module
| |
| version: 5.67
| |
| release: 8
| |
| summary: An example of a common Fedora module
| |
| description: This module demonstrates what most Fedora modules look like.
| |
| license:
| |
| module: [ MIT ]
| |
| dependencies:
| |
| buildrequires:
| |
| base-runtime: 25
| |
| common-build-tools: 0
| |
| requires:
| |
| base-runtime: 25
| |
| references:
| |
| community: http://www.example.com/common-package
| |
| documentation: http://www.example.com/common-package/docs/5.67/
| |
| components:
| |
| rpms:
| |
| api:
| |
| - common-package
| |
| - common-package-devel
| |
| - common-plugins
| |
| packages:
| |
| common-package:
| |
| rationale: The key component of this module
| |
| commit: fd245a0
| |
| common-plugins:
| |
| rationale: Extensions for common-package
| |
| commit: ff09556
| |
| | |
| === Complete module definition ===
| |
| | |
| See [https://pagure.io/modulemd/blob/master/f/spec.yaml the modulemd specification].
| |
| | |
| [[Category:Modularity]]
| |
| [[Category:Modularization]]
| |
