From 6de21a42a63ac2b08318484ee35ccd3c6c65c732 Mon Sep 17 00:00:00 2001
From: Paul Eggleton <paul.eggleton@microsoft.com>
Date: Wed, 28 Oct 2020 04:36:25 -0700
Subject: ref-manual: add migration info about MLPREFIX changes

Add a migration subsection on the need to add MLPREFIX to conditional
package dependencies in gatesgarth.

(From yocto-docs rev: e202beabfc1282d6999fde0ced89e41c993da27f)

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/migration-3.2.rst | 31 ++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

(limited to 'documentation/ref-manual')

diff --git a/documentation/ref-manual/migration-3.2.rst b/documentation/ref-manual/migration-3.2.rst
index 57c74354f9..9b65e26c48 100644
--- a/documentation/ref-manual/migration-3.2.rst
+++ b/documentation/ref-manual/migration-3.2.rst
@@ -75,6 +75,37 @@ pseudo will throw an ``abort()`` and direct you to a :yocto_wiki:`wiki page </wi
 that explains how to deal with this.
 
 
+.. _migration-3.2-multilib-mlprefix:
+
+``MLPREFIX`` now required for multilib when runtime dependencies conditionally added
+------------------------------------------------------------------------------------
+
+In order to solve some previously intractable problems with runtime
+dependencies and multilib, a change was made that now requires the :term:`MLPREFIX`
+value to be explicitly prepended to package names being added as
+dependencies (e.g. in :term:`RDEPENDS` and :term:`RRECOMMENDS` values)
+where the dependency is conditionally added.
+
+If you have anonymous python or in-line python conditionally adding
+dependencies in your custom recipes, and you intend for those recipes to
+work with multilib, then you will need to ensure that ``${MLPREFIX}``
+is prefixed on the package names in the dependencies, for example
+(from the ``glibc`` recipe): ::
+
+    RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}"
+
+This also applies when conditionally adding packages to :term:`PACKAGES` where
+those packages have dependencies, for example (from the ``alsa-plugins`` recipe): ::
+
+    PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
+    ...
+    RDEPENDS_${PN}-pulseaudio-conf += "\
+            ${MLPREFIX}libasound-module-conf-pulse \
+            ${MLPREFIX}libasound-module-ctl-pulse \
+            ${MLPREFIX}libasound-module-pcm-pulse \
+    "
+
+
 .. _migration-3.2-packagegroup-core-device-devel:
 
 packagegroup-core-device-devel no longer included in images built for qemu* machines
-- 
cgit v1.2.3-54-g00ecf