From patchwork Sat Feb 17 11:07:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Simone_Wei=C3=9F?= X-Patchwork-Id: 39619 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 A2B4DC48BF5 for ; Sat, 17 Feb 2024 11:07:17 +0000 (UTC) Received: from mout02.posteo.de (mout02.posteo.de [185.67.36.66]) by mx.groups.io with SMTP id smtpd.web10.7881.1708168035915694421 for ; Sat, 17 Feb 2024 03:07:16 -0800 Authentication-Results: mx.groups.io; dkim=fail reason="dkim: body hash did not verify" header.i=@posteo.com header.s=2017 header.b=l/SIWAg4; spf=pass (domain: posteo.com, ip: 185.67.36.66, mailfrom: simone.p.weiss@posteo.com) Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id D1EAA240101 for ; Sat, 17 Feb 2024 12:07:13 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.com; s=2017; t=1708168033; bh=DK2NGbTjksg+LzVQOzyIQM3C7FGdiSz2aBC5K0OgAaY=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version:Content-Type: Content-Transfer-Encoding:From; b=l/SIWAg4sl5QFQaJer5E3a+L5hKiTt+1KJDti+oPp8wU7jRcPlo20zo/AvCjdmTpP 1n288gqBS4MoS0dc1XRQe3GQogznDgaDZeBvZqgelrM3fND0Bdb65ndy7NZ48H/QA/ iRiPgFVga7F6YCs7Q1TUIpoLZtTI+vVsUOYQWKvYewOV8kaJ1FJjBYxdfEIlUB/dbM VY17DNTxT8hE4ax2RCAYaSajcFBYebwd9SZ9xYKZfFz/E3fQMMp9/KH/6zyOzWFjaB V/GolAEui2LlKis3+Km8F4mqMubIjcQCcXXd/Cub0KdxaKNkslLqPBplxMM6+5YqwI 8O4ajJUGE3CXA== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4TcQxD6nCTz6tw8; Sat, 17 Feb 2024 12:07:11 +0100 (CET) From: simone.p.weiss@posteo.com To: bitbake-devel@lists.openembedded.org Cc: docs@lists.yoctoproject.org, =?utf-8?q?Simone_Wei=C3=9F?= Subject: [PATCH v2] bitbake: doc: Add section for variable context Date: Sat, 17 Feb 2024 11:07:03 +0000 Message-Id: <20240217110704.49901-1-simone.p.weiss@posteo.com> MIME-Version: 1.0 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 ; Sat, 17 Feb 2024 11:07:17 -0000 X-Groupsio-URL: https://lists.openembedded.org/g/bitbake-devel/message/15908 From: Simone Weiß This is inspired by the same section in the yocto-docs. It aims to provide information in what contexts(recipes, .conf, bbclass,...) a variable is usually used. For that I tried to group similar variables, so that a short overview is given. This was inspired by [YOCTO #14072], but of course does not implement a warning if a variable is used in an unintended context. Signed-off-by: Simone Weiß --- ...bake-user-manual-ref-variables-context.rst | 89 +++++++++++++++++++ doc/index.rst | 1 + 2 files changed, 90 insertions(+) create mode 100644 doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst new file mode 100644 index 00000000..8252889e --- /dev/null +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +**************** +Variable Context +**************** + +Variables might only have an impact or can be used in certain contexts. Some +should only be used in global files like ``.conf``, while others are intended only +for local files like ``.bb``. This chapter aims to describe some important variable +contexts. + +.. _ref-varcontext-configuration: + +BitBake's own configuration +=========================== + +Variables starting with ``BB_`` usually configure the behaviour of BitBake itself. +For example, one could configure: + +- System resources, like disk space to be used (:term:`BB_DISKMON_DIRS`), + or the number of tasks to be run in parallel by BitBake (:term:`BB_NUMBER_THREADS`). + +- How the fetchers shall behave, e.g., :term:`BB_FETCH_PREMIRRORONLY` is used + by BitBake to determine if BitBake's fetcher shall search only + :term:`PREMIRRORS` for files. + +Those variables are usually configured globally. + +BitBake configuration +===================== + +There are variables: + +- Like :term:`B` or :term:`T`, that are used to specify directories used by + BitBake during the build of a particular recipe. Those variables are + specified in ``bitbake.conf``. Some, like :term:`B`, are quite often + overwritten in recipes. + +- Starting with ``FAKEROOT``, to configure how the ``fakeroot`` command is + handled. Those are usually set by ``bitbake.conf`` and might get adapted in a + ``bbclass``. + +- Detailing where BitBake will store and fetch information from, for + data reuse between build runs like :term:`CACHE`, :term:`DL_DIR` or + :term:`PERSISTENT_DIR`. Those are usually global. + + +Layers and files +================ + +Variables starting with ``LAYER`` configure how BitBake handles layers. +Additionally, variables starting with ``BB`` configure how layers and files are +handled. For example: + +- :term:`LAYERDEPENDS` is used to configure on which layers a given layer + depends. + +- The configured layers are contained in :term:`BBLAYERS` and files in + :term:`BBFILES`. + +Those variables are often used in the files ``layer.conf`` and ``bblayers.conf``. + +Recipes and packages +==================== + +Variables handling recipes and packages can be split into: + +- :term:`PN`, :term:`PV` or :term:`PF` for example, contain information about + the name or revision of a recipe or package. Usually, the default set in + ``bitbake.conf`` is used, but those are from time to time overwritten in + recipes. + +- :term:`SUMMARY`, :term:`DESCRIPTION`, :term:`LICENSE` or :term:`HOMEPAGE` + contain the expected information and should be set specifically for every + recipe. + +- In recipes, variables are also used to control build and runtime + dependencies between recipes/packages with other recipes/packages. The + most common should be: :term:`PROVIDES`, :term:`RPROVIDES`, :term:`DEPENDS`, + and :term:`RDEPENDS`. + +- There are further variables starting with ``SRC`` that specify the sources in + a recipe like :term:`SRC_URI` or :term:`SRCDATE`. Those are also usually set + in recipes. + +- Which version or provider of a recipe should be given preference when + multiple recipes would provide the same item, is controlled by variables + starting with ``PREFERRED_``. Those are normally set in the configuration + files of a ``MACHINE`` or ``DISTRO``. diff --git a/doc/index.rst b/doc/index.rst index 3ff8b158..ee1660ac 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,6 +13,7 @@ BitBake User Manual bitbake-user-manual/bitbake-user-manual-intro bitbake-user-manual/bitbake-user-manual-execution bitbake-user-manual/bitbake-user-manual-metadata + bitbake-user-manual/bitbake-user-manual-ref-variables-context bitbake-user-manual/bitbake-user-manual-fetching bitbake-user-manual/bitbake-user-manual-ref-variables bitbake-user-manual/bitbake-user-manual-hello