From patchwork Wed Nov 13 15:28:11 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 52423 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6325AD462BF for ; Wed, 13 Nov 2024 15:28:32 +0000 (UTC) Received: from relay1-d.mail.gandi.net (relay1-d.mail.gandi.net [217.70.183.193]) by mx.groups.io with SMTP id smtpd.web11.14131.1731511703591560375 for ; Wed, 13 Nov 2024 07:28:23 -0800 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=HxANBv2a; spf=pass (domain: bootlin.com, ip: 217.70.183.193, mailfrom: antonin.godard@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 03AEC240003; Wed, 13 Nov 2024 15:28:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1731511702; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=LNWvbcCGaHZ4HWAc1IWkeHgN2L+2SG1S/oHBgVXUnMU=; b=HxANBv2a4+JUsHA8tc8D3H9KGUJvHG0nbgeYpTD1AtHQUK6pRwfeVn6gAbW4IPuTUlEHsu cwXpkcradPGz8xIOJyLFNwe8IzITOpiirAoqmWmbUHeeq+mi768nTAyyISIOdBFGYhjwKv AiF/HKV10x8CAs8ST0DaftTJmp52hnbo3ricMTXF417Cv0fBmOAErRJDRW0KA7PkkDvJaR ybgWCUWmE/HO8uiaaoXormp7bewNlNjZj4HuHJnRwrfP3Gog2uTD4KT7r7FgJf1l9sS68t HQFXIsQn/L3S8QJZ/kGHqErQzRPD8TAFaxAlj+j83oHXvkENuP7+vZlFuVWOXA== From: Antonin Godard Date: Wed, 13 Nov 2024 16:28:11 +0100 Subject: [yocto-docs PATCH v4 1/2] conf.py: add a bitbake_git extlink MIME-Version: 1.0 Message-Id: <20241113-layer-confs-v4-1-a4758fa4d1a8@bootlin.com> References: <20241113-layer-confs-v4-0-a4758fa4d1a8@bootlin.com> In-Reply-To: <20241113-layer-confs-v4-0-a4758fa4d1a8@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Quentin Schulz , Antonin Godard X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=953; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=6ZNvm3WUu2JjNgLs8af7rSs7BtVbgsjHBX7632HItSc=; b=owEBbQKS/ZANAwAIAdGAQUApo6g2AcsmYgBnNMWVjCBYluOoNJjGWH4iX93kOWRrR8knINUmi UsB42t59TWJAjMEAAEIAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCZzTFlQAKCRDRgEFAKaOo NhiAD/wLU/ctJiiRN1dlXqmH26+a4TJp9/LH+LcC5Rau3GoI+pBF+CXFVogiE9um+yvLAbMMcfU 5dTIHDWvo57Ch5EFxaGs7jgIwN1pBQN4Wj419yxWLYkqO/cA9FuLj00C7V+S+eanwwaKAWyTsIK HJKlwUh+8Mnbft9Rm7ZOEPZLPZUdMLupvLSz0YJCypXpUOeVmIFf1FD9bbkleSEBaHhFcCG8+q7 UcYsEqvzgVuyqOfKpORREkHwdTMdXkIHCdFKEb2cynhTa2suDPHhw/DOKLGokzpVT24YSL5QIZp 4U8yEmpCQzCLjw0afHnc3rXdFFejiy9g4D40HxJ+OrEwSOhJDPzibhn/aHvIzomy4gBI637ZQlm /Iw6iv5xZ6dVF4DIUa9ocH1qwI8soV9dUVhC2vyNIhqQPihJOSrTXFOGTk7m9aj6OgNV6WjZ2g4 1e+jI8pFwytRBn85SXuSGk9CaPmLbG4d0LsMZhFcEaetx2TPfXvtd6/ZGHc1Z2fGuX2ecOO6ChC tl/J4999eqeXlS6VZUiPUIhGfZR8sSpFCm/1nRD3tgVW4DCnOARrEFwSvuGpGuapZa9fRImGy4q v8TpRtiUIT3/qtdVa/2xtzW9+Ak9vAEesfni7ZpiZBB6JluidxyU+VIe9z5RlAafeRKupgRVviZ MI6prANQau6jYkQ== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-GND-Sasl: antonin.godard@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 13 Nov 2024 15:28:32 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5738 To make references to the bitbake repo, add an extlink for it and use it in the docs with ":bitbake_git:`lib/bb/utils.py `". Reviewed-by: Quentin Schulz Signed-off-by: Antonin Godard --- documentation/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/conf.py b/documentation/conf.py index c7dd4e03fc0e99176a0fa2f74fda58efaf0af9b2..b0e7c91eb5d8e4e855c0ca46351586cdf237fcb3 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -90,6 +90,7 @@ rst_prolog = """ # external links and substitutions extlinks = { + 'bitbake_git': ('https://git.openembedded.org/bitbake%s', None), 'cve_mitre': ('https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s', 'CVE-%s'), 'cve_nist': ('https://nvd.nist.gov/vuln/detail/CVE-%s', 'CVE-%s'), 'yocto_home': ('https://www.yoctoproject.org%s', None), From patchwork Wed Nov 13 15:28:12 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 52424 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 65783D462C5 for ; Wed, 13 Nov 2024 15:28:32 +0000 (UTC) Received: from relay1-d.mail.gandi.net (relay1-d.mail.gandi.net [217.70.183.193]) by mx.groups.io with SMTP id smtpd.web11.14132.1731511703719995274 for ; Wed, 13 Nov 2024 07:28:24 -0800 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=kR0wXC3k; spf=pass (domain: bootlin.com, ip: 217.70.183.193, mailfrom: antonin.godard@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 4490B240007; Wed, 13 Nov 2024 15:28:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1731511702; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=SruzrTvMbnIuycwYyfh1+XkATD5YTAIe//gRRR4VAMA=; b=kR0wXC3kHMGdBxbzBo0nlWjWX5H/iEGieHOl61PNo3GlnogbLyLe0Nbz48EoxR3mKigUGQ o11ZkSEQBJzBn6X+aKNusus9krDSRejNyAtnuUKFCFv7GyAL3c5rbQqiTH/QcJ2FVdZaK4 FS1hx3GRMjQ2AzIfgn4j8vBTpWYm+SfNJY7/YjScyIM6BLPXT+N8ZlFVWKcXCYvcFSNzAX EmWhBtIknlo9zVNxnmD4/yfu9OoiKig5DBuTwm8t8oclXYySnQQ4l1OPkmAJ2h8W9bk+b4 QjcPsOidrjLVRL1K+ux1APfePrJLF/Xag2SDo8QaLVIF52w5JVRAdjcUi9bpkA== From: Antonin Godard Date: Wed, 13 Nov 2024 16:28:12 +0100 Subject: [yocto-docs PATCH v4 2/2] dev-manual: document how to provide confs from layer.conf MIME-Version: 1.0 Message-Id: <20241113-layer-confs-v4-2-a4758fa4d1a8@bootlin.com> References: <20241113-layer-confs-v4-0-a4758fa4d1a8@bootlin.com> In-Reply-To: <20241113-layer-confs-v4-0-a4758fa4d1a8@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Quentin Schulz , Antonin Godard X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=5773; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=ffvRsdrOMeJvt3WWrg569RW5SKmjZWeNGTxnKb+7ZzU=; b=owEBbQKS/ZANAwAIAdGAQUApo6g2AcsmYgBnNMWVredeVK5eAIe1jgAAgJkrU/pJ/d/8CQUxa zXeixvJTT+JAjMEAAEIAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCZzTFlQAKCRDRgEFAKaOo Nt48D/44OI08IPR/4U3CkGZJLNrbR9xu4pDJMStutuWun98iZqxLnEPeYo9yE5QZOmVsHVumbnk 2aY2eUiofDlo34hsXDbxE5UoSuZf7BrsXblW3bF3VZCO5B81pNkJx2c6YD5AYfPw8x2MBBQKYB0 YxtZBS/cJbPInal2QjklxR5jDqpQ8SztEkvQN4dAYK+n9rkpQJ7N/u4VakIunceDPVU2ttukEUU vjUI0vRPx8p3lAQ4zB2SHDcKc1hJg8obsM9iROgi0NDSspnRkliRuvws9Vsd9dkpIh5govSteTS 7jcLAuYFKNBanCu2lLBYRvBKYx1dJfSqQ8dUjF8oVdMxjvV11zMihrDrsE4rzYXwmiqoUgEUdEf yrkrYU2L3oy5xuEkh58fJ+ZFn4NxIjX6BdQQNm5fWWFyXq4EAC/omKi5Mhk4UOGKUNUBQ3hWcYX Mein6KOE54hzrBDpvRakk7dEg7zPWjKuaIJZhL94OrwTwgEH1UcIRmdi2fyQY9+CYKKOiOOHRhk iqp1247YScpDIz3dQXBegVfsuPXczmlHJPTTkfFbnID2oudjSvFIzqj5UEBwM2sl4pN5Fj/63Al Okd/wZcT9WXkfQKPKHANNSZVJHE10ajjirqVNPHeITPYRM600QLnBksAF5toi/dasoh3kCjk481 T3DjyskJLctSQCQ== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-GND-Sasl: antonin.godard@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 13 Nov 2024 15:28:32 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5740 Add a section on providing global level configuration from the layer.conf file. Since this file is parsed at an earlier stage in the parsing process, it's not possible to combine bb.utils.contains and {DISTRO,MACHINE}_FEATURES to conditionally set some configurations. This patch documents: - First that this file can be used for providing such configuration. - Then demonstrate how to conditionally provide them, using a technique that is currently used in meta-virtualization (https://git.yoctoproject.org/meta-virtualization/tree/conf/layer.conf#n50). Fixes [YOCTO #12688]. Reviewed-by: Quentin Schulz Signed-off-by: Antonin Godard --- documentation/dev-manual/layers.rst | 90 +++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst index 91889bd0ae391c7b6e62068778ae5c180c840762..39cd1963a60086902d7e04e4bdde01f7e661371f 100644 --- a/documentation/dev-manual/layers.rst +++ b/documentation/dev-manual/layers.rst @@ -644,6 +644,96 @@ variable and append the layer's root name:: order of ``.conf`` or ``.bbclass`` files. Future versions of BitBake might address this. +Providing Global-level Configurations With Your Layer +----------------------------------------------------- + +When creating a layer, you may need to define configurations that should take +effect globally in your build environment when the layer is part of the build. +The ``layer.conf`` file is a :term:`configuration file` that affects the build +system globally, so it is a candidate for this use-case. + +.. warning:: + + Providing unconditional global level configuration from the ``layer.conf`` + file is *not* a good practice, and should be avoided. For this reason, the + section :ref:`ref-conditional-layer-confs` below shows how the ``layer.conf`` + file can be used to provide configurations only if a certain condition is + met. + +For example, if your layer provides a Linux kernel recipe named +``linux-custom``, you may want to make :term:`PREFERRED_PROVIDER_virtual/kernel +` point to ``linux-custom``:: + + PREFERRED_PROVIDER_virtual/kernel = "linux-custom" + +This can be defined in the ``layer.conf`` file. If your layer is at the last +position in the :term:`BBLAYERS` list, it will take precedence over previous +``PREFERRED_PROVIDER_virtual/kernel`` assignments (unless one is set from a +:term:`configuration file` that is parsed later, such as machine or distro +configuration files). + +.. _ref-conditional-layer-confs: + +Conditionally Provide Global-level Configurations With Your Layer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases, your layer may provide global configurations only if some +features it provides are enabled. Since the ``layer.conf`` file is parsed at an +earlier stage in the parsing process, the :term:`DISTRO_FEATURES` and +:term:`MACHINE_FEATURES` variables are not yet available to ``layer.conf``, and +declaring conditional assignments based on these variables is not possible. The +following technique shows a way to bypass this limitation by using the +:term:`USER_CLASSES` variable and a conditional ``require`` command. + +In the following steps, let's assume our layer is named ``meta-mylayer`` and +that this layer defines a custom :ref:`distro feature ` +named ``mylayer-kernel``. We will set the :term:`PREFERRED_PROVIDER` variable +for the kernel only if our feature ``mylayer-kernel`` is part of the +:term:`DISTRO_FEATURES`: + +#. Create an include file in the directory + ``meta-mylayer/conf/distro/include/``, for example a file named + ``mylayer-kernel-provider.inc`` that sets the kernel provider to + ``linux-custom``:: + + PREFERRED_PROVIDER_virtual/kernel = "linux-custom" + +#. Provide a path to this include file in your ``layer.conf``:: + + META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc" + +#. Create a new class in ``meta-mylayer/classes-global/``, for example a class + ``meta-mylayer-cfg.bbclass``. Make it conditionally require the file + ``mylayer-kernel-provider.inc`` defined above, using the variable + ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``:: + + require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)} + + For details on the ``bb.utils.contains`` function, see its definition in + :bitbake_git:`lib/bb/utils.py `. + + .. note:: + + The ``require`` command is designed to not fail if the function + ``bb.utils.contains`` returns an empty string. + +#. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to + the :term:`USER_CLASSES` variable:: + + USER_CLASSES:append = " meta-mylayer-cfg" + + This will add the class ``meta-mylayer-cfg`` to the list of classes to + globally inherit. Since the ``require`` command is conditional in + ``meta-mylayer-cfg.bbclass``, even though inherited the class will have no + effect unless the feature ``mylayer-kernel`` is enabled through + :term:`DISTRO_FEATURES`. + +This technique can also be used for :ref:`Machine features +` by following the same steps. Though not mandatory, it is +recommended to put include files for :term:`DISTRO_FEATURES` in your layer's +``conf/distro/include`` and the ones for :term:`MACHINE_FEATURES` in your +layer's ``conf/machine/include``. + Managing Layers ===============