| |
@@ -1,12 +1,80 @@
|
| |
= Defining modules in modulemd
|
| |
|
| |
- Modules are defined using a https://pagure.io/modulemd[modulemd file]. The definition includes the summary and description, list of source RPM packages, build information i.e. buildroot, and usage information i.e. installation profiles or licenses.
|
| |
+ Simply put, a **https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd] is a file that defines what packages get build for what releases**. It includes a summary and a description, a list of source RPM packages, build information i.e. build order and macros, and usage information i.e. installation profiles and licenses.
|
| |
|
| |
- This page will help you with writing a module definition from scratch. Even though this page is meant to be up-to-date, please make sure your module complies with the https://fedoraproject.org/wiki/Module:Guidelines[Fedora Packaging Guidelines for Modules] as it is the authoritative point of truth.
|
| |
+ == A typical modulemd example
|
| |
|
| |
- This page includes the <<Common definitions>>, the <<Advanced definitions>>, examples of <<A minimal modulemd>>, and a <<Bonus: Converting modulemd v1 to v2>>.
|
| |
+ A typical modulemd file looks similar to the following examples. Read on for more details about each part of the modulemd file.
|
| |
|
| |
- == Common definitions
|
| |
+ Feel free to copy/paste this example when creating your new module.
|
| |
+
|
| |
+ [source,yaml]
|
| |
+ ----
|
| |
+ document: modulemd
|
| |
+ version: 2
|
| |
+ data:
|
| |
+ # === Information about this module ==================================
|
| |
+ # (Can be copied from the main RPM package, but doesn't need to be)
|
| |
+ summary: An example module
|
| |
+ description: >-
|
| |
+ A module for the demonstration of the metadata format. Also,
|
| |
+ the obligatory lorem ipsum dolor sit amet goes right here.
|
| |
+
|
| |
+ # === License of this modulemd file ==================================
|
| |
+ # (Package licenses will be added automatically by the build system)
|
| |
+ license:
|
| |
+ module:
|
| |
+ - MIT
|
| |
+
|
| |
+ # === Modular dependencies ===========================================
|
| |
+ # (For which Fedora releases to build?)
|
| |
+ dependencies:
|
| |
+ - buildrequires:
|
| |
+ platform: [] # <- Build for all Fedora releases
|
| |
+ requires:
|
| |
+ platform: [] # <- Run on all Fedora releases
|
| |
+
|
| |
+ # === Module API (optional, but encouraged) ==========================
|
| |
+ # (Which packages are API-stable?)
|
| |
+ api:
|
| |
+ rpms:
|
| |
+ - package-one # <- Binary RPM package name
|
| |
+ - package-one-extras # <- Binary RPM package name
|
| |
+ - package-one-cli # <- Binary RPM package name
|
| |
+ - package-one-devel # <- Binary RPM package name
|
| |
+ - package-two # <- Binary RPM package name
|
| |
+
|
| |
+ # === Installation profiles (optional, but encouraged) ===============
|
| |
+ # (Helping users with installation by providing pre-defined groups)
|
| |
+ profiles:
|
| |
+ default: # <- Name of the profile
|
| |
+ description: A standard installation.
|
| |
+ rpms:
|
| |
+ - package-one # <- Binary RPM package name
|
| |
+ - package-one-extras # <- Binary RPM package name
|
| |
+ - package-two # <- Binary RPM package name
|
| |
+ cli: # <- Name of the profile
|
| |
+ description: A command-line client.
|
| |
+ rpms:
|
| |
+ - package-one-cli # <- Binary RPM package name
|
| |
+
|
| |
+ # === Packages in this module ========================================
|
| |
+ # (Referenced by their dist-git repo name + branch name)
|
| |
+ components:
|
| |
+ rpms:
|
| |
+ first-package: # <- Source RPM package name
|
| |
+ ref: 3.0 # <- Branch name in dist-git
|
| |
+ rationale: Provides the core functionality.
|
| |
+ second-package: # <- Source RPM package name
|
| |
+ ref: latest # <- Branch name in dist-git
|
| |
+ rationale: Web UI for the first-package.
|
| |
+ ----
|
| |
+
|
| |
+ == Common modulemd definitions
|
| |
+
|
| |
+ These are the common parts of a modulemd file, used in the example above. Advanced definitions, including a complex example of Module Stream Expansion (MSE), are towards the end of this page.
|
| |
+
|
| |
+ === Document header
|
| |
|
| |
Every modulemd starts with these three lines:
|
| |
|
| |
@@ -20,9 +88,9 @@
|
| |
|
| |
<1> All the following definitions go here, under _data_.
|
| |
|
| |
- === Information about your module
|
| |
+ === Information about this module
|
| |
|
| |
- Tell users what this module represents by writing a summary and a description, and how can they use it by specifying a license.
|
| |
+ Tell users what this module represents by writing a summary and a description.
|
| |
|
| |
[source,yaml]
|
| |
----
|
| |
@@ -30,42 +98,28 @@
|
| |
description: >- <1>
|
| |
A module for the demonstration of the metadata format. Also,
|
| |
the obligatory lorem ipsum dolor sit amet goes right here.
|
| |
- license:
|
| |
- module:
|
| |
- - MIT <2>
|
| |
----
|
| |
|
| |
<1> The `>-` means new line in YAML. Useful for longer blocks of text, such as the description!
|
| |
|
| |
- <2> A license for this modulemd file. Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise.
|
| |
|
| |
+ === License of this modulemd file
|
| |
|
| |
- === List the packages
|
| |
-
|
| |
- To make your module useful, include some RPM packages in it. List all source RPM packages this module should include.
|
| |
+ This is a license of this very modulemd file and it doesn't need to be modified.
|
| |
+ The buildsystem adds licenses of all packages to this list automatically.
|
| |
|
| |
[source,yaml]
|
| |
----
|
| |
- components:
|
| |
- rpms:
|
| |
- first-package: <1>
|
| |
- rationale: Provides the core functionality. <2>
|
| |
- ref: 3.0 <3>
|
| |
- second-package:
|
| |
- rationale: Web UI for the first-package.
|
| |
- ref: stable
|
| |
- ... <4>
|
| |
+ license:
|
| |
+ module:
|
| |
+ - MIT <1>
|
| |
----
|
| |
|
| |
- <1> Name of the package — maps to a DistGit repository name.
|
| |
-
|
| |
- <2> The reason why is this package here. Mostly for humans.
|
| |
-
|
| |
- <3> DistGit branch, tag, or a commit — so the right version of the package gets included.
|
| |
+ <1> A license for this modulemd file. Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise.
|
| |
|
| |
- <4> List as many packages as you need.
|
| |
+ === Modular dependencies
|
| |
|
| |
- === For which releases?
|
| |
+ Simply put: For which Fedora releases to build?
|
| |
|
| |
To build your module for all Fedora releases that are actively maintained, use the following definition. For anything more than this, such as building against other modules or requiring other modules during runtime, please see the Advanced section below.
|
| |
|
| |
@@ -78,7 +132,7 @@
|
| |
platform: []
|
| |
----
|
| |
|
| |
- === Help users install it (optional, but encouraged)
|
| |
+ === Installation profiles (optional, but encouraged)
|
| |
|
| |
To help users install your module, define installation profiles. These profiles represent a specific use case of your module. Most modules have at least a default profile. But you can specify more. For example, a database module can have a server and a client profile.
|
| |
|
| |
@@ -106,7 +160,7 @@
|
| |
|
| |
<4> List as many profiles as you need.
|
| |
|
| |
- === Public API (optional, but encouraged)
|
| |
+ === Module API (optional, but encouraged)
|
| |
|
| |
List all binary RPM packages in your module that you consider to be the main stable feature of the module. Other (unlisted) packages should be considered unsupported, or an implementation detail.
|
| |
|
| |
@@ -121,6 +175,31 @@
|
| |
- package-two
|
| |
----
|
| |
|
| |
+ === Packages in this module
|
| |
+
|
| |
+ List all source SRPM packages this module should include, referenced them by their dist-git repo name + branch name.
|
| |
+
|
| |
+ [source,yaml]
|
| |
+ ----
|
| |
+ components:
|
| |
+ rpms:
|
| |
+ first-package: <1>
|
| |
+ rationale: Provides the core functionality. <2>
|
| |
+ ref: 3.0 <3>
|
| |
+ second-package:
|
| |
+ rationale: Web UI for the first-package.
|
| |
+ ref: latest
|
| |
+ ... <4>
|
| |
+ ----
|
| |
+
|
| |
+ <1> Name of the package — maps to a DistGit repository name.
|
| |
+
|
| |
+ <2> The reason why is this package here. Mostly for humans.
|
| |
+
|
| |
+ <3> DistGit branch, tag, or a commit — so the right version of the package gets included.
|
| |
+
|
| |
+ <4> List as many packages as you need.
|
| |
+
|
| |
== Advanced definitions
|
| |
|
| |
=== References to the upstream (optional)
|
| |
@@ -159,7 +238,7 @@
|
| |
buildorder: 0 <1>
|
| |
second-package:
|
| |
rationale: Web UI for the first-package.
|
| |
- ref: stable
|
| |
+ ref: latest
|
| |
buildorder: 10 <1>
|
| |
----
|
| |
|
| |
@@ -187,10 +266,7 @@
|
| |
* built agains one or more streams of the same module
|
| |
* work with one or more streams of another module
|
| |
|
| |
-
|
| |
- ==== Building for a specific Fedora release(s) only
|
| |
-
|
| |
- Building **only for Fedora 28**:
|
| |
+ **Building only for Fedora 28**:
|
| |
|
| |
[source,yaml]
|
| |
----
|
| |
@@ -201,7 +277,7 @@
|
| |
platform: [f28]
|
| |
----
|
| |
|
| |
- Building **for everything else than Fedora 28**:
|
| |
+ **Building for everything else than Fedora 28**:
|
| |
|
| |
[source,yaml]
|
| |
----
|
| |
@@ -212,7 +288,7 @@
|
| |
platform: [-f28]
|
| |
----
|
| |
|
| |
- Building **only for Fedora 28 and Fedora 29**:
|
| |
+ **Building only for Fedora 28 and Fedora 29**:
|
| |
|
| |
[source,yaml]
|
| |
----
|
| |
@@ -223,7 +299,7 @@
|
| |
platform: [f28, f29]
|
| |
----
|
| |
|
| |
- ==== Depending on other modules
|
| |
+ **Building against other modules:**:
|
| |
|
| |
Your module can also depend on another modules. Specific streams can be referenced the same way as above in "Building for a specific Fedora release(s) only".
|
| |
|
| |
@@ -238,7 +314,7 @@
|
| |
nodejs: []
|
| |
----
|
| |
|
| |
- ==== Complex dependencies
|
| |
+ **A complex example:**
|
| |
|
| |
Simple things should simple, complex things should be possible. Let's say my module requires `nodejs` during build and run time. It also requires `build-tools` only during build. To make it even more complex, it also requires a specific stream of a `pizza-module` during build and run time, but only on Fedora 27.
|
| |
|
| |
@@ -266,7 +342,7 @@
|
| |
For even more complex scenarios, please study the https://github.com/fedora-modularity/libmodulemd/blob/master/spec.v2.yaml[modulemd specification].
|
| |
|
| |
|
| |
- === Binary packages to exclude (optional)
|
| |
+ === Excluding binary packages (optional)
|
| |
|
| |
One source RPM package might produce multiple binary RPM packages. If you don't want to include some binary packages, list them under `filter`.
|
| |
|
| |
@@ -308,7 +384,7 @@
|
| |
ref: 3.0
|
| |
second-package:
|
| |
rationale: Web UI for the first-package.
|
| |
- ref: stable
|
| |
+ ref: latest
|
| |
----
|
| |
|
| |
=== Including profiles and API (recommended)
|
| |
@@ -357,13 +433,5 @@
|
| |
ref: 3.0
|
| |
second-package:
|
| |
rationale: Web UI for the first-package.
|
| |
- ref: stable
|
| |
- ----
|
| |
-
|
| |
- === Bonus: Converting modulemd v1 to v2
|
| |
-
|
| |
- This video walks through the differences between the legacy modulemd v1 and the current modulemd v2.
|
| |
-
|
| |
- ++++
|
| |
- <iframe width="560" height="315" src="https://www.youtube.com/embed/kQM_jC8S7bM?rel=0&showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
|
| |
- ++++
|
| |
\ No newline at end of file
|
| |
+ ref: latest
|
| |
+ ----
|
| |
\ No newline at end of file
|
| |