From 008793e4dcffc21992777d1b2cd510a8d67770a3 Mon Sep 17 00:00:00 2001 From: Brendan Reilly Date: Tue, 23 Mar 2021 13:51:20 -0400 Subject: [PATCH] Update static context docs for PackagerV3 changes --- docs/STATIC_CONTEXTS.rst | 70 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/STATIC_CONTEXTS.rst b/docs/STATIC_CONTEXTS.rst index 8f96d6ce..9c574d1e 100644 --- a/docs/STATIC_CONTEXTS.rst +++ b/docs/STATIC_CONTEXTS.rst @@ -1,6 +1,68 @@ Static contexts =============== +By default, module build contexts are generated by MBS and used to ensure uniqueness for each +NSVC. Static contexts, which can be set in a module's YAML document, allow a user to specify +their own contexts for their builds. This is used to make a module's per stream dependencies +and upgrade paths more explicit for multicontext modules. + +There are two methods to declare static contexts, one which uses ``ModuleStreamV2`` and a newer +one which uses ``PackagerV3``. The ``ModuleStreamV2`` method uses the already existing ``xmd`` +field to define its contexts, and MBS uses the defined dependencies instead of relying on MSE. +The ``PackagerV3`` method uses a new field ``configurations`` in the YAML document to declare +the contexts, streams, and dependencies, which MBS uses to bypass MSE. + +**PackagerV3 Method** + +- this method requires a modulemd-packager document, which is declared via ``document`` at the + start of the file. Also, the Module metadata format version to be set to ``3``. +- the user can set their own context and dependencies when required through ``configurations``. + ``configurations`` is a list of contexts in the ``data`` section of a YAML document used for + build configuration, to replace Module Stream Expansion. To make static contexts work, you + need to define ``context`` and ``platform`` for each platform you're building for. You may also + optionally set context specific ``requires`` and ``buildrequires`` values. +- The context definition needs to be defined in the initial modulemd yaml file. ``configurations`` + build property overrides any dependencies set through the ``dependencies`` property. +- `static contexts` and `stream expansion` are mutually exclusive i. e. the streams defined in + ``buildrequires`` and ``requires`` of `static context` will not be expanded and need + to be precisely defined by the user. (You can not use `stream expansion` notation as ``[]`` + or ``-f28`` as this will result in an error) + + +**Example** +:: + +document: modulemd-packager +version: 3 + . + . + . + configurations: + - context: context1 + platform: f28 + buildrequires: + module1: stream1 + . + . + . + moduleN: streamN + requires: + module1: stream1 + . + . + . + moduleN: streamN + - context: context2 + platform: f29 + requires: + module1: stream1 + . + . + . + + +**ModuleStreamV2 Method** + - the user can specifically set their own context and dependencies when required through ``mbs_options``. ``mbs_options`` is a dict which is part of the ``xmd`` property and is used to configure additional build options for MBS. To make static contexts work, @@ -17,6 +79,14 @@ Static contexts same ``build contexts`` takes place. - as per design of the modulemdlib the only types which can be put inside of the ``xmd`` property are ``dict`` and ``string``. +- the user can set a boolean field ``static_context`` in the ``data`` section of a YAML + document describing a stream. This field is optional and will default to ``False`` if + unspecified. +- if ``static_context`` is set to ``True``, dependency solvers will consider the context + meaningful for determining the upgrade path. Otherwise, if it is set to ``False``, + a static context will not be used. To maintain backwards compatibility, if the + ``mbs_options`` dict contains a ``contexts`` dict, ``static_context`` will be treated + as ``True``. **Example**: