Document virtual platforms

README.rst

@@ -976,3 +976,12 @@ MBS is licensed under MIT license. See |LICENSE|_ file for details.
 
 Parts of MBS are licensed under 3-clause BSD license from:
 https://github.com/projectatomic/atomic-reactor/blob/master/LICENSE
+
+
+Virtual Modules
+===============
+
+For a detailed description of virtual modules, see |docs/VIRTUAL_MODULES.rst|_.
+
+.. |docs/VIRTUAL_MODULES.rst| replace:: ``docs/VIRTUAL_MODULES.rst``
+.. _docs/VIRTUAL_MODULES.rst: docs/VIRTUAL_MODULES.rst

docs/VIRTUAL_MODULES.rst

@@ -0,0 +1,91 @@
+Virtual (Pseudo) Modules
+========================
+
+A virtual module is any module which is not built by MBS directly, but instead its metadata is
+imported to the MBS database. A virtual module is defined using a modulemd file with extra data
+in the ``xmd`` section. These are usually base modules such as ``platform``.
+
+
+Example
+=======
+
+Here is an example of the Fedora 31 platform module, which is also virtual module::
+
+    document: modulemd
+    version: 1
+    data:
+      description: Fedora 31 traditional base
+      license:
+        module: [MIT]
+      name: platform
+      profiles:
+        buildroot:
+        rpms: [bash, bzip2, coreutils, cpio, diffutils, fedora-release, findutils, gawk,
+               glibc-minimal-langpack, grep, gzip, info, make, patch, redhat-rpm-config,
+               rpm-build, sed, shadow-utils, tar, unzip, util-linux, which, xz]
+        srpm-buildroot:
+        rpms: [bash, fedora-release, fedpkg-minimal, glibc-minimal-langpack, gnupg2,
+               redhat-rpm-config, rpm-build, shadow-utils]
+      stream: f31
+      summary: Fedora 31 traditional base
+      context: 00000000
+      version: 1
+      xmd:
+        mbs:
+        buildrequires: {}
+        commit: f31
+        requires: {}
+        koji_tag: module-f31-build
+        mse: TRUE
+
+
+Virtual Module Fields
+=====================
+
+Required standard fields:
+
+- ``name`` - the module's name
+- ``stream`` - the module's stream
+- ``version`` - the module's version
+- ``context`` - the module's context; this can be simply ``00000000``, which is the default value
+    in MBS
+
+Optional standard fields:
+
+- ``profiles.buildroot`` - defines the list of packages installed during the RPM build in Koji
+- ``profiles.srpm-buildroot`` - defines the list of packages installed during the SRPM build;
+    ``module-build-macros`` must be present if this is a base module like ``platform``
+
+Custom fields in xmd:
+
+- ``buildrequires`` - the buildrequires as resolved by MBS; it should always be an empty dictionary
+    for base modules
+- ``requires`` - the requires as resolved by MBS; it should always be an empty dictionary
+    for base modules
+- ``commit`` - this should be ``virtual`` or some other identifier that is meaningful since a commit
+    is not applicable when a module is directly imported
+- ``mse`` - this is an internal identifier used by MBS to know if this is a legacy module build
+    prior to module stream expansion; this should always be ``TRUE``
+- ``koji_tag`` - this defines the Koji tag with the RPMs that are part of this module; for base
+    modules this will likely be a tag representing a buildroot
+- ``virtual_streams`` - the list of streams which groups multiple modules together; for more
+    information on this field, see the ``Virtual Streams`` section below
+- ``disttag_marking`` - if this module is a base module, then MBS will use the stream of the base
+    module in the disttag of the RPMS being built. If the stream is not the appropriate value, then
+    this can be overridden with a custom value using this property. This value can't contain a dash,
+    since that is an invalid character in the disttag.
+
+
+Virtual Streams
+===============
+
+The ``virtual_streams`` field defines the list of streams which groups multiple modules together.
+
+For example, all the 8.y.z versions of the ``platform:el8.y.z`` module defines
+``virtual_streams: [el8]``. That tells MBS that if some built module has a runtime dependency on
+``platform:el8``, MBS can choose dependencies built against any platform modules which provides
+the ``el8`` virtual stream to fulfill this dependency.
+
+This allows building a module which buildrequires ``platform:el8.1.0`` against modules which have
+been built against ``platform:el8.0.0`` as long as they both have a runtime requirement of
+``platform:el8``.