From patchwork Fri Sep 11 15:11:07 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97984 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 332EFC88E50 for ; Fri, 11 Sep 2026 15:11:39 +0000 (UTC) Received: from smtpout-02.galae.net (smtpout-02.galae.net [185.246.84.56]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.41850.1789139492369599227 for ; Fri, 11 Sep 2026 08:11:32 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=nf4TrVqW; spf=pass (domain: bootlin.com, ip: 185.246.84.56, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-02.galae.net (Postfix) with ESMTPS id B12591A01ED for ; Fri, 11 Sep 2026 15:11:30 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id 7D400601DE for ; Fri, 11 Sep 2026 15:11:30 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id DBB6A11C7AFAD; Fri, 11 Sep 2026 17:11:25 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139486; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=JlIKjxK7wIcLiNyNP1E9D+447813tfZFcYkuTI2KBBU=; b=nf4TrVqWUB/WTrhfmTrF1siJicZb6UTlFmx5sLk14fUZYuiLQmMD7irBQCSAWrdhgV6K4J oYzzZxmXF6OJqxoNPHpU03Zz9qmCFdrponV7M6xrdeBamrEmYE42d/qUfjqWaYZLaTiy5G jmmgnTebNHfi9b5PmRM2p5tjKKaGJLputtJpquUUHmXwHS/IoIQAlc2kef3XLrvgeInXZv 4XpCYlM7JG64vScoiCxd2KTSdD+OXewZUcrNvWrCpNQcMBypdSDDPvpomlnTbyqVboktTU 5xdB8tWq22DYNCACPW2DpIy/Sf1jLLq6CzQxk/q2mlVPGILeXxUT2pW075mvWw== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:07 +0200 Subject: [PATCH 1/8] ref-manual/terms.rst: Configuration File: precise machine conf files location MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-1-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=1274; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=EhEqGO5TOiZxkHHpm6A6OlUJZxdOsMxELPqL2zSV46M=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoVsxm6/m9rhmHFaWyYjHvdz7na79EtB/x+R rrRkjrfSASJAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFQAKCRDRgEFAKaOo NmuBD/0SDvgKKjEkIXDFd1TbzID7fX44grMAMtJvCMrMlF9wG0nQToc5/U1wq8F+Lh2TrrhEeHC pygVd2zMtolt+OVDAUEWgwIX0eWDgzvF8wd3Du343/f2vLm3o3k8skaGTIoRI010B0wKgaXLRs5 FrO/cDH6dG1KCuPqzD0NBTIOgi+Sp3rEOgTfSbmHmOmsVoFz0t1AH3UflBlIXsMXeXGQreMViIU e3HtNBd1pZdnMr2rvoY6kJhj0vx1M2eFxc7CIt5ltaeeCKbCsrdZSn+MWEvkeesi7GySAKab9iG El5XSlcVTIBmLt53/pjmloVPGOFEsXfOPGho5btmmXJeD/5t/j4Wg7NUMML15KQWFHpDlsQAhPp jepctuwfxHuryFRCFF2Sn5oFKXhRIXaf/I6Gk9gAjlHq+MuGIIqvAbC3JEpcwArbshKu8gyCtad uvR2tr2Ewp485YFHK5WirMuNQnzaXHXdUlUtKK71vxMFdY3t1+4v6fzTT1ylcKPSjsdCKjJ0Bz5 CbnmfOBQVErfkF7n19E6+Vm1++lEG0Jb5SU6R1mG5tcSLdjQwBV47KmPfi2pcgTjYKG5rGf9gs0 yf6wdUD7AgbCKHl4/D9RG5YogJTPUsTXplwl2V8BlagrcC52p+Sq4uU+3z6FKJVvzdsVHyv6INh YatfA6mJzWjfkJQ== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10470 Machine configuration file are usually found in BSP layers, so let's say that. Signed-off-by: Antonin Godard --- documentation/ref-manual/terms.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index 022185f83..22cbc8002 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst @@ -200,8 +200,8 @@ universal, the list includes them just in case: contains user-defined variables that affect every build. The :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto "distro" configuration variables used only when building with this - policy. Machine configuration files, which are located throughout the - :term:`Source Directory`, define variables for specific hardware and are + policy. Machine configuration files, which are located + :ref:`bsp-manual/bsp:BSP Layers>, define variables for specific hardware and are only used when building for that target (e.g. the :file:`machine/beaglebone.conf` configuration file defines variables for the Texas Instruments ARM Cortex-A8 development board). From patchwork Fri Sep 11 15:11:08 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97983 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 1E5C0C88E58 for ; Fri, 11 Sep 2026 15:11:39 +0000 (UTC) Received: from smtpout-02.galae.net (smtpout-02.galae.net [185.246.84.56]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.41824.1789139497091096181 for ; Fri, 11 Sep 2026 08:11:37 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=XmTrTZxd; spf=pass (domain: bootlin.com, ip: 185.246.84.56, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-02.galae.net (Postfix) with ESMTPS id 385D61A01ED for ; Fri, 11 Sep 2026 15:11:35 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id 0DEFD601DE for ; Fri, 11 Sep 2026 15:11:35 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 62F0C11C7AFA5; Fri, 11 Sep 2026 17:11:30 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139490; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=oWi8zHX3MxDWFBnIdFOvdmug3B6eaSlCwNnvOHJ6wSQ=; b=XmTrTZxdhGefFV1OC3cWFLUqFJZNyRL5T5KO5H3HH2spfvbem9TvR8JuRMPK98KMeaFcXC NPw5KBfDTICx2zVb0VkVMfnzu1Ivb5LK29azQBGWeMZGglXSeIxl0MaRFjqUtugR9SKp01 VcrHF2PaMIPgL+gfAg+w0SorwshTpRiuK7L+w+x9BhlDKrEmmM/NFUMK4efUy4TA4fr8oA cjpo+7xNpSPMv8SZIMa/h0FG+AkQA0H2m8aO/ttQssta/K64WzN/8e5itREb4ja1zWFr9E cIo2UcbMdWJ+TkEfAD6sNdI7SemQWHVqB/U/eXGdFlJ3LUneV9ifoGxVLcoiNA== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:08 +0200 Subject: [PATCH 2/8] ref-manual/terms.rst: Configuration File: split paragraph in a list MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-2-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=3170; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=c2HBW0G6dMNziTcFg2o+SFdub8df3IuB2wXWjH34jD8=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoW/Gpasua0cclwrJFNa59jSp+gfH75dWDmB ZJb+55reQ+JAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFgAKCRDRgEFAKaOo NlrjD/42M7djxboUXbtiGRpzukx3n6Ri+GnPqyea7ylOB0Qp3CaezRm2b09Vgak1E+PRYYSCoL0 APl1BvyTYwLI2jWd4g6U95W8J7u9FPi/UHmRuk2UqUvWkMzL9x4mQOIKHmQ+Sr+icaK0x0kZ5// 6R+OwrySOIhR0/l2AwpTH6JV6ovgRVJIAkhU1BvAY6xgjXer1RFV3APXFrdgQQL4Zt1lKmvxbU1 GNbAKiBBQX6hzBf6bMKGscWLC96733fUtrElcf0jmpRawVwbQf2CvPQjwEF00OoG77/928UIeQD xB2cF2PJdfYjho59E48K3iH9jtmmMpOhneaNOSRvAZzppYikKk0BCjBl0LjiMvgr2FPGiOa6QbO JkzY5TzSp7TqrHLbMte/81WEfbprvph2hOuFro0cY7X6LtdU8WXzgFGu9SbtoAb3X+zNJHm4yii JJsk6we6x10EGGJ5aWVvFe7c1GxqacLUbUIc3/Skjahqp/wEmc5PVrYUPjHa1FS/CMwp0TXtL5N DeHscMEvoiFK5Oo2Dx9xDWZ7k9wKYqPNQTo+hyiRG4/uHM7pEdDBRBJhY39nyn4TCiGzyFmSX5c ymhucs7ycCtd++zTJBfNXaX4wcGVce1gsA1XBHzyqg/PUTVV3vM25/fqHIBKRpCIZltJWtQUf/L QK4Vxz3fTuM5trA== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10471 Use a list to enumerate the different kinds of configuration files there are, to improve readability. Signed-off-by: Antonin Godard --- documentation/ref-manual/terms.rst | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index 22cbc8002..c210da4cb 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst @@ -195,19 +195,30 @@ universal, the list includes them just in case: build system what to build and what to put into the image to support a particular platform. - Configuration files end with a ``.conf`` filename extension. The - :file:`conf/local.conf` configuration file in the :term:`Build Directory` - contains user-defined variables that affect every build. The - :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto - "distro" configuration variables used only when building with this - policy. Machine configuration files, which are located - :ref:`bsp-manual/bsp:BSP Layers>, define variables for specific hardware and are - only used when building for that target (e.g. the - :file:`machine/beaglebone.conf` configuration file defines variables for - the Texas Instruments ARM Cortex-A8 development board). - :term:`Configuration Fragments ` such as - :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` define snippets of - configuration that can be enabled from the command-line. + Configuration files end with a ``.conf`` filename extension. There are + multiple types of configuration files, such as: + + - The :file:`conf/local.conf` configuration file in the :term:`Build + Directory` contains user-defined variables that affect every build. + + - The :file:`meta-poky/conf/distro/poky.conf` configuration file defines + Yocto "distro" configuration variables used only when building with + this policy. See the :ref:`dev-manual/custom-distribution:creating your + own distribution` section of the Yocto Project Reference Manual for + more information. + + - Machine configuration files, which are located :ref:`bsp-manual/bsp:BSP + Layers`, define variables for specific hardware and are only used when + building for that target (e.g. the :file:`machine/beaglebone.conf` + configuration file defines variables for the Texas Instruments ARM + Cortex-A8 development board). + + - :term:`Configuration Fragments ` such as + :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` define snippets of + configuration that can be enabled from the command-line. + + See also the :doc:`/ref-manual/structure` section of the Yocto Project + Reference Manual for more example of configuration files. :term:`Configuration Fragment` A :term:`Configuration Fragment` (also called Standard :term:`Configuration From patchwork Fri Sep 11 15:11:09 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97986 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 34D51C88E45 for ; Fri, 11 Sep 2026 15:11:49 +0000 (UTC) Received: from smtpout-02.galae.net (smtpout-02.galae.net [185.246.84.56]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.41855.1789139501376046329 for ; Fri, 11 Sep 2026 08:11:41 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=xR5o4JWc; spf=pass (domain: bootlin.com, ip: 185.246.84.56, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-02.galae.net (Postfix) with ESMTPS id B12A21A01EF for ; Fri, 11 Sep 2026 15:11:39 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id 87104601DE for ; Fri, 11 Sep 2026 15:11:39 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id E997611C7AFBA; Fri, 11 Sep 2026 17:11:34 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139495; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=2HZqUgnIZnSUhCpT4blXX91qHtM0mO+O1vXLCeclhD0=; b=xR5o4JWc1TlRcbjDR9zZ0BgBdtgrDiE+ofjl6Wehs9qU4U0COWHbz4HP/rkj22dQEtlW2/ OPrykozDHFUf/rZpfzvnlk7ARtaOVdJNsPwMhPq8LwrYITWm4mx2tcYIzbHLFWazEPDgys Kfhsa2TNPKsxSHhYLL86286bLem+rBRAU9dbD5w7hRyw4YUxwjVR/fJAbjkahsTIDvq598 AqIIGtgKMS+vOVy38K5RV5Xv/jx+1yhLpT3XwePgHTm8nclitxy7b5HWtG1v53thzIOwQe FSGnIETP3RPIc6/ujioGzp+XGngmo0qLfom9/m1/+L4hcE09IsGNANMxnB6KLA== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:09 +0200 Subject: [PATCH 3/8] ref-manual/terms.rst: Configuration File: use a link to local.conf MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-3-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=1214; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=heuNLsku99EyCCYchrYkQstc7jvKb2TTTr0yO0SuMf8=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoWvoURtkySSoeKtTfvyGhbh1nHTvNCyb0/1 vP8P9903Y6JAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFgAKCRDRgEFAKaOo NgyZD/0emd9zT26N5PdffSCDQ5EsNIlZOpBZxdgMnCxNGd7nViqW9O7a3zMSyNHzKdxhkB/Bc84 d+0g8cUC6/OBhrg7Rq987SjfT/ICSNJNTRu7CBx+zP74KufdhxhUi80+GFe+C5c8WS2Ardl2R2c HD3LqZsNffmjxUzHRXyJykAhV2p/EaJpdPJwys8/dt6MH3dI5Wz4j+czvH9ihZI1SQWJrarKRLx lmyHcvmhUJoOwgYQsSn+5XWvNnibe9/nvgKVD1pSG2r6/JERZXwOO7C6NLXs5RrA6Dx0EP9Fw9y JL98mPCThK3tE7tVphLdUklKLjv7LcJ8i69bz8pOQdPkHcoQlWmibw9PTVv7gL18KdAxX3vK6Lo IYsqzTFV7CjRJTgC5C85Nu/l28R2mBlbfWgoik5Fisqjv6kyQ3oZGNgIDqTjc6WszYSuKQF9Epx DZNs+EYh5gP/ZshA6q0bPN7ZLeaRA9lcFuq+dH8ggeeOvP2uIfCW4o9TIyXr1CQe8kNJGB0LLV2 hGSQiy44LcDD/L8oypX2L0d6Q8a9OfxahNrrZtIluIIqqgo38pDx+DvAVIldRmut96/AE1JQYgN mUNVHno+3YEYVaNESGcpv43xMUr76BT2+TS51vsGgrucxBHYJX7TzjxjfRiqA/wX2v47EU2PHRg 8dgDBnS6hZaz4GQ== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:49 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10472 Reference our structure document when referencing this file, so that the reader can get further information on it. Signed-off-by: Antonin Godard --- documentation/ref-manual/terms.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index c210da4cb..7c2ae896f 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst @@ -198,8 +198,9 @@ universal, the list includes them just in case: Configuration files end with a ``.conf`` filename extension. There are multiple types of configuration files, such as: - - The :file:`conf/local.conf` configuration file in the :term:`Build - Directory` contains user-defined variables that affect every build. + - The :ref:`structure-build-conf-local.conf` configuration file in the + :term:`Build Directory` contains user-defined variables that affect + every build. - The :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto "distro" configuration variables used only when building with From patchwork Fri Sep 11 15:11:10 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97985 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 423D8C88E50 for ; Fri, 11 Sep 2026 15:11:49 +0000 (UTC) Received: from smtpout-02.galae.net (smtpout-02.galae.net [185.246.84.56]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.41825.1789139507227338724 for ; Fri, 11 Sep 2026 08:11:47 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=0ELCHh4Z; spf=pass (domain: bootlin.com, ip: 185.246.84.56, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-02.galae.net (Postfix) with ESMTPS id 97CFC1A01ED for ; Fri, 11 Sep 2026 15:11:45 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id 65E6C601DE for ; Fri, 11 Sep 2026 15:11:45 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 8640F11C7AFAC; Fri, 11 Sep 2026 17:11:39 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139500; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=36+4MqJkRMKtI/ZWuPWddYqovN7KC8A1ibBoXIOs0Yk=; b=0ELCHh4ZbZs1XQaOxNq1bx2M7MjtWAz0vBIgA4rMij3jCmeUU0fftI9Vsj3EkBgxxLhcPj ODdhG9W7a+YmtABtP17spNXoi0PKoz9lISQcvEF6wcSZuLlkHVWpR0XR6w9RrIJ/qIGShY H1pkhYgszPpC9YI3NHaeW2g/2ynodg2FYqvTCMlI1qH4PIdCjbGHviWEFeiro/toru8Oo7 PCn6IEFFhN6RCLv2+hMMEUpZHAdQne6NHqzCbILIS7Ry3kIsskumK8wvV/fuyaR59gw9GE 1e5nM/Y5hWH3wsctQdutr9x84ppIw5GU1b1cNSdsM+bRMX2FBRZbxBt/Ht46ww== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:10 +0200 Subject: [PATCH 4/8] ref-manual/classes.rst: buildstats: remove local.conf default value MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-4-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=1327; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=a2LTkj/VZg2NRrHsIRjCNi57KziRbHlWAxp9s/Mq7Q0=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoW2nhEFEkMRc1RqZUAFn8wJ7PRLdd3s4PdG qd9oV4+BE+JAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFgAKCRDRgEFAKaOo Nh5HD/9woXiN2t8uOnqHZwpsKA80Y4mgZmGsznrK86RbrLysFHUw+upSwzgoJx3fYznIF0E9HeU YrvbqkUnwVVlIAGvFpQ6pnsfx3oTFMGonq/sMHFqRFMKqHtwbDlxKPQt6KLhMxIOg2owU37XWY0 /dxnZ9KkOr0HC0pfW8sJC+gHS5nUrRulfkM1L5fboaQkNEgyGkVg4Nn7zbkLUi+EyVgIhBZaqJK alVZDsUIGiLVhppXAXBvdJCwVwxY3v5JJR0noFmu70Rf5UsE9YT1T5kYiHz3Mo/GA02+JEDHofH VsQKfucL8JS/1itzGMKDfgot//7DPBhI1a+vzysCjSpSzUxw7571Uv1+X3bYLIg2d+bfo6T/r2c soFoif47EF4nYf8x302wsTWSkXgygXpC6DAAEyGGkniL9U1WYuIMvwh7N1aBiE6GB8d1XHkSYnS TK7RXhMnFmgiXa6tgwlxRpCF6ZSZwggTnjR+Ur2os4Ro1ost/xeuowNOeeYJU2hTD9SUfC8zlNZ TCrIA3U6o/xocGpq0B576tltwUNJdY1HV4TYJE396m6tMYeJE1CNpPmbAxWp0oV5sAbzaJwzxb+ UOGsMiQB2TDFGSYTsiMZ2a9RD/eCRjHS8D9BJiBBKoTIy9CX65rycGYbKtlOc/qVzHygCqS/pBI BmnZq+CHp/V9lFg== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:49 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10473 The buildstats class is still part of the default templates of OE-Core but since the recommended way of setting things up is to now use bitbake-setup, that no longer the case. Remove the local.conf mention and keep an instruction on how to enable the class. Signed-off-by: Antonin Godard --- documentation/ref-manual/classes.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 631091f03..6b48cf693 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -288,11 +288,8 @@ to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using chart of the entire build process and can be useful for highlighting bottlenecks. -Collecting build statistics is enabled by default through the -:term:`USER_CLASSES` variable from your -``local.conf`` file. Consequently, you do not have to do anything to -enable the class. However, if you want to disable the class, simply -remove ":ref:`ref-classes-buildstats`" from the :term:`USER_CLASSES` list. +If you want to enable the class, you can add ":ref:`ref-classes-buildstats`" to +the :term:`USER_CLASSES` variable. .. _ref-classes-buildstats-summary: From patchwork Fri Sep 11 15:11:11 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97987 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 3CE49C88E50 for ; Fri, 11 Sep 2026 15:11:59 +0000 (UTC) Received: from smtpout-02.galae.net (smtpout-02.galae.net [185.246.84.56]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.41860.1789139512552826491 for ; Fri, 11 Sep 2026 08:11:52 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=ob4drZn+; spf=pass (domain: bootlin.com, ip: 185.246.84.56, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-02.galae.net (Postfix) with ESMTPS id D0D431A01ED for ; Fri, 11 Sep 2026 15:11:50 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id A083C601DE for ; Fri, 11 Sep 2026 15:11:50 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 31D6711C7AFBD; Fri, 11 Sep 2026 17:11:45 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139505; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=Fz0z7Xy2gWEQkdTpbQJpzMuScbS8vS6EOT6SWrLLeUA=; b=ob4drZn+BnFdbTLEPNoymyhtWyA9E6l/Re410gI2XgT3Y1qA3M+lJFCcV+jivSzC73Ro6p nDg+uAxQ0UzyCIrKOm23y67532E1/RJCgrW09zvTE/hzS0mwZgZrdy1TAkNOnp3P0qUPs+ OSaYVMFEtUfVeIACdfMY5f+2o8gY8cmMyNyALbqhDrWGEIzt/MYDn3KGKyFQ51OtA14D4k 61N12MhRsuXfZvg/6inZBxvtKsOXUBvY2tdlK00TtT6hKC4rBGniytxSmdJ9xCTkMsMlxF Bv+SOKKLLXgFq/8bVbVOnkitwF2fzsPDYeupTC+RYvn1ylYyaJihpLerAMsAKg== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:11 +0200 Subject: [PATCH 5/8] dev-manual/wic.rst: remove local.conf mentions MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-5-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=1630; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=z6mVX32MGSMlqjdkfGSDm9wSwu2BSyZuq2dWQAbBhco=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoXIzFuQQ4MI9Niti5C2JeLMnP1dHZJbBzlx mDSrjhRLV2JAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFwAKCRDRgEFAKaOo NukwEACqkK0Q4uBqrAwmbzcGpXHb7B7zcieu91MjFAc4cZJE2csqe6g470jZqDtrHI4Hh23GNrH CA4NP5T6orLXmoKEA50/yhO/S3pCXMaaJYuucjpxUzIRHExNcKcBoIkOlQWTfB7neEcd0JxKZWR D/O3cSxCq5crfOGxAzl9FoXk7jKVf8113khs5V5PkPjZnFZejuNgZu+snVeeP9RmZzlMHejigoQ tzP4HenBQQ413orV6GS7mgnvUgvPqdByzmqyn2BB+df139pNhsEMa4UzyMfkHEcacMdnLMens3Z BAMs0QJILHAxNRmjnGgJbKZUpJSf35TAeJsKWDtU1ciPWJ9qorh3UxF8+HVisSDJ4AcZfKBSk06 TWEwj8MkBXhPlRGkPmG5M0d3zJHBqwcufyX9uBY3Bt0TD19fcufzOku8qz5U280yET8s4nCNK1O 0zNh/3wIGtkHEdn0OaPuOfNczqOCwfyye7rBK/tdCx5CTUySYN2K0MNR9ofqQutMq09vMhPBD01 ez0+yOi44jBq2/tWBVdC02O6+DjbEP3vN2X00gCCqpUnv5hr/tj1UWXca8XUUGBXzDLs2oJYiuF 9d6N54ISer4BUa0A/gadzo+eD8YNFKcxCnAsXSqscvKd+NMY0PPaM1fk+/R49ES1RccFHT8KOyV +NT4TPhNoWzqt9A== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:59 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10474 These mentions are not needed for the examples, remove them. Signed-off-by: Antonin Godard --- documentation/dev-manual/wic.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/documentation/dev-manual/wic.rst b/documentation/dev-manual/wic.rst index bd3b5f697..c13655f87 100644 --- a/documentation/dev-manual/wic.rst +++ b/documentation/dev-manual/wic.rst @@ -530,9 +530,7 @@ file: The previous example shows the easiest way to create an image by running in cooked mode and supplying a kickstart file and the "-e" option to -point to the existing build artifacts. Your ``local.conf`` file needs to -have the :term:`MACHINE` variable set -to the machine you are using, which is "qemux86" in this example. +point to the existing build artifacts (the "qemux86" machine is used here). Once the image builds, the output provides image location, artifact use, and kickstart file information. @@ -608,8 +606,7 @@ untouched: Once the lines are changed, the example generates the ``directdisksdb-gpt`` image. The command points the process at the ``core-image-minimal`` artifacts for the Next Unit of -Computing (nuc) :term:`MACHINE` the -``local.conf``: +Computing (nuc) :term:`MACHINE`: .. code-block:: console @@ -680,7 +677,7 @@ default output directory, which is the current directory: For this example, :term:`MACHINE` did not have to be -specified in the ``local.conf`` file since the artifact is manually +specified since the artifact is manually specified. Using Wic to Manipulate an Image From patchwork Fri Sep 11 15:11:12 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97988 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 D08D7C88E58 for ; Fri, 11 Sep 2026 15:11:59 +0000 (UTC) Received: from smtpout-04.galae.net (smtpout-04.galae.net [185.171.202.116]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.41832.1789139517374584982 for ; Fri, 11 Sep 2026 08:11:57 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=BJEGf7gn; spf=pass (domain: bootlin.com, ip: 185.171.202.116, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-04.galae.net (Postfix) with ESMTPS id 12B08C63A0C for ; Fri, 11 Sep 2026 15:12:37 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id 40EDA601DE for ; Fri, 11 Sep 2026 15:11:55 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 7ACB511C7AFC1; Fri, 11 Sep 2026 17:11:50 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139510; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=+3zDB8Kk/9Ae12ewE9nlfG92PGb/UKSuHjDKssfn0qk=; b=BJEGf7gnTX4zBFejOo268UZDeIH/yF73uNdysOx8irjjBb+vgr/tUnypujI2/M3woseIrS eKogbu30DCRDxsDa31KH9A65PT4G26I8Pod6j0vjB2/gfO20oaRv3oGJ+JP0oSthTDZTSz 3HZ5s1NRbuXbFes8N+jSP76PLPQKvxiIdOH9vur5yRZrXvu2AKI9Ql392TbG6Ro7NG6p+e 51kUdwIliCvSdWNzohpfKZVxKgW0/uUDKjPsHwO9b9fBtaa+4dhunHFwtK3y0d8fEpI/sr EunRzWJHvb2s0bp60+AvdMQcDU6rwsKv3yxYFi0Vr6QabdYUgENuvlZ8p2XjhQ== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:12 +0200 Subject: [PATCH 6/8] ref-manual/variables.rst: GCCVERSION: replace local.conf and mention recipe existence MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-6-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=996; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=TVJ2BPfHb1W9q6jFn/PMe8PsJCYk1OAfaQa2eAEHjXM=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoXIS0YmxFexlk0Or5IDBJ6EWuPKUfNBa8BS BLgyWEk03qJAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFwAKCRDRgEFAKaOo NvJREACnuIhHUG7SBH32W1sAZJJFBX/MrZGNmhYBr7lj7Tb3d/mzCDvAf/iyduHJgWhLD6X6g05 MMe8xgYSYjXFIIY8qlNQixOYh40jKvsDLtXh7x0KeOjo7qOxSm8ToSgbquCzG7UF6DJiIYbmQ4g LUPjhKX4xKLr54EJtchYi+M2GL83IGa65LLqwtYlD8Mwvefnv9uAcCnVldVBTvg9rrQh3dJym57 7htB8D7At0NZy/wmSxuEB9idEt3BAVlcEFk7v3eYpesZITsFnAGeUwvBsnJ4i+L9gvzO8Fih/2/ Jeo9KhOBkF7VVJhyXSt8ELRZWq2mpHN+xiJvKoNMg4JMq/dFqZxZRQQ0vg5mFN9DWqGMw5JQSKs oW1/GKHcqyKV8S9BgMtJb92ra09NaaNijUxDbYGcHAgjDIZHBEXZQNovaZVeEcNUNUX3U4eSlrl K7Fr26BfJVkPHIxKBFZ8WlWMZbq+se8Rq3NDrQeKAgMRFYv6L/FbLMFbW7h4dX+Bpd0WQWOUnhk YbRaVc+UEQcaa4DeJkGQsyit4QXHopi4h4fNYahAAwqoE+NEGHX0yBEX/rAWl/sqymsjoUdCaeF nmR3s/Xi4/yC44RLHDytWqaD/vTsbMbnB67npvvpk+19BGjWsJ7iaYn/IYXtoGvTMDTxVe6dIhS QakKxh1pK7gzGdA== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:59 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10475 OE-Core only provides one version of gcc et. al. Mention that recipes with the overridden version should exist. Signed-off-by: Antonin Godard --- documentation/ref-manual/variables.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index f76e5ba4d..0df84b463 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -3834,7 +3834,8 @@ system and gives an overview of their function and contents. GCCVERSION ?= "8.%" You can override this value by setting it in a - configuration file such as the ``local.conf``. + :term:`configuration file` such as a distro configuration file, granted + that the recipes associated to this version of GCC exist in your workspace. :term:`GDB` The minimal command and arguments to run the GNU Debugger. From patchwork Fri Sep 11 15:11:13 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97989 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 0000EC88E45 for ; Fri, 11 Sep 2026 15:11:59 +0000 (UTC) Received: from smtpout-04.galae.net (smtpout-04.galae.net [185.171.202.116]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.41862.1789139518430466897 for ; Fri, 11 Sep 2026 08:11:59 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=dkim header.b=nx+ARZ18; spf=pass (domain: bootlin.com, ip: 185.171.202.116, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-04.galae.net (Postfix) with ESMTPS id 9E70EC63A0E for ; Fri, 11 Sep 2026 15:12:38 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id CD553601DE for ; Fri, 11 Sep 2026 15:11:56 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 18C2C11C7AFAC; Fri, 11 Sep 2026 17:11:55 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139515; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=BjWQl+RGzlgc3xoBRSMhlZBRgQTEjous4eHdcSrXRhM=; b=nx+ARZ18GjHMo5pc8rULCP6ybngD3QwUQuKSuzStH9HCY/N3tnJ3bTHKQiyyBzWe3gcMHk lev3goNFDBucL76x0GiD0LbPRWpwlkZaOQe7kA9+1rRcstwd49y2wQlkRaqlmbINj5yzQx lLksGvkBFDlAEKQKHdaOZSpf6mATbcrDC93Kh/csgvV1/ahOjaB+Uv3l052Oapy2jrEWtd KF5/3uH1cIF8Ncu5T/aYQVpdycfe4sJ2/8YnXag/qPt5yTXa+BQR/OmjpLKc2leudLSdkx YAjg5rqXRmN1ZIPrz6owZiCNB4cy/sH2F/VaJdqd6VZz1BkPmB6hhsnJIq8KUA== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:13 +0200 Subject: [PATCH 7/8] docs-wide: advise setting global changes in the proper place MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-7-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=60404; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=fHMisMg1kXEetE1ICH/DLZU1MP4WIrDV901y0Xwktk0=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoXumtooRsCtzeF2Gh1kUHJyOaH+QXJxg33F a5CBUiyRuiJAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaFwAKCRDRgEFAKaOo Nuu9D/938RnqrbjHhjoDJe8E+NQaxS/S8yh9d5Ee5PYk2MhSZ4CCbiW10+6Hno6lnmYSJpQWi+B eF16ne6wwr7zkAdhEDJeGszp2/J2AbXym7jBuH1oPkGVPnyAF+XqvlmQaljk8ZgqyT4fAVoHES7 Xmzn6rXaWLeyuhiEUPBCFFU2Pqg3RMNfIqUit2kZ7FRHRVhUBQvsvFGB/9n8Ngjko4hh11fXz46 VUKHvvzlG79W/WFU3wQmMh/GfgDm72UzM3uv9QLhFJ/HpAoSvkBplOmRHoTg9bMeKXtPqkJ/QaP RbrHohyMuK+IyRMmDOHGS3jAKNN4QjmgOtAtu0yUMnwUkRq2tki8VSGQtTNiZLG+luU/Ayb90yw RzSP/74baUTSDQPH76S0hfeDbQPkOkcNpAPedNk974+H/L57UsChneBrdrt1dhzdrc3+mTjzGqB O3MWw9CbShN6uz28et7PqVBJ+dcjnuvJ0Iw6O3UCdrxWVAzYSU9Hx1eGdBgMeKVr9SKqiyn66rf BkRkShOE6HNWaODgR23lqDKeaHeOuEjfzRFN/+TteTMNlIDDPBvnHG8twrPG8qnm8oaaFifo9JT w6sz0FCVTdi8pT51js1bs6hVqfGLWGf0zmx2DskSwhe/N49EbEh+IEsF32lixSKc3I+53PJJ5w1 CMhHe2cmfHzW7Iw== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:11:59 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10476 Go over occurrences of "local.conf" in the documentation and replace these kinds of suggestions by better recommendations, e.g. set this in your distro/machine configuration file. Signed-off-by: Antonin Godard --- documentation/dev-manual/bmaptool.rst | 5 +- documentation/dev-manual/build-quality.rst | 11 +- documentation/dev-manual/building.rst | 29 +++--- documentation/dev-manual/custom-distribution.rst | 6 +- documentation/dev-manual/customizing-images.rst | 9 +- documentation/dev-manual/debugging.rst | 2 +- documentation/dev-manual/device-manager.rst | 4 +- .../dev-manual/efficiently-fetching-sources.rst | 2 +- documentation/dev-manual/external-scm.rst | 2 +- documentation/dev-manual/external-toolchain.rst | 6 +- documentation/dev-manual/libraries.rst | 7 +- documentation/dev-manual/licenses.rst | 3 +- documentation/dev-manual/new-recipe.rst | 9 +- documentation/dev-manual/packages.rst | 16 +-- documentation/dev-manual/upgrading-recipes.rst | 8 +- documentation/dev-manual/wayland.rst | 4 +- documentation/kernel-dev/common.rst | 9 +- documentation/overview-manual/concepts.rst | 9 +- documentation/profile-manual/intro.rst | 4 +- documentation/profile-manual/usage.rst | 15 +-- documentation/ref-manual/classes.rst | 21 ++-- documentation/ref-manual/faq.rst | 8 +- documentation/ref-manual/images.rst | 5 +- documentation/ref-manual/system-requirements.rst | 2 +- documentation/ref-manual/variables.rst | 115 ++++++++++----------- documentation/sdk-manual/appendix-customizing.rst | 3 +- documentation/sdk-manual/appendix-obtain.rst | 15 ++- documentation/security-manual/read-only-rootfs.rst | 2 +- documentation/security-manual/securing-images.rst | 4 +- documentation/test-manual/reproducible-builds.rst | 6 +- documentation/test-manual/runtime-testing.rst | 2 +- .../transitioning-to-a-custom-environment.rst | 2 +- 32 files changed, 181 insertions(+), 164 deletions(-) diff --git a/documentation/dev-manual/bmaptool.rst b/documentation/dev-manual/bmaptool.rst index 29e7f0d2e..b145974c6 100644 --- a/documentation/dev-manual/bmaptool.rst +++ b/documentation/dev-manual/bmaptool.rst @@ -28,8 +28,9 @@ Following, is an example that shows how to flash a Wic image. Realize that while this example uses a Wic image, you can use `bmaptool` to flash any type of image. Use these steps to flash an image using `bmaptool`: -#. *Update your local.conf File:* You need to have the following set - in your ``local.conf`` file before building your image:: +#. *Update your image types:* You need to have the :term:`IMAGE_FSTYPES` + set in image recipe, distro :term:`configuration file` or + :ref:`structure-build-conf-local.conf` file before building your image:: IMAGE_FSTYPES += "wic wic.bmap" diff --git a/documentation/dev-manual/build-quality.rst b/documentation/dev-manual/build-quality.rst index e9b066c44..37d18efd2 100644 --- a/documentation/dev-manual/build-quality.rst +++ b/documentation/dev-manual/build-quality.rst @@ -35,8 +35,8 @@ Enabling and Disabling Build History Build history is disabled by default. To enable it, add the following :term:`INHERIT` statement and set the :term:`BUILDHISTORY_COMMIT` variable to -"1" at the end of your ``conf/local.conf`` file found in the -:term:`Build Directory`:: +"1" in a :term:`configuration file`, such as the +:ref:`structure-build-conf-local.conf` file:: INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "1" @@ -53,7 +53,7 @@ build output information and commit it as a single commit to a local during the build. You can disable build history by removing the previous statements from -your ``conf/local.conf`` file. +your :term:`configuration file`. Understanding What the Build History Contains ============================================= @@ -134,7 +134,7 @@ You can use the ``buildhistory-collect-srcrevs`` command with the ``-a`` option to collect the stored :term:`SRCREV` values from build history and report them in a format suitable for use in global configuration (e.g., -``local.conf`` or a distro include file) to override floating +a distro include :term:`configuration file`) to override floating :term:`AUTOREV` values to a fixed set of revisions. Here is some example output from this command:: @@ -260,8 +260,7 @@ dependency graphs, so you can see why something was pulled into the image. If you are just interested in this information and not interested in collecting specific package or SDK information, you can enable writing only image information without any history by adding the -following to your ``conf/local.conf`` file found in the -:term:`Build Directory`:: +following to a :term:`configuration file`:: INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "0" diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index 60cb22785..705bad6ed 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst @@ -112,8 +112,9 @@ Follow these steps to create an :term:`Initramfs` image: #. *Decide if You Need to Bundle the Initramfs Image Into the Kernel Image:* If you want the :term:`Initramfs` image that is built to be bundled in with the kernel image, set the :term:`INITRAMFS_IMAGE_BUNDLE` - variable to ``"1"`` in your ``local.conf`` configuration file and set the - :term:`INITRAMFS_IMAGE` variable in the recipe that builds the kernel image. + variable to ``"1"`` in a :term:`configuration file`, such as a machine + :term:`configuration file`, and set the :term:`INITRAMFS_IMAGE` variable in + the recipe that builds the kernel image. Setting the :term:`INITRAMFS_IMAGE_BUNDLE` flag causes the :term:`Initramfs` image to be unpacked into the ``${B}/usr/`` directory. The unpacked @@ -236,7 +237,7 @@ To achieve this, you need to perform some additional steps: TCLIBC = "musl" #. *Set additional Initramfs variables on your main configuration:* - Additionally, on your main configuration (``local.conf``) you need to set the + Additionally, in your :term:`configuration file` you need to set the variables:: INITRAMFS_MULTICONFIG = "initramfscfg" @@ -328,10 +329,11 @@ your own distribution that are likely modeled after ``poky-tiny``. .. note:: - To use ``poky-tiny`` in your build, set the :term:`DISTRO` variable in your - ``local.conf`` file to "poky-tiny" as described in the - ":ref:`dev-manual/custom-distribution:creating your own distribution`" - section. + To use ``poky-tiny`` in your build, set the + :ref:`ref-fragments-builtin-core-distro` fragment to "poky-tiny" as described in the + :ref:`ref-bitbake-config-build-enable-fragment` section, or set the + :term:`DISTRO` variable to "poky-tiny" in the + :ref:`structure-build-conf-local.conf` file. Understanding some memory concepts will help you reduce the system size. Memory consists of static, dynamic, and temporary memory. Static memory @@ -414,9 +416,8 @@ minimal impact on the feature set. For example, you might not need a VGA display. Or, you might be able to get by with ``devtmpfs`` and ``mdev`` instead of ``udev``. -Use your ``local.conf`` file to make changes. For example, to eliminate -``udev`` and ``glib``, set the following in the local configuration -file:: +Use your distro :term:`configuration file` to make such changes. For example, to +eliminate ``udev`` and ``glib``, set the following:: VIRTUAL-RUNTIME_dev_manager = "" @@ -792,10 +793,10 @@ any machine and at any time. Follow these steps to build your target using the files in the downloads directory: -#. *Using Local Files Only:* Inside your ``local.conf`` file, add the - :term:`SOURCE_MIRROR_URL` variable, inherit the - :ref:`ref-classes-own-mirrors` class, and add the - :term:`BB_NO_NETWORK` variable to your ``local.conf``:: +#. *Using Local Files Only:* Inside your ``local.conf`` or distro + :term:`configuration file`, add the :term:`SOURCE_MIRROR_URL` variable, + inherit the :ref:`ref-classes-own-mirrors` class, and add the + :term:`BB_NO_NETWORK` variable:: SOURCE_MIRROR_URL ?= "file:///home/your-download-dir/" INHERIT += "own-mirrors" diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst index 4dafd2725..365bfa8f7 100644 --- a/documentation/dev-manual/custom-distribution.rst +++ b/documentation/dev-manual/custom-distribution.rst @@ -40,7 +40,8 @@ layer. The following steps provide some more detail: .. note:: The :term:`DISTRO` variable in your ``local.conf`` file determines the - name of your distribution. + name of your distribution. You can also use the + :ref:`ref-fragments-builtin-core-distro` configuration fragment. You can split out parts of your configuration file into include files and then "require" them from within your distribution configuration @@ -91,6 +92,9 @@ layer. The following steps provide some more detail: DISTRO = "mydistro" + You can also set the :ref:`ref-fragments-builtin-core-distro` configuration + fragment from the command-line. + - *Add more to the layer if necessary:* Use your layer to hold other information needed for the distribution: diff --git a/documentation/dev-manual/customizing-images.rst b/documentation/dev-manual/customizing-images.rst index 6eed9ef56..9a345c8bb 100644 --- a/documentation/dev-manual/customizing-images.rst +++ b/documentation/dev-manual/customizing-images.rst @@ -56,7 +56,8 @@ high-level image features by using the variables. Although the functions for both variables are nearly equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your -``local.conf`` file, which is found in the :term:`Build Directory`. +``local.conf`` for temporary changes (which is found in the :term:`Build +Directory`) and a distro :term:`configuration file` for permanent changes. To understand how these features work, the best reference is :ref:`meta/classes-recipe/image.bbclass `. @@ -90,9 +91,9 @@ image does not contain an SSH server. You can customize your image and change these defaults. Edit the :term:`IMAGE_FEATURES` variable in your recipe or use the -:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file so that it -configures the image you are working with to include -``ssh-server-dropbear`` or ``ssh-server-openssh``. +:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file (or distro +:term:`configuration file`) so that it configures the image you are working with +to include ``ssh-server-dropbear`` or ``ssh-server-openssh``. .. note:: diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 3afc17ad4..1718b90d2 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -943,7 +943,7 @@ To run a ``debuginfod`` server, you need to do the following: (it already is in :term:`OpenEmbedded-Core (OE-Core)` defaults and :term:`Poky` reference distribution). - If not, set in your distro config file or in ``local.conf``:: + If not, set in your distro :term:`configuration file` or in ``local.conf``:: DISTRO_FEATURES:append = " debuginfod" diff --git a/documentation/dev-manual/device-manager.rst b/documentation/dev-manual/device-manager.rst index 49fc785fe..757b23d1a 100644 --- a/documentation/dev-manual/device-manager.rst +++ b/documentation/dev-manual/device-manager.rst @@ -31,7 +31,7 @@ The content of the resulting ``/dev`` directory is defined in a Device Table file. The :term:`IMAGE_DEVICE_TABLES` variable defines the Device Table to use and should be set in the -machine or distro configuration file. Alternatively, you can set this +machine or distro :term:`configuration file`. Alternatively, you can set this variable in your ``local.conf`` configuration file. If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default @@ -63,7 +63,7 @@ permissions ``0600``. To have more control over the device nodes, you can use a device manager like ``udev`` or ``busybox-mdev``. You choose the device manager by defining the :term:`VIRTUAL-RUNTIME_dev_manager ` variable in your machine -or distro configuration file. Alternatively, you can set this variable in +or distro :term:`configuration file`. Alternatively, you can set this variable in your ``local.conf`` configuration file:: VIRTUAL-RUNTIME_dev_manager = "udev" diff --git a/documentation/dev-manual/efficiently-fetching-sources.rst b/documentation/dev-manual/efficiently-fetching-sources.rst index a3366226c..ab72e8dd2 100644 --- a/documentation/dev-manual/efficiently-fetching-sources.rst +++ b/documentation/dev-manual/efficiently-fetching-sources.rst @@ -26,7 +26,7 @@ adding statements to your configuration file so that the build process checks local directories first for existing tarballs before checking the Internet. -Here is an efficient way to set it up in your ``local.conf`` file:: +Here is an efficient way to set it up in a :term:`configuration file`:: SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/" INHERIT += "own-mirrors" diff --git a/documentation/dev-manual/external-scm.rst b/documentation/dev-manual/external-scm.rst index e7ab8a4c6..bab5055f7 100644 --- a/documentation/dev-manual/external-scm.rst +++ b/documentation/dev-manual/external-scm.rst @@ -21,7 +21,7 @@ Here is an example:: during the packaging phase. Then, you can add the following to your -``local.conf``:: +:ref:`structure-build-conf-local.conf` file:: SRCREV:pn-PN = "${AUTOREV}" diff --git a/documentation/dev-manual/external-toolchain.rst b/documentation/dev-manual/external-toolchain.rst index 29459ea12..ea196b67a 100644 --- a/documentation/dev-manual/external-toolchain.rst +++ b/documentation/dev-manual/external-toolchain.rst @@ -15,8 +15,10 @@ follows: ``bblayers.conf`` file through the :term:`BBLAYERS` variable. -- Set the :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file - to the location in which you installed the toolchain. +- Set the :term:`EXTERNAL_TOOLCHAIN` variable in your + :ref:`structure-build-conf-local.conf` file + to the location in which you installed the toolchain (or in your distro + :term:`configuration file`). The toolchain configuration is very flexible and customizable. It is primarily controlled with the :term:`TCMODE` variable. This variable diff --git a/documentation/dev-manual/libraries.rst b/documentation/dev-manual/libraries.rst index 160734729..d7b9f0cfc 100644 --- a/documentation/dev-manual/libraries.rst +++ b/documentation/dev-manual/libraries.rst @@ -116,9 +116,10 @@ Using Multilib -------------- After you have set up the recipes, you need to define the actual -combination of multiple libraries you want to build. You accomplish this -through your ``local.conf`` configuration file in the -:term:`Build Directory`. An example configuration would be as follows:: +combination of multiple libraries you want to build. You can accomplish this +through your :ref:`structure-build-conf-local.conf` configuration file in the +:term:`Build Directory`, or a custom machine :term:`configuration file`. An +example configuration would be as follows:: MACHINE = "qemux86-64" require conf/multilib.conf diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst index 774b5db23..b5091087e 100644 --- a/documentation/dev-manual/licenses.rst +++ b/documentation/dev-manual/licenses.rst @@ -417,7 +417,8 @@ One requirement that is often overlooked is inclusion of license text. This requirement also needs to be dealt with prior to generating the final image. Some licenses require the license text to accompany the binary. You can achieve this by adding the following to your -``local.conf`` file:: +:ref:`structure-build-conf-local.conf` file or distro :term:`configuration +file`:: COPY_LIC_MANIFEST = "1" COPY_LIC_DIRS = "1" diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst index 3f360597f..f43fc2be3 100644 --- a/documentation/dev-manual/new-recipe.rst +++ b/documentation/dev-manual/new-recipe.rst @@ -395,8 +395,8 @@ Limiting the Number of Parallel Connections Some users are behind firewalls or use servers where the number of parallel connections is limited. In such cases, you can limit the number of fetch -tasks being run in parallel by adding the following to your ``local.conf`` -file:: +tasks being run in parallel by adding the following to your +:ref:`structure-build-conf-local.conf` file:: do_fetch[number_threads] = "4" @@ -1549,8 +1549,9 @@ in the BitBake User Manual. assign a value to a variable, but only when the variable is currently unset. Use the question mark followed by the equal sign (``?=``) to make a "soft" assignment used for conditional assignment. Typically, - "soft" assignments are used in the ``local.conf`` file for variables - that are allowed to come through from the external environment. + "soft" assignments are used in :term:`configuration files ` for variables that are allowed to come through from the external + environment. Here is an example where ``VAR1`` is set to "New value" if it is currently empty. However, if ``VAR1`` has already been set, it diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst index c75584c93..95488c761 100644 --- a/documentation/dev-manual/packages.rst +++ b/documentation/dev-manual/packages.rst @@ -33,7 +33,7 @@ or to not install a package at all. The following list introduces variables you can use to prevent packages from being installed into your image. Each of these variables only works with IPK and RPM package types, not for Debian packages. -Also, you can use these variables from your ``local.conf`` file +Also, you can use these variables in a distro :term:`configuration file` or attach them to a specific image recipe by using a recipe name override. For more detail on the variables, see the descriptions in the Yocto Project Reference Manual's glossary chapter. @@ -179,14 +179,16 @@ you need to start the PR Service using the ``bitbake-prserv`` command:: bitbake-prserv --host ip --port port --start In addition to -hand-starting the service, you need to update the ``local.conf`` file of +hand-starting the service, you need to update the +:ref:`structure-build-conf-local.conf` file of each building system as described earlier so each system points to the server and port. It is also recommended you use build history, which adds some sanity checks to binary package versions, in conjunction with the server that is running the PR Service. To enable build history, add the following to -each building system's ``local.conf`` file:: +each building system's :ref:`structure-build-conf-local.conf` file (or set this +in your distro :term:`configuration file`):: # It is recommended to activate "buildhistory" for testing the PR service INHERIT += "buildhistory" @@ -558,10 +560,8 @@ to use. In your configuration, you use the :term:`PACKAGE_CLASSES` variable to specify the format: -#. Open the ``local.conf`` file inside your :term:`Build Directory` (e.g. - ``bitbake-builds/build/conf/local.conf``). - -#. Select the desired package format as follows:: +#. Select the desired package format as follows from your +:ref:`structure-build-conf-local.conf` or distro :term:`configuration file`:: PACKAGE_CLASSES ?= "package_packageformat" @@ -878,7 +878,7 @@ signed package feeds for IPK and RPM packages. The steps you need to take to enable signed package feed use are similar to the steps used to sign RPM packages. You must define the following in -your ``local.config`` or ``distro.config`` file:: +your :ref:`structure-build-conf-local.conf` or distro :term:`configuration file`:: INHERIT += "sign_package_feed" PACKAGE_FEED_GPG_NAME = "key_name" diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst index 3a974fdfc..5c4e7df5d 100644 --- a/documentation/dev-manual/upgrading-recipes.rst +++ b/documentation/dev-manual/upgrading-recipes.rst @@ -115,14 +115,15 @@ The following steps describe how to set up the AUH utility: - If you want to enable testing through the :ref:`ref-classes-testimage` class, which is optional, you need to have the following set in - your ``conf/local.conf`` file:: + your :ref:`structure-build-conf-local.conf` file:: IMAGE_CLASSES += "testimage" .. note:: If your distro does not enable by default ptest, which :term:`Poky` - does, you need the following in your ``local.conf`` file:: + does, you need the following in your + :ref:`structure-build-conf-local.conf` file:: DISTRO_FEATURES:append = " ptest" @@ -139,7 +140,8 @@ The following steps describe how to set up the AUH utility: :yocto_git:`AUH source repository `. Read through the sample file and make configurations as needed. For - example, if you enabled build history in your ``local.conf`` as + example, if you enabled build history in your + :ref:`structure-build-conf-local.conf` as described earlier, you must enable it in ``upgrade-helper.conf``. Also, if you are using the default ``maintainers.inc`` file supplied diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst index 18d1bfb0a..5e333b626 100644 --- a/documentation/dev-manual/wayland.rst +++ b/documentation/dev-manual/wayland.rst @@ -48,7 +48,7 @@ Wayland with Kernel Mode Setting (`KMS `__) support, include the "wayland" flag in the :term:`DISTRO_FEATURES` -statement in your ``local.conf`` file:: +statement in your distro :term:`configuration file`:: DISTRO_FEATURES:append = " wayland" @@ -63,7 +63,7 @@ Installing Wayland and Weston To install the Wayland feature into an image, you must include the following :term:`CORE_IMAGE_EXTRA_INSTALL` -statement in your ``local.conf`` file:: +statement in your distro :term:`configuration file`:: CORE_IMAGE_EXTRA_INSTALL += "wayland weston" diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst index d9b4478d5..af06e8dcd 100644 --- a/documentation/kernel-dev/common.rst +++ b/documentation/kernel-dev/common.rst @@ -51,7 +51,8 @@ section: #. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is set to "qemux86-64", which is fine if you are building for the QEMU emulator in 64-bit mode. However, if you are not, you need to set the - :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file + :term:`MACHINE` variable appropriately in your + :ref:`structure-build-conf-local.conf` file found in the :term:`Build Directory` (i.e. ``bitbake-builds/build`` in this example). Also, since you are preparing to work on the kernel image, you need @@ -60,7 +61,8 @@ section: In this example we wish to build for qemux86 so we must set the :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``:: + As described we do this by appending to + :ref:`structure-build-conf-local.conf`:: MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" @@ -156,7 +158,8 @@ section: In this example we wish to build for qemux86 so we must set the :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``:: + As described we do this by appending to + :ref:`structure-build-conf-local.conf`:: MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index d4530e97f..e0e3c0398 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst @@ -122,12 +122,12 @@ Reference Manual provides details about classes and how to use them. Configurations -------------- -The configuration files (``.conf``) define various configuration +The :term:`configuration files ` (``.conf``) define various configuration variables that govern the OpenEmbedded build process. These files fall into several areas that define machine configuration options, distribution configuration options, compiler tuning options, general common configuration options, and user configuration options in -``conf/local.conf``, which is found in the :term:`Build Directory`. +:ref:`structure-build-conf-local.conf`, which is found in the :term:`Build Directory`. Layers @@ -228,8 +228,9 @@ the Build Environment>`, you can specify which directory will be the Setting up the build environment creates a :term:`Build Directory` if one does not already exist. BitBake uses the :term:`Build Directory` for all its work during builds. The Build Directory has a ``conf`` subdirectory -that contains default versions of your ``local.conf`` and ``bblayers.conf`` -configuration files. These default :term:`configuration files `. These default :term:`configuration files ` are created only if they do not already exist in the :term:`Build Directory` at the time you source the build environment setup script. diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst index 317912552..6241dffcb 100644 --- a/documentation/profile-manual/intro.rst +++ b/documentation/profile-manual/intro.rst @@ -32,7 +32,9 @@ General Setup ============= Most of the tools are available only in ``sdk`` images or in images built -after adding ``tools-profile`` to your ``local.conf`` file. So, in order to be able +after adding ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` variable. + +So, in order to be able to access all of the tools described here, you can build and boot an ``sdk`` image, perhaps one of:: diff --git a/documentation/profile-manual/usage.rst b/documentation/profile-manual/usage.rst index f8de6848e..dc34fa36c 100644 --- a/documentation/profile-manual/usage.rst +++ b/documentation/profile-manual/usage.rst @@ -48,7 +48,7 @@ For this section, we'll assume you've already performed the basic setup outlined in the ":ref:`profile-manual/intro:General Setup`" section. In particular, you'll get the most mileage out of perf if you profile an -image built with the following in your ``local.conf`` file:: +image built with the following in a :term:`configuration file`:: INHIBIT_PACKAGE_STRIP = "1" @@ -296,7 +296,7 @@ The problem is that perf can't find the symbol information for the ``busybox`` binary, which is actually stripped out by the Yocto build system. -One way around that is to put the following in your ``local.conf`` file +One way around that is to put the following in a :term:`configuration file` when you build the image:: INHIBIT_PACKAGE_STRIP = "1" @@ -306,13 +306,14 @@ what can we do to get perf to resolve the symbols? Basically we need to install the debugging information for the BusyBox package. To generate the debug info for the packages in the image, we can add -``dbg-pkgs`` to :term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example:: +``dbg-pkgs`` to :term:`EXTRA_IMAGE_FEATURES` in +:ref:`structure-build-conf-local.conf`. For example:: EXTRA_IMAGE_FEATURES:append = " dbg-pkgs" Additionally, in order to generate the type of debugging information that perf understands, we also need to set :term:`PACKAGE_DEBUG_SPLIT_STYLE` -in the ``local.conf`` file:: +in a :term:`configuration file`:: PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' @@ -1867,8 +1868,8 @@ Practically speaking, that means you need to do the following: $ bitbake core-image-sato-sdk - Or build a non-SDK image but include the profiling tools - (edit ``local.conf`` and add ``tools-profile`` to the end of - :term:`EXTRA_IMAGE_FEATURES` variable):: + (add ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` + variable):: $ bitbake core-image-sato @@ -1894,7 +1895,7 @@ section of this manual, and boot the resulting target image. .. note:: If you have a :term:`Build Directory` containing multiple machines, you need - to have the :term:`MACHINE` you're connecting to selected in ``local.conf``, and + to have the :term:`MACHINE` you're connecting to selected, and the kernel in that machine's :term:`Build Directory` must match the kernel on the booted system exactly, or you'll get the above ``crosstap`` message when you try to call a script. diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 6b48cf693..ec768b755 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -2010,9 +2010,9 @@ code specific to particular package types resides in these package-specific classes: :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`, :ref:`ref-classes-package_ipk`. -You can control the list of resulting package formats by using the -:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf`` -configuration file, which is located in the :term:`Build Directory`. +You can control the list of resulting package formats by setting the +:term:`PACKAGE_CLASSES` variable in your :ref:`structure-build-conf-local.conf` +file or distro :term:`configuration file`. When defining the variable, you can specify one or more package types. Since images are generated from packages, a packaging class is needed to enable image generation. The first class listed in this variable is @@ -2065,7 +2065,7 @@ packages are written out in a ``.deb`` file format to the This class inherits the :ref:`ref-classes-package` class and is enabled through the :term:`PACKAGE_CLASSES` -variable in the ``local.conf`` file. +variable. .. _ref-classes-package_ipk: @@ -2079,7 +2079,7 @@ are written out in a ``.ipk`` file format to the This class inherits the :ref:`ref-classes-package` class and is enabled through the :term:`PACKAGE_CLASSES` -variable in the ``local.conf`` file. +variable. .. _ref-classes-package_rpm: @@ -2093,7 +2093,7 @@ are written out in a ``.rpm`` file format to the This class inherits the :ref:`ref-classes-package` class and is enabled through the :term:`PACKAGE_CLASSES` -variable in the ``local.conf`` file. +variable. .. _ref-classes-packagedata: @@ -2616,7 +2616,8 @@ recipe are no longer needed. However, by default, the build system preserves these files for inspection and possible debugging purposes. If you would rather have these files deleted to save disk space as the build progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to -your ``local.conf`` file, which is found in the :term:`Build Directory`:: +your :ref:`structure-build-conf-local.conf` file, which is found in the +:term:`Build Directory`:: INHERIT += "rm_work" @@ -2625,7 +2626,8 @@ recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your changes to the source being lost. To exclude some recipes from having their work directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, -which can also be set in your ``local.conf`` file. Here is an example:: +which can also be set in your :ref:`structure-build-conf-local.conf` file. Here +is an example:: RM_WORK_EXCLUDE += "busybox glibc" @@ -3849,7 +3851,8 @@ using the Vala programming language. The :ref:`ref-classes-vex` class is used to generate metadata needed by external tools to check for vulnerabilities, for example CVEs. -In order to use this class, inherit the class in the ``local.conf`` file and it +In order to use this class, inherit the class in your +:ref:`structure-build-conf-local.conf` or distro :term:`configuration file` and it will add the ``generate_vex`` task for every recipe:: INHERIT += "vex" diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index 374ecf8e8..f8e047e27 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst @@ -119,8 +119,8 @@ of other mirrors including the Yocto Project source mirror if those fail. As an example, you could add a specific server for the build system to -attempt before any others by adding something like the following to the -``local.conf`` configuration file:: +attempt before any others by adding something like the following to +a :term:`configuration file`:: PREMIRRORS:prepend = "\ git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ @@ -159,8 +159,8 @@ technique is useful if you want to create a mirror server. If not, however, the technique can simply waste time during the build. Finally, consider an example where you are behind an HTTP-only firewall. -You could make the following changes to the ``local.conf`` configuration -file as long as the :term:`PREMIRRORS` server is current:: +You could make the following changes to a :term:`configuration +file` as long as the :term:`PREMIRRORS` server is current:: PREMIRRORS:prepend = "\ git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ diff --git a/documentation/ref-manual/images.rst b/documentation/ref-manual/images.rst index 37694d11f..8b287505c 100644 --- a/documentation/ref-manual/images.rst +++ b/documentation/ref-manual/images.rst @@ -21,8 +21,9 @@ image you want. INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0*" - Alternatively, you can adjust ``local.conf`` file, repeating and adjusting the line - for all images where the license restriction must apply: + Alternatively, you can adjust your distro :term:`configuration file`, + repeating and adjusting the line for all images where the license restriction + must apply: INCOMPATIBLE_LICENSE:pn-your-image-name = "GPL-3.0* LGPL-3.0*" diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst index 8317452b2..052cd4b0d 100644 --- a/documentation/ref-manual/system-requirements.rst +++ b/documentation/ref-manual/system-requirements.rst @@ -591,7 +591,7 @@ installer: .. note:: - The :term:`SDKMACHINE` variable in your ``local.conf`` file determines + The :term:`SDKMACHINE` variable determines whether you build tools for a 32-bit or 64-bit system. Once the build completes, you can find the ``.sh`` file that installs diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 0df84b463..c04b24ce0 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -288,11 +288,10 @@ system and gives an overview of their function and contents. BAD_RECOMMENDATIONS = "package_name package_name package_name ..." - You can set this variable globally in your ``local.conf`` file or you - can attach it to a specific image recipe by using the recipe name - override:: + You can set this variable globally in a :term:`configuration file` or you + can specify it in an image recipe directly:: - BAD_RECOMMENDATIONS:pn-target_image = "package_name" + BAD_RECOMMENDATIONS = "package_name" It is important to realize that if you choose to not install packages using this variable and some other packages are dependent on them @@ -572,8 +571,7 @@ system and gives an overview of their function and contents. BB_GENERATE_MIRROR_TARBALLS = "1" - Set this variable in your - ``local.conf`` file in the :term:`Build Directory`. + Set this variable in a :term:`configuration file`. Once you have the tarballs containing your source files, you can clean up your :term:`DL_DIR` directory by deleting any Git or other @@ -942,7 +940,8 @@ system and gives an overview of their function and contents. :term:`BBMULTICONFIG` Specifies each additional separate configuration when you are building targets with multiple configurations. Use this variable in - your ``conf/local.conf`` configuration file. Specify a + your :ref:`structure-build-conf-local.conf` configuration file for local testing, or in a + machine :term:`configuration file`. Specify a multiconfig name for each configuration file you are using. For example, the following line specifies three configuration files:: @@ -1731,8 +1730,8 @@ system and gives an overview of their function and contents. "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). :term:`CONF_VERSION` - Tracks the version of the local configuration file (i.e. - ``local.conf``). The value for :term:`CONF_VERSION` increments each time + Tracks the version of the local configuration file (:ref:`structure-build-conf-local.conf`). + The value for :term:`CONF_VERSION` increments each time ``build/conf/`` compatibility changes. :term:`CONFFILES` @@ -1968,8 +1967,9 @@ system and gives an overview of their function and contents. :term:`CORE_IMAGE_EXTRA_INSTALL` Specifies the list of packages to be added to the image. You should - only set this variable in the ``local.conf`` configuration file found - in the :term:`Build Directory`. + set this variable in the :ref:`structure-build-conf-local.conf` configuration file found + in the :term:`Build Directory`, or in a distro :term:`configuration file` + if your distro should always include this list of package. This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer supported. @@ -2720,8 +2720,8 @@ system and gives an overview of their function and contents. ``${``\ :term:`LOG_DIR`\ ``}/error-report``. You can set :term:`ERR_REPORT_DIR` to the path you want the error - reporting tool to store the debug files as follows in your - ``local.conf`` file:: + reporting tool to store the debug files as follows in a + :term:`configuration file`:: ERR_REPORT_DIR = "path" @@ -2912,9 +2912,10 @@ system and gives an overview of their function and contents. A list of additional features to include in an image. When listing more than one feature, separate them with a space. - Typically, you configure this variable in your ``local.conf`` file, - which is found in the :term:`Build Directory`. Although you can use this - variable from within a recipe, best practices dictate that you do not. + Typically, you configure this variable in your :ref:`structure-build-conf-local.conf` file for + local modifications, or in your distro :term:`configuration file` for + permanent changes. Although you can use this variable from within a + recipe, best practices dictate that you do not. .. note:: @@ -3131,7 +3132,7 @@ system and gives an overview of their function and contents. Points to the base URL of the server and location within the document-root that provides the metadata and packages required by OPKG to support runtime package management of IPK packages. You set - this variable in your ``local.conf`` file. + this variable in a :term:`configuration file`. Consider the following example:: @@ -3867,7 +3868,9 @@ system and gives an overview of their function and contents. If you specifically remove the locale ``en_US.UTF-8``, you must set :term:`IMAGE_LINGUAS` appropriately. - You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file. + You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file for + local testing or in your distro :term:`configuration file`. + By default, all locales are generated:: GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" @@ -3963,7 +3966,7 @@ system and gives an overview of their function and contents. :term:`GRUB_GFXSERIAL` Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu. Set this variable to "1" in your - ``local.conf`` or distribution configuration file to enable graphics + :ref:`structure-build-conf-local.conf` or distribution :term:`configuration file` to enable graphics and serial in the menu. See the :ref:`ref-classes-grub-efi` class for more @@ -5448,7 +5451,7 @@ system and gives an overview of their function and contents. building and configuring the kernel stops with an error. You can turn these errors into warnings by setting the - following in ``conf/local.conf``:: + following in a :term:`configuration file`:: KERNEL_DANGLING_FEATURES_WARN_ONLY = "1" @@ -6583,11 +6586,10 @@ system and gives an overview of their function and contents. NO_RECOMMENDATIONS = "1" - You can set this variable globally in your ``local.conf`` file or you - can attach it to a specific image recipe by using the recipe name - override:: + You can set this variable globally in a :term:`configuration file` or you + can specify it in an image recipe directly:: - NO_RECOMMENDATIONS:pn-target_image = "1" + NO_RECOMMENDATIONS = "1" It is important to realize that if you choose to not install packages using this variable and some other packages are dependent on them @@ -6944,9 +6946,7 @@ system and gives an overview of their function and contents. included in the default package. :term:`PACKAGE_CLASSES` - This variable, which is set in the ``local.conf`` configuration file - found in the ``conf`` folder of the - :term:`Build Directory`, specifies the package manager the + This variable specifies the package manager the OpenEmbedded build system uses when packaging data. You can provide one or more of the following arguments for the @@ -6957,7 +6957,7 @@ system and gives an overview of their function and contents. The build system uses only the first argument in the list as the package manager when creating your image or SDK. However, packages will be created using any additional packaging classes you specify. - For example, if you use the following in your ``local.conf`` file:: + For example, if you use the following in your distro :term:`configuration file`:: PACKAGE_CLASSES ?= "package_ipk" @@ -7018,11 +7018,10 @@ system and gives an overview of their function and contents. PACKAGE_EXCLUDE = "package_name package_name package_name ..." - You can set this variable globally in your ``local.conf`` file or you - can attach it to a specific image recipe by using the recipe name - override:: + You can set this variable globally in a :term:`configuration file` or you + can specify it in an image recipe directly:: - PACKAGE_EXCLUDE:pn-target_image = "package_name" + PACKAGE_EXCLUDE = "package_name" If you choose to not install a package using this variable and some other package is dependent on it (i.e. listed in a recipe's @@ -7317,8 +7316,8 @@ system and gives an overview of their function and contents. PACKAGECONFIG:append = " f4" - *Configuration file:* This method is identical to changing the - block through an append file except you edit your ``local.conf`` - or ``mydistro.conf`` file. As with append files previously + block through an append file except you edit your :ref:`structure-build-conf-local.conf` + or distro :term:`configuration file`. As with append files previously described, you can either completely override the variable:: PACKAGECONFIG:pn-recipename = "f4 f5" @@ -8009,8 +8008,8 @@ system and gives an overview of their function and contents. :term:`PRSERV_HOST` The network based :term:`PR` service host and port. - The ``conf/templates/default/local.conf.sample.extended`` configuration - file in :yocto_git:`meta-poky ` shows how the + The :oecore_path:`meta/conf/templates/default/local.conf.sample.extended` + configuration file in :term:`OpenEmbedded-Core (OE-Core)` shows how the :term:`PRSERV_HOST` variable is set:: PRSERV_HOST = "localhost:0" @@ -9371,9 +9370,8 @@ system and gives an overview of their function and contents. package. Removal of these files is required for packages containing prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. - To enable file removal, set the variable to "1" in your - ``conf/local.conf`` configuration file in your: - :term:`Build Directory`:: + To enable file removal, set the variable to "1" in a :term:`configuration + file`:: SKIP_FILEDEPS = "1" @@ -9437,7 +9435,7 @@ system and gives an overview of their function and contents. :term:`SOURCE_MIRROR_FETCH` When you are fetching files to create a mirror of sources (i.e. creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in - your ``local.conf`` configuration file ensures the source for all + a :term:`configuration file` ensures the source for all recipes are fetched regardless of whether or not a recipe is compatible with the configuration. A recipe is considered incompatible with the currently configured machine when either or @@ -10978,9 +10976,10 @@ system and gives an overview of their function and contents. :term:`TEMPLATECONF` Specifies the directory used by the build system to find templates - from which to build the ``bblayers.conf`` and ``local.conf`` files. + from which to build the :ref:`structure-build-conf-bblayers.conf` and + :ref:`structure-build-conf-local.conf` files. Use this variable if you wish to customize such files, and the default - BitBake targets shown when sourcing the ``oe-init-build-env`` script. + BitBake targets shown when sourcing the :ref:`structure-core-script` script. For details, see the :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory` @@ -11034,8 +11033,7 @@ system and gives an overview of their function and contents. The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image. The default timeout period to allow the boot process to reach the login prompt is 500 - seconds. You can specify a different value in the ``local.conf`` - file. + seconds. You can specify a different value in a :term:`configuration file`. For more information on testing images, see the ":ref:`test-manual/runtime-testing:performing automated runtime testing`" @@ -11184,10 +11182,9 @@ system and gives an overview of their function and contents. These tests are written in Python making use of the ``unittest`` module, and the majority of them run commands on the target system - over ``ssh``. You can set this variable to "1" in your ``local.conf`` - file in the :term:`Build Directory` to have the - OpenEmbedded build system automatically run these tests after an - image successfully builds: + over ``ssh``. You can set this variable to "1" in a :term:`configuration + file` to have the OpenEmbedded build system automatically run these tests + after an image successfully builds: TESTIMAGE_AUTO = "1" @@ -12472,14 +12469,11 @@ system and gives an overview of their function and contents. Classes inherited using :term:`USER_CLASSES` must be located in the ``classes-global/`` or ``classes/`` subdirectories. - The default list is set in your ``local.conf`` file:: + A default list is set in the + :oecore_path:`meta/conf/templates/default/local.conf.sample` file:: USER_CLASSES ?= "buildstats" - For more information, see - ``conf/templates/default/local.conf.sample`` in - :yocto_git:`meta-poky `. - :term:`USERADD_DEPENDS` Specifies a list of recipes that create users / groups (via :term:`USERADD_PARAM` / :term:`GROUPADD_PARAM`) which a recipe @@ -12498,8 +12492,8 @@ system and gives an overview of their function and contents. ``uid`` and ``gid`` values. Consequently, the :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan on using statically assigned ``gid`` and ``uid`` values, you should - set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` - file as follows:: + set the :term:`USERADD_ERROR_DYNAMIC` variable in a :term:`configuration + file`:: USERADD_ERROR_DYNAMIC = "error" @@ -12529,8 +12523,7 @@ system and gives an overview of their function and contents. When applying static group identification (``gid``) values, the OpenEmbedded build system looks in :term:`BBPATH` for a ``files/group`` file and then applies those ``uid`` values. Set the - variable as follows in your ``local.conf`` file:: - + variable as follows in a :term:`configuration file`:: USERADD_GID_TABLES = "files/group" @@ -12580,7 +12573,7 @@ system and gives an overview of their function and contents. When applying static user identification (``uid``) values, the OpenEmbedded build system looks in :term:`BBPATH` for a ``files/passwd`` file and then applies those ``uid`` values. Set the - variable as follows in your ``local.conf`` file:: + variable as follows in a :term:`configuration file`:: USERADD_UID_TABLES = "files/passwd" @@ -12595,8 +12588,10 @@ system and gives an overview of their function and contents. ``group`` files found in :term:`BBPATH`. To use static user identification (``uid``) and group identification - (``gid``) values, set the variable as follows in your ``local.conf`` - file: USERADDEXTENSION = "useradd-staticids" + (``gid``) values, set the variable as follows in in a + :term:`configuration file`:: + + USERADDEXTENSION = "useradd-staticids" .. note:: diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst index 467c5c10c..65fd4af9f 100644 --- a/documentation/sdk-manual/appendix-customizing.rst +++ b/documentation/sdk-manual/appendix-customizing.rst @@ -20,7 +20,8 @@ The extensible SDK primarily consists of a pre-configured copy of the OpenEmbedded build system from which it was produced. Thus, the SDK's configuration is derived using that build system and the filters shown in the following list. When these filters are present, the OpenEmbedded -build system applies them against ``local.conf`` and ``auto.conf``: +build system applies them against :ref:`structure-build-conf-local.conf` and +:ref:`structure-build-conf-auto.conf`: - Variables whose values start with "/" are excluded since the assumption is that those values are paths that are likely to be diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst index 24a8e17b3..d70c38fa5 100644 --- a/documentation/sdk-manual/appendix-obtain.rst +++ b/documentation/sdk-manual/appendix-obtain.rst @@ -99,15 +99,13 @@ build the SDK installer. Follow these steps: to get a :term:`build host` ready. #. *Make Sure You Are Building an Installer for the Correct Machine:* - Check to be sure that your :term:`MACHINE` variable in the ``local.conf`` - file in your :term:`Build Directory` matches the architecture + Check to be sure that your :term:`MACHINE` matches the architecture for which you are building. #. *Make Sure Your SDK Machine is Correctly Set:* If you are building a toolchain designed to run on an architecture that differs from your current development host machine (i.e. the build host), be sure that - the :term:`SDKMACHINE` variable in the ``local.conf`` file in your - :term:`Build Directory` is correctly set. + the :term:`SDKMACHINE` variable is correctly set. .. note:: @@ -153,12 +151,11 @@ build the SDK installer. Follow these steps: of libraries, you need to be sure your SDK has the appropriate static development libraries. Use the :term:`TOOLCHAIN_TARGET_TASK` - variable inside your ``local.conf`` file before building the - SDK installer. Doing so ensures that the eventual SDK - installation process installs the appropriate library packages + variable to install the appropriate library packages as part of the SDK. Here is an example using ``libc`` - static development libraries: TOOLCHAIN_TARGET_TASK:append = " - libc-staticdev" + static development libraries:: + + TOOLCHAIN_TARGET_TASK:append = " libc-staticdev" #. *Run the Installer:* You can now run the SDK installer from ``tmp/deploy/sdk`` in the :term:`Build Directory`. Here is an example: diff --git a/documentation/security-manual/read-only-rootfs.rst b/documentation/security-manual/read-only-rootfs.rst index 251178ed5..823ddcecd 100644 --- a/documentation/security-manual/read-only-rootfs.rst +++ b/documentation/security-manual/read-only-rootfs.rst @@ -28,7 +28,7 @@ image's recipe file via the :term:`IMAGE_FEATURES` variable:: IMAGE_FEATURES += "read-only-rootfs" As an alternative, you can add the same feature -from within your :term:`Build Directory`'s ``local.conf`` file with the +from within your distro :term:`configuration file` with the associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:: EXTRA_IMAGE_FEATURES = "read-only-rootfs" diff --git a/documentation/security-manual/securing-images.rst b/documentation/security-manual/securing-images.rst index bcf4237bf..9772b52d3 100644 --- a/documentation/security-manual/securing-images.rst +++ b/documentation/security-manual/securing-images.rst @@ -81,7 +81,7 @@ your build output more secure. The security flags are in the disabled by default. Use the following line in your ``local.conf`` file or in your custom -distribution configuration file to enable the security compiler and +distro :term:`configuration file` to enable the security compiler and linker flags for your build:: require conf/distro/include/security_flags.inc @@ -100,7 +100,7 @@ system to make your images more secure: EXTRA_IMAGE_FEATURES = "allow-empty-password empty-root-password allow-root-login" - to your ``local.conf`` file, or by enabling the exactly equivalent + to your distro :term:`configuration file`, or by enabling the exactly equivalent configuration fragment :ref:`ref-fragments-root-login-with-empty-password`. If you're using either of these approaches during development, diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst index 84523ff13..892f7b9c8 100644 --- a/documentation/test-manual/reproducible-builds.rst +++ b/documentation/test-manual/reproducible-builds.rst @@ -94,12 +94,12 @@ run:: This defaults to including a ``world`` build so, if other layers are added, it would also run the tests for recipes in the additional layers. Different build targets can be defined using the :term:`OEQA_REPRODUCIBLE_TEST_TARGET` variable -in ``local.conf``. For example, running reproducibility tests for only the +in :ref:`structure-build-conf-local.conf`. For example, running reproducibility tests for only the ``python3-numpy`` recipe can be done by setting:: OEQA_REPRODUCIBLE_TEST_TARGET = "python3-numpy" -in local.conf before running the ``oe-selftest`` command shown above. +in :ref:`structure-build-conf-local.conf` before running the ``oe-selftest`` command shown above. Reproducibility builds the target list twice. The first build will be run using :ref:`Shared State ` if available, the @@ -150,7 +150,7 @@ Using :term:`OEQA_REPRODUCIBLE_TEST_* ` var ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to test the reproducibility of a set of recipes, you can define -:term:`OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS`, in your local.conf:: +:term:`OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS`, in your :ref:`structure-build-conf-local.conf`:: OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS = "my-recipe" diff --git a/documentation/test-manual/runtime-testing.rst b/documentation/test-manual/runtime-testing.rst index a64a97c80..4eef9d059 100644 --- a/documentation/test-manual/runtime-testing.rst +++ b/documentation/test-manual/runtime-testing.rst @@ -95,7 +95,7 @@ Once you start running the tests, the following happens: to reach the login prompt. You can change the timeout period by setting :term:`TEST_QEMUBOOT_TIMEOUT` - in the ``local.conf`` file. + in a :term:`configuration file`. #. Once the boot process is reached and the login prompt appears, the tests run. The full boot log is written to diff --git a/documentation/transitioning-to-a-custom-environment.rst b/documentation/transitioning-to-a-custom-environment.rst index 17938ebda..13f906eea 100644 --- a/documentation/transitioning-to-a-custom-environment.rst +++ b/documentation/transitioning-to-a-custom-environment.rst @@ -98,7 +98,7 @@ Transitioning to a custom environment for systems development well as the package feed and possibly the update solution. You would create your own distribution in a new layer inheriting from :term:`Poky` but overriding what needs to change for your distribution. If you find yourself adding a lot of - configuration to your local.conf file aside from paths and other typical + configuration to your :ref:`structure-build-conf-local.conf` file aside from paths and other typical local settings, it's time to :ref:`consider creating your own distribution `. From patchwork Fri Sep 11 15:11:14 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Antonin Godard X-Patchwork-Id: 97990 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 F2D65C88E50 for ; Fri, 11 Sep 2026 15:12:09 +0000 (UTC) Received: from smtpout-04.galae.net (smtpout-04.galae.net [185.171.202.116]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.41863.1789139519367470000 for ; Fri, 11 Sep 2026 08:11:59 -0700 Authentication-Results: mx.groups.io; dkim=fail reason="dkim: body hash did not verify" header.i=@bootlin.com header.s=dkim header.b=YCAD0g6C; spf=pass (domain: bootlin.com, ip: 185.171.202.116, mailfrom: antonin.godard@bootlin.com) Received: from smtpout-01.galae.net (smtpout-01.galae.net [212.83.139.233]) by smtpout-04.galae.net (Postfix) with ESMTPS id 87F8CC63A0F for ; Fri, 11 Sep 2026 15:12:39 +0000 (UTC) Received: from mail.galae.net (mail.galae.net [212.83.136.155]) by smtpout-01.galae.net (Postfix) with ESMTPS id B6DC3601DE for ; Fri, 11 Sep 2026 15:11:57 +0000 (UTC) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 97BEE11C7AFBA; Fri, 11 Sep 2026 17:11:56 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=dkim; t=1789139517; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=q8heGsFVgylSciLgqKZ5+l3pjz6jFHI2rA9x2KdY+Sc=; b=YCAD0g6C1mp6tjVH5pbUHRyW2ZBKeIMId2Zs6vcumlRX2+mdnakOAHqU5WtZZ0GROIruGM K5BAK9jfV12MKaCCUOzfCSwRlH57gpRZ9nlDtZauyOVDpvBxb37QuNMnpZVlrGw6e4SJir Bdkbzbf43PlyyIYQJwFA5LN82HYXQWPP5Z6buFOvlNk73O7+Cy1YgH3PiM5sAa1Bxoll5H 3B1f4+BxELb2YdUPJvx3xT28E6x3+hbVF32vLsotx0F/aDOtadM1UlmGTg9wc2ioTweWG9 w+7z/Cg5GPGXol/k6qQdk6nzd10575cZl/dQtwL7TcLeCXT03CtqGoDIxzZJUg== From: Antonin Godard Date: Fri, 11 Sep 2026 17:11:14 +0200 Subject: [PATCH 8/8] docs-wide: replace hardcoded conf paths to structure.rst refs MIME-Version: 1.0 Message-Id: <20260911-remove-local-conf-refs-v1-8-322e1e9a232d@bootlin.com> References: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> In-Reply-To: <20260911-remove-local-conf-refs-v1-0-322e1e9a232d@bootlin.com> To: docs@lists.yoctoproject.org Cc: Thomas Petazzoni , Antonin Godard X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=86148; i=antonin.godard@bootlin.com; h=from:subject:message-id; bh=PFzOxuMOqoWQ+AlcsauNX3uaZOS13rTSBSh2QORUlJ0=; b=owEBbQKS/ZANAwAKAdGAQUApo6g2AcsmYgBqpBoYlxLz+TMfrrNMUZdDXYQm2ICrFyLrLy7BR DgFmBN4v3qJAjMEAAEKAB0WIQSGSHJRiN1AG7mg0//RgEFAKaOoNgUCaqQaGAAKCRDRgEFAKaOo Ntq5D/0WenUphG4hIpV3A0sGzJzXpf+pPrmPB6RJ6nPgJ1UbqYOOhWvT4FJ5iX2s1htaqPz4Sjy 9Ui/xwFQh4TXHMeg6FHYQS+/yRtUmEvLrTzajHzwWwCRyYdLT8vjYKALi/DXOf6153eWO4vC9QE jlQRIAjB6vAVMNfn1Pg25Izg5W3JbI5IVGlavkjZYA3KwkI/uF0BikUfNU4x8LYv/HSrk5emXqD ZkFsBSenmI9zkvXyNqSXpaXMhnj2QU/Lgt8badxbCeAfHdd86jKr/6aZ1Xlsg7Cd/LzsjBRWd2S E69cxH4MadVe7rhAt4qJVmSJdRgsaxRAG5xR8RsdUcc9afDUtmBPCKI2Pyj0c9ZMRqatAgOsjHh /Phxlw9HSy/iRGfSHHy75tnGg95qQLknT5VaWX8I+x+JWcwhofyty5tgsS5BRKPC7ZQqXVvUWjn lEhVXvUwqGULm9sMV3q6XWq6sXqrgAaIUOgqW66QeXZikh4HluREonao7TTvOE4dH9S/IbXMGnf KK3HtmIzUCCw/O1wzpi3BITbVv/zTeDZdHxAwjtVYA1Di4tfWkpPfFtC2cuf3pGkA2HyaWpI43v T6z0HeFxjf5EUdy5QkZKE5n22KiSQxYMLVfXkFGHhHTxGAhzs2dLemUHyX7B6ZfVw80ZAyUiuFa p26NLhPVVb5n3mA== X-Developer-Key: i=antonin.godard@bootlin.com; a=openpgp; fpr=8648725188DD401BB9A0D3FFD180414029A3A836 X-Last-TLS-Session-Version: TLSv1.3 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Sep 2026 15:12:09 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10477 Locate the hardcoded strings for configuration files such as local.conf, bblayers.conf and such, and replace them with a reference link to our structure.rst document, which contains information about the purpose of these files. Signed-off-by: Antonin Godard --- documentation/brief-yoctoprojectqs/index.rst | 4 +-- documentation/bsp-manual/bsp.rst | 6 ++-- documentation/dev-manual/bblock.rst | 2 +- documentation/dev-manual/build-quality.rst | 4 +-- documentation/dev-manual/building.rst | 6 ++-- documentation/dev-manual/custom-distribution.rst | 8 ++--- .../custom-template-configuration-directory.rst | 8 ++--- documentation/dev-manual/customizing-images.rst | 6 ++-- documentation/dev-manual/debugging.rst | 16 ++++----- documentation/dev-manual/device-manager.rst | 4 +-- documentation/dev-manual/devtool.rst | 4 +-- documentation/dev-manual/disk-space.rst | 2 +- documentation/dev-manual/error-reporting-tool.rst | 6 ++-- documentation/dev-manual/external-toolchain.rst | 2 +- documentation/dev-manual/layers.rst | 22 ++++++------ documentation/dev-manual/licenses.rst | 8 ++--- documentation/dev-manual/limiting-resources.rst | 2 +- documentation/dev-manual/multiconfig.rst | 10 +++--- documentation/dev-manual/packages.rst | 4 +-- documentation/dev-manual/poky-manual-setup.rst | 2 +- documentation/dev-manual/upgrading-recipes.rst | 4 +-- documentation/dev-manual/x32-psabi.rst | 2 +- documentation/kernel-dev/common.rst | 16 ++++----- documentation/migration-guides/migration-1.3.rst | 4 +-- documentation/migration-guides/migration-1.6.rst | 6 ++-- documentation/migration-guides/migration-1.7.rst | 4 +-- documentation/migration-guides/migration-2.0.rst | 2 +- documentation/migration-guides/migration-2.1.rst | 2 +- documentation/migration-guides/migration-4.1.rst | 2 +- documentation/migration-guides/migration-4.2.rst | 4 +-- .../migration-guides/release-notes-4.2.rst | 2 +- .../migration-guides/release-notes-5.2.rst | 2 +- .../migration-guides/release-notes-6.0.rst | 2 +- documentation/overview-manual/concepts.rst | 36 +++++++++---------- documentation/profile-manual/intro.rst | 8 ++--- documentation/ref-manual/classes.rst | 2 +- documentation/ref-manual/devtool-reference.rst | 2 +- documentation/ref-manual/structure.rst | 12 +++---- documentation/ref-manual/terms.rst | 6 ++-- documentation/ref-manual/variables.rst | 42 +++++++++++----------- documentation/ref-manual/varlocality.rst | 2 +- documentation/sdk-manual/appendix-customizing.rst | 6 ++-- documentation/security-manual/securing-images.rst | 2 +- documentation/test-manual/runtime-testing.rst | 14 ++++---- .../test-manual/understand-autobuilder.rst | 4 +-- documentation/toaster-manual/reference.rst | 2 +- .../transitioning-to-a-custom-environment.rst | 2 +- 47 files changed, 159 insertions(+), 159 deletions(-) diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst index 4adec9714..f7e4606f1 100644 --- a/documentation/brief-yoctoprojectqs/index.rst +++ b/documentation/brief-yoctoprojectqs/index.rst @@ -376,7 +376,7 @@ layer>`: git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi #. **Add Your Layer to the Layer Configuration File:** Before you can use - it, you must add the layer and its dependencies to your ``bblayers.conf`` + it, you must add the layer and its dependencies to your :ref:`structure-build-conf-bblayers.conf` file, which is found in the :term:`Build Directory` (``conf/``) directory. For this, the ``bitbake-layers add-layer`` command can be used: @@ -410,7 +410,7 @@ layer>`: `Synaptics` license. See the :yocto_git:`ipcompliance.md ` document for more information. Add the ``synaptics-killswitch`` value to the :term:`LICENSE_FLAGS_ACCEPTED` - variable, in the ``conf/local.conf`` file of your build directory:: + variable, in the :ref:`structure-build-conf-local.conf` file of your build directory:: LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch" diff --git a/documentation/bsp-manual/bsp.rst b/documentation/bsp-manual/bsp.rst index 8eb4f470b..dd6133269 100644 --- a/documentation/bsp-manual/bsp.rst +++ b/documentation/bsp-manual/bsp.rst @@ -78,7 +78,7 @@ section in the Yocto Project Development Tasks Manual. The BSP layer's base directory (``meta-bsp_root_name``) is the root directory of that Layer. This directory is what you add to the :term:`BBLAYERS` variable in the -``conf/bblayers.conf`` file found in your +:ref:`structure-build-conf-bblayers.conf` file found in your :term:`Build Directory`, which is established after you run the OpenEmbedded build environment setup script (i.e. :ref:`structure-core-script`). @@ -802,7 +802,7 @@ workflow. need to get the build environment ready by sourcing an environment setup script (i.e. ``oe-init-build-env``) and you need to be sure two key configuration files are configured appropriately: the - ``conf/local.conf`` and the ``conf/bblayers.conf`` file. You must + :ref:`structure-build-conf-local.conf` and the :ref:`structure-build-conf-bblayers.conf` file. You must make the OpenEmbedded build system aware of your new layer. See the ":ref:`dev-manual/layers:enabling your layer`" section in the Yocto Project Development Tasks Manual for information @@ -1098,7 +1098,7 @@ list describes them in order of preference: #. *Use the LICENSE_FLAGS Variable to Define the Recipes that Have Commercial or Other Types of Specially-Licensed Packages:* For each of those recipes, you can - specify a matching license string in a ``local.conf`` variable named + specify a matching license string in a :ref:`structure-build-conf-local.conf` variable named :term:`LICENSE_FLAGS_ACCEPTED`. Specifying the matching license string signifies that you agree to the license. Thus, the build system can build the corresponding diff --git a/documentation/dev-manual/bblock.rst b/documentation/dev-manual/bblock.rst index 605bb7565..b9d6606a9 100644 --- a/documentation/dev-manual/bblock.rst +++ b/documentation/dev-manual/bblock.rst @@ -72,7 +72,7 @@ To unlock all recipes, do not specify any recipe:: Configuration file ------------------ -``bblock`` will dump the signatures in the ``build/conf/bblock.conf`` file, +``bblock`` will dump the signatures in the :ref:`structure-build-conf-bblock.conf` file, included by default in :oe_git:`meta/conf/bitbake.conf `. To dump the file, use the ``-d`` option:: diff --git a/documentation/dev-manual/build-quality.rst b/documentation/dev-manual/build-quality.rst index 37d18efd2..dc10d1f05 100644 --- a/documentation/dev-manual/build-quality.rst +++ b/documentation/dev-manual/build-quality.rst @@ -304,8 +304,8 @@ The following list shows the files produced for SDKs: specific to the extensible SDK although you can set it differently if you would like to pull in specific files from the standard SDK. - The default files are ``conf/local.conf``, ``conf/bblayers.conf``, - ``conf/auto.conf``, ``conf/locked-sigs.inc``, and + The default files are :ref:`structure-build-conf-local.conf`, :ref:`structure-build-conf-bblayers.conf`, + :ref:`structure-build-conf-auto.conf`, ``conf/locked-sigs.inc``, and ``conf/devtool.conf``. Thus, for an extensible SDK, these files get copied into the ``sdk-files`` directory. diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index 705bad6ed..d36a523f5 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst @@ -708,7 +708,7 @@ the external directory and use it as is, not copy it. To build from software that comes from an external source, all you need to do is inherit the :ref:`ref-classes-externalsrc` class and then set the :term:`EXTERNALSRC` variable to point to your external source code. Here -are the statements to put in your ``local.conf`` file:: +are the statements to put in your :ref:`structure-build-conf-local.conf` file:: INHERIT += "externalsrc" EXTERNALSRC:pn-myrecipe = "path-to-your-source-tree" @@ -758,7 +758,7 @@ Follow these steps to populate your Downloads directory: an empty location or one that does not yet exist. #. *Generate Tarballs of the Source Git Repositories:* Edit your - ``local.conf`` configuration file as follows:: + :ref:`structure-build-conf-local.conf` configuration file as follows:: DL_DIR = "/home/your-download-dir/" BB_GENERATE_MIRROR_TARBALLS = "1" @@ -793,7 +793,7 @@ any machine and at any time. Follow these steps to build your target using the files in the downloads directory: -#. *Using Local Files Only:* Inside your ``local.conf`` or distro +#. *Using Local Files Only:* Inside your :ref:`structure-build-conf-local.conf` or distro :term:`configuration file`, add the :term:`SOURCE_MIRROR_URL` variable, inherit the :ref:`ref-classes-own-mirrors` class, and add the :term:`BB_NO_NETWORK` variable:: diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst index 365bfa8f7..7129439dd 100644 --- a/documentation/dev-manual/custom-distribution.rst +++ b/documentation/dev-manual/custom-distribution.rst @@ -26,7 +26,7 @@ layer. The following steps provide some more detail: so that you can keep your Metadata and code for the distribution separate. It is strongly recommended that you create and use your own layer for configuration and code. Using your own layer as compared to - just placing configurations in a ``local.conf`` configuration file + just placing configurations in a :ref:`structure-build-conf-local.conf` configuration file makes it easier to reproduce the same build configuration when using multiple build machines. See the ":ref:`dev-manual/layers:Creating Your Own Layer`" @@ -39,7 +39,7 @@ layer. The following steps provide some more detail: .. note:: - The :term:`DISTRO` variable in your ``local.conf`` file determines the + The :term:`DISTRO` variable in your :ref:`structure-build-conf-local.conf` file determines the name of your distribution. You can also use the :ref:`ref-fragments-builtin-core-distro` configuration fragment. @@ -81,10 +81,10 @@ layer. The following steps provide some more detail: - *Provide miscellaneous variables:* Be sure to define any other variables for which you want to create a default or enforce as part of the distribution configuration. You can include nearly any - variable from the ``local.conf`` file. The variables you use are not + variable from the :ref:`structure-build-conf-local.conf` file. The variables you use are not limited to the list in the previous bulleted item. -- *Point to Your distribution configuration file:* In your ``local.conf`` +- *Point to Your distribution configuration file:* In your :ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`, set your :term:`DISTRO` variable to point to your distribution's configuration file. For example, if your distribution's configuration file is named ``mydistro.conf``, then diff --git a/documentation/dev-manual/custom-template-configuration-directory.rst b/documentation/dev-manual/custom-template-configuration-directory.rst index 597772f7f..7febc8c4a 100644 --- a/documentation/dev-manual/custom-template-configuration-directory.rst +++ b/documentation/dev-manual/custom-template-configuration-directory.rst @@ -5,8 +5,8 @@ Creating a Custom Template Configuration Directory If you are producing your own customized version of the build system for use by other users, you might want to provide a custom build configuration -that includes all the necessary settings and layers (i.e. ``local.conf`` and -``bblayers.conf`` that are created in a new :term:`Build Directory`) and a custom +that includes all the necessary settings and layers (i.e. :ref:`structure-build-conf-local.conf` and +:ref:`structure-build-conf-bblayers.conf` that are created in a new :term:`Build Directory`) and a custom message that is shown when setting up the build. This can be done by creating one or more template configuration directories in your custom distribution layer. @@ -21,7 +21,7 @@ This can be done by using ``bitbake-layers save-build-conf``:: TEMPLATECONF=/srv/bitbake-builds/layers/meta-alex/conf/templates/test-1 . /srv/bitbake-builds/layers/openembedded-core/oe-init-build-env build-try-test-1 The above command takes the config files from the currently active :term:`Build Directory` under ``conf``, -replaces site-specific paths in ``bblayers.conf`` with ``##OECORE##``-relative paths, and copies +replaces site-specific paths in :ref:`structure-build-conf-bblayers.conf` with ``##OECORE##``-relative paths, and copies the config files into a specified layer under a specified template name. To use those saved templates as a starting point for a build, users should point @@ -44,7 +44,7 @@ would be:: If you look at a configuration template directory, you will see the ``bblayers.conf.sample``, ``local.conf.sample``, ``conf-summary.txt`` and ``conf-notes.txt`` files. The build system uses these files to form the -respective ``bblayers.conf`` file, ``local.conf`` file, and show +respective :ref:`structure-build-conf-bblayers.conf` file, ``local.conf`` file, and show users usage information about the build they're setting up when running the ``oe-init-build-env`` setup script. These can be edited further if needed to improve or change the build configurations diff --git a/documentation/dev-manual/customizing-images.rst b/documentation/dev-manual/customizing-images.rst index 9a345c8bb..ab12e342b 100644 --- a/documentation/dev-manual/customizing-images.rst +++ b/documentation/dev-manual/customizing-images.rst @@ -10,7 +10,7 @@ Customizing Images Using ``local.conf`` ======================================= Probably the easiest way to customize an image is to add a package by -way of the ``local.conf`` configuration file. Because it is limited to +way of the :ref:`structure-build-conf-local.conf` configuration file. Because it is limited to local use, this method generally only allows you to add packages and is not as flexible as creating your own customized image. When you add packages using local variables this way, you need to realize that these @@ -56,7 +56,7 @@ high-level image features by using the variables. Although the functions for both variables are nearly equivalent, best practices dictate using :term:`IMAGE_FEATURES` from within a recipe and using :term:`EXTRA_IMAGE_FEATURES` from within your -``local.conf`` for temporary changes (which is found in the :term:`Build +:ref:`structure-build-conf-local.conf` for temporary changes (which is found in the :term:`Build Directory`) and a distro :term:`configuration file` for permanent changes. To understand how these features work, the best reference is @@ -91,7 +91,7 @@ image does not contain an SSH server. You can customize your image and change these defaults. Edit the :term:`IMAGE_FEATURES` variable in your recipe or use the -:term:`EXTRA_IMAGE_FEATURES` in your ``local.conf`` file (or distro +:term:`EXTRA_IMAGE_FEATURES` in your :ref:`structure-build-conf-local.conf` file (or distro :term:`configuration file`) so that it configures the image you are working with to include ``ssh-server-dropbear`` or ``ssh-server-openssh``. diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 1718b90d2..4995ba73f 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -113,7 +113,7 @@ variables>` did not work out as expected. BitBake's ``bitbake-getvar`` command is used to display variable values after parsing. The following command displays the variable value for :term:`OVERRIDES` -after the configuration files (i.e. ``local.conf``, ``bblayers.conf``, +after the configuration files (i.e. ``local.conf``, :ref:`structure-build-conf-bblayers.conf`, ``bitbake.conf`` and so forth) have been parsed:: $ bitbake-getvar OVERRIDES @@ -787,7 +787,7 @@ In this example, compiling the "neard" package is causing the problem. So the first thing to do is build "neard" locally. Before you start the build, set the :term:`PARALLEL_MAKE` variable -in your ``local.conf`` file to a high number (e.g. "-j 20"). Using a +in your :ref:`structure-build-conf-local.conf` file to a high number (e.g. "-j 20"). Using a high value for :term:`PARALLEL_MAKE` increases the chances of the race condition showing up:: @@ -943,7 +943,7 @@ To run a ``debuginfod`` server, you need to do the following: (it already is in :term:`OpenEmbedded-Core (OE-Core)` defaults and :term:`Poky` reference distribution). - If not, set in your distro :term:`configuration file` or in ``local.conf``:: + If not, set in your distro :term:`configuration file` or in :ref:`structure-build-conf-local.conf`:: DISTRO_FEATURES:append = " debuginfod" @@ -1010,7 +1010,7 @@ debugger. #. *Configure your build system to construct the companion debug filesystem:* - In your ``local.conf`` file, set the following:: + In your :ref:`structure-build-conf-local.conf` file, set the following:: IMAGE_GEN_DEBUGFS = "1" IMAGE_FSTYPES_DEBUGFS = "tar.bz2" @@ -1029,7 +1029,7 @@ debugger. #. *Configure the system to include gdbserver in the target filesystem:* - Make the following addition in your ``local.conf`` file:: + Make the following addition in your :ref:`structure-build-conf-local.conf` file:: EXTRA_IMAGE_FEATURES:append = " tools-debug" @@ -1165,7 +1165,7 @@ debug on the target hardware. To support this kind of debugging, you need do the following: - Ensure that GDB is on the target. You can do this by making - the following addition to your ``local.conf`` file:: + the following addition to your :ref:`structure-build-conf-local.conf` file:: EXTRA_IMAGE_FEATURES:append = " tools-debug" @@ -1174,7 +1174,7 @@ To support this kind of debugging, you need do the following: IMAGE_INSTALL:append = " packagename-dbg" - Alternatively, you can add the following to ``local.conf`` to include + Alternatively, you can add the following to :ref:`structure-build-conf-local.conf` to include all the debug symbols:: EXTRA_IMAGE_FEATURES:append = " dbg-pkgs" @@ -1183,7 +1183,7 @@ To support this kind of debugging, you need do the following: To improve the debug information accuracy, you can reduce the level of optimization used by the compiler. For example, when adding the - following line to your ``local.conf`` file, you will reduce optimization + following line to your :ref:`structure-build-conf-local.conf` file, you will reduce optimization from :term:`FULL_OPTIMIZATION` of "-O2" to :term:`DEBUG_OPTIMIZATION` of "-O -fno-omit-frame-pointer":: diff --git a/documentation/dev-manual/device-manager.rst b/documentation/dev-manual/device-manager.rst index 757b23d1a..cc27b667a 100644 --- a/documentation/dev-manual/device-manager.rst +++ b/documentation/dev-manual/device-manager.rst @@ -32,7 +32,7 @@ Table file. The :term:`IMAGE_DEVICE_TABLES` variable defines the Device Table to use and should be set in the machine or distro :term:`configuration file`. Alternatively, you can set this -variable in your ``local.conf`` configuration file. +variable in your :ref:`structure-build-conf-local.conf` configuration file. If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default ``device_table-minimal.txt`` is used:: @@ -64,7 +64,7 @@ To have more control over the device nodes, you can use a device manager like ``udev`` or ``busybox-mdev``. You choose the device manager by defining the :term:`VIRTUAL-RUNTIME_dev_manager ` variable in your machine or distro :term:`configuration file`. Alternatively, you can set this variable in -your ``local.conf`` configuration file:: +your :ref:`structure-build-conf-local.conf` configuration file:: VIRTUAL-RUNTIME_dev_manager = "udev" diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst index d67f22277..242ea9dd9 100644 --- a/documentation/dev-manual/devtool.rst +++ b/documentation/dev-manual/devtool.rst @@ -445,7 +445,7 @@ installers. functionality of the SDK and the eSDK installers. Compared to the installers, however, the SDK created with ``devtool ide-sdk`` is much more flexible. For example, it is very easy to change the :term:`MACHINE` in the -``local.conf`` file, update the layer meta data and then regenerate the SDK. +:ref:`structure-build-conf-local.conf` file, update the layer meta data and then regenerate the SDK. Let's take a look at an example of how to use ``devtool ide-sdk`` in each of the two modes: @@ -454,7 +454,7 @@ the two modes: In order to use the ``devtool ide-sdk``, a few settings are needed. As a starting example, the following lines of code can be added to the - ``local.conf`` file:: + :ref:`structure-build-conf-local.conf` file:: # Build the companion debug file system IMAGE_GEN_DEBUGFS = "1" diff --git a/documentation/dev-manual/disk-space.rst b/documentation/dev-manual/disk-space.rst index ba3afa5a2..5516f793e 100644 --- a/documentation/dev-manual/disk-space.rst +++ b/documentation/dev-manual/disk-space.rst @@ -7,7 +7,7 @@ Conserving Disk Space During Builds =================================== To help conserve disk space during builds, you can add the following -statement to your project's ``local.conf`` configuration file found in +statement to your project's :ref:`structure-build-conf-local.conf` configuration file found in the :term:`Build Directory`:: INHERIT += "rm_work" diff --git a/documentation/dev-manual/error-reporting-tool.rst b/documentation/dev-manual/error-reporting-tool.rst index 30d1ce2b3..dabade078 100644 --- a/documentation/dev-manual/error-reporting-tool.rst +++ b/documentation/dev-manual/error-reporting-tool.rst @@ -27,7 +27,7 @@ Enabling and Using the Tool By default, the error reporting tool is disabled. You can enable it by inheriting the :ref:`ref-classes-report-error` class by adding the -following statement to the end of your ``local.conf`` file in your +following statement to the end of your :ref:`structure-build-conf-local.conf` file in your :term:`Build Directory`:: INHERIT += "report-error" @@ -35,7 +35,7 @@ following statement to the end of your ``local.conf`` file in your By default, the error reporting feature stores information in ``${``\ :term:`LOG_DIR`\ ``}/error-report``. However, you can specify a directory to use by adding the following to -your ``local.conf`` file:: +your :ref:`structure-build-conf-local.conf` file:: ERR_REPORT_DIR = "path" @@ -69,7 +69,7 @@ Disabling the Tool ================== To disable the error reporting feature, simply remove or comment out the -following statement from the end of your ``local.conf`` file in your +following statement from the end of your :ref:`structure-build-conf-local.conf` file in your :term:`Build Directory`:: INHERIT += "report-error" diff --git a/documentation/dev-manual/external-toolchain.rst b/documentation/dev-manual/external-toolchain.rst index ea196b67a..94b4e67a8 100644 --- a/documentation/dev-manual/external-toolchain.rst +++ b/documentation/dev-manual/external-toolchain.rst @@ -12,7 +12,7 @@ follows: steps to build and install the toolchain. - Make sure you add the layer that contains the toolchain to your - ``bblayers.conf`` file through the + :ref:`structure-build-conf-bblayers.conf` file through the :term:`BBLAYERS` variable. - Set the :term:`EXTERNAL_TOOLCHAIN` variable in your diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst index 49dc7a6e9..50e276cc0 100644 --- a/documentation/dev-manual/layers.rst +++ b/documentation/dev-manual/layers.rst @@ -75,7 +75,7 @@ Follow these general steps to create your layer without using tools: Add your new layer with 'bitbake-layers add-layer meta-scottrif' In order to use a layer with the :term:`OpenEmbedded Build System`, you - need to add the layer to your ``bblayers.conf`` configuration + need to add the layer to your :ref:`structure-build-conf-bblayers.conf` configuration file, as hinted by the previous command. See the ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" section for more information. @@ -219,7 +219,7 @@ following list: The dependency is created during any build that includes the layer ``meta-one``. However, you might not want this dependency for all machines. For example, suppose you - are building for machine "two" but your ``bblayers.conf`` file has + are building for machine "two" but your :ref:`structure-build-conf-bblayers.conf` file has the ``meta-one`` layer included. During the build, the ``base-files`` for machine "two" will also have the dependency on ``foo``. @@ -267,7 +267,7 @@ following list: The build for machine "one" will pick up your machine-specific file as long as you have the file in ``meta-one/recipes-core/base-files/base-files/``. However, if you - are building for a different machine and the ``bblayers.conf`` + are building for a different machine and the :ref:`structure-build-conf-bblayers.conf` file includes the ``meta-one`` layer and the location of your machine-specific file is the first location where that file is found according to :term:`FILESPATH`, builds for all machines will @@ -466,7 +466,7 @@ Enabling Your Layer Before the OpenEmbedded build system can use your new layer, you need to enable it. To enable your layer, simply add your layer's path to the -:term:`BBLAYERS` variable in your ``conf/bblayers.conf`` file, which is +:term:`BBLAYERS` variable in your :ref:`structure-build-conf-bblayers.conf` file, which is found in the :term:`Build Directory`. The following example shows how to enable your new ``meta-mylayer`` layer (note how your new layer exists outside of the official ``poky`` repository which you would have checked @@ -485,7 +485,7 @@ out earlier):: " BitBake parses each ``conf/layer.conf`` file from the top down as -specified in the :term:`BBLAYERS` variable within the ``conf/bblayers.conf`` +specified in the :term:`BBLAYERS` variable within the :ref:`structure-build-conf-bblayers.conf` file. During the processing of each ``conf/layer.conf`` file, BitBake adds the recipes, classes and configurations contained within the particular layer to the source directory. @@ -822,9 +822,9 @@ The following list describes the available commands: - ``show-cross-depends:`` Lists dependency relationships between recipes that cross layer boundaries. -- ``add-layer:`` Adds a layer to ``bblayers.conf``. +- ``add-layer:`` Adds a layer to :ref:`structure-build-conf-bblayers.conf`. -- ``remove-layer:`` Removes a layer from ``bblayers.conf`` +- ``remove-layer:`` Removes a layer from :ref:`structure-build-conf-bblayers.conf` - ``flatten:`` Flattens the layer configuration into a separate output directory. Flattening your layer configuration builds a @@ -870,13 +870,13 @@ The following list describes the available commands: - ``layerindex-fetch``: Fetches a layer from a layer index, along with its dependent layers, and adds the layers to the - ``conf/bblayers.conf`` file. + :ref:`structure-build-conf-bblayers.conf` file. - ``layerindex-show-depends``: Finds layer dependencies from the layer index. - ``save-build-conf``: Saves the currently active build configuration - (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer. + (:ref:`structure-build-conf-local.conf`, :ref:`structure-build-conf-bblayers.conf`) as a template into a layer. This template can later be used for setting up builds via :term:`TEMPLATECONF`. For information about saving and using configuration templates, see ":ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`". @@ -893,7 +893,7 @@ Adding a Layer Using the ``bitbake-layers`` Script ================================================== Once you create your general layer, you must add it to your -``bblayers.conf`` file. Adding the layer to this configuration file +:ref:`structure-build-conf-bblayers.conf` file. Adding the layer to this configuration file makes the OpenEmbedded build system aware of your layer so that it can search it for metadata. @@ -904,7 +904,7 @@ Add your layer by using the ``bitbake-layers add-layer`` command:: Here is an example that adds a layer named ``meta-scottrif`` to the configuration file. Following the command that adds the layer is another ``bitbake-layers`` command that -shows the layers that are in your ``bblayers.conf`` file: +shows the layers that are in your :ref:`structure-build-conf-bblayers.conf` file: .. code-block:: console diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst index b5091087e..fc23871c8 100644 --- a/documentation/dev-manual/licenses.rst +++ b/documentation/dev-manual/licenses.rst @@ -134,7 +134,7 @@ In order for a component restricted by a :term:`LICENSE_FLAGS` definition to be enabled and included in an image, it needs to have a matching entry in the global :term:`LICENSE_FLAGS_ACCEPTED` -variable, which is a variable typically defined in your ``local.conf`` +variable, which is a variable typically defined in your :ref:`structure-build-conf-local.conf` file. For example, to enable the ``meta/recipes-multimedia/gstreamer/gstreamer1.0-plugins-ugly`` package of :term:`OpenEmbedded-Core (OE-Core)`, you @@ -251,7 +251,7 @@ defined in the COMMERCIAL_VIDEO_PLUGINS ?= "" If you want to enable these components, you can do so by making sure you have -statements similar to the following in your ``local.conf`` configuration file:: +statements similar to the following in your :ref:`structure-build-conf-local.conf` configuration file:: COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ gst-plugins-ugly-mpegaudioparse" @@ -361,7 +361,7 @@ create them with various levels of compliance in mind. One way of doing this (but certainly not the only way) is to release just the source as a tarball. You can do this by adding the following to -the ``local.conf`` file found in the :term:`Build Directory`:: +the :ref:`structure-build-conf-local.conf` file found in the :term:`Build Directory`:: INHERIT += "archiver" ARCHIVER_MODE[src] = "original" @@ -473,7 +473,7 @@ One thing a development organization might want to consider for end-user convenience is to provide its own version of the :oecore_path:`meta/conf/templates/default/bblayers.conf.sample` file to ensure that when the end user utilizes the released build system to build an image, the -development organization's layers are included in the ``bblayers.conf`` file +development organization's layers are included in the :ref:`structure-build-conf-bblayers.conf` file automatically:: # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf diff --git a/documentation/dev-manual/limiting-resources.rst b/documentation/dev-manual/limiting-resources.rst index 9b3db0a59..892b0069a 100644 --- a/documentation/dev-manual/limiting-resources.rst +++ b/documentation/dev-manual/limiting-resources.rst @@ -38,7 +38,7 @@ details. If you want to have a different limit from the rest of the build for a recipe, it is also possible to achieve with the following line added to your - ``local.conf`` :term:`configuration file`:: + :ref:`structure-build-conf-local.conf` :term:`configuration file`:: PARALLEL_MAKE:pn-linux-yocto = "-j4" diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst index 71fe542ef..58ff95c17 100644 --- a/documentation/dev-manual/multiconfig.rst +++ b/documentation/dev-manual/multiconfig.rst @@ -20,7 +20,7 @@ To accomplish a multiple configuration build, you must define each target's configuration separately using a parallel :term:`configuration file` in the :term:`Build Directory` or configuration directory within a layer, and you must follow a required file hierarchy. Additionally, you must enable the -multiple configuration builds in your ``local.conf`` file. +multiple configuration builds in your :ref:`structure-build-conf-local.conf` file. Follow these steps to set up and execute multiple configuration builds: @@ -74,7 +74,7 @@ Follow these steps to set up and execute multiple configuration builds: - *Add the BitBake Multi-configuration Variable to the Local Configuration File*: Use the :term:`BBMULTICONFIG` - variable in your ``conf/local.conf`` configuration file to specify + variable in your :ref:`structure-build-conf-local.conf` configuration file to specify each multiconfig. Continuing with the example from the previous figure, the :term:`BBMULTICONFIG` variable needs to enable two multiconfigs: "x86" and "arm" by specifying each configuration file:: @@ -85,7 +85,7 @@ Follow these steps to set up and execute multiple configuration builds: A "default" configuration already exists by definition. This configuration is named: "" (i.e. empty string) and is defined by - the variables coming from your ``local.conf`` + the variables coming from your :ref:`structure-build-conf-local.conf` file. Consequently, the previous example actually adds two additional configurations to your build: "arm" and "x86" along with "". @@ -107,7 +107,7 @@ Follow these steps to set up and execute multiple configuration builds: - A ``core-image-sato`` image that is configured through the ``arm.conf`` configuration file - - A ``core-image-base`` that is configured through your ``local.conf`` + - A ``core-image-base`` that is configured through your :ref:`structure-build-conf-local.conf` configuration file .. note:: @@ -178,7 +178,7 @@ Suggested best practices ======================== - :term:`TMPDIR` (other than the default set in bitbake.conf) is only set in - ``local.conf`` by the user. This means that we should **not** manipulate + :ref:`structure-build-conf-local.conf` by the user. This means that we should **not** manipulate :term:`TMPDIR` in any way within the Machine or Distro :term:`configuration file`. diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst index 95488c761..0271cca10 100644 --- a/documentation/dev-manual/packages.rst +++ b/documentation/dev-manual/packages.rst @@ -163,7 +163,7 @@ be consistent and correct with the latest changes. The simplest form for a PR Service is for a single host development system that builds the package feed (building system). For this scenario, you can enable a local PR Service by setting :term:`PRSERV_HOST` in your -``local.conf`` file in the :term:`Build Directory`:: +:ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`:: PRSERV_HOST = "localhost:0" @@ -959,7 +959,7 @@ NPM packages: part of the OpenEmbedded environment. You need to get the package by cloning the :oe_git:`meta-openembedded ` repository. Be sure to add the path to your local copy - to your ``bblayers.conf`` file. + to your :ref:`structure-build-conf-bblayers.conf` file. - ``devtool`` cannot detect native libraries in module dependencies. Consequently, you must manually add packages to your recipe. diff --git a/documentation/dev-manual/poky-manual-setup.rst b/documentation/dev-manual/poky-manual-setup.rst index 5e65763d5..ca8539b6b 100644 --- a/documentation/dev-manual/poky-manual-setup.rst +++ b/documentation/dev-manual/poky-manual-setup.rst @@ -103,7 +103,7 @@ an entire Linux distribution, including the toolchain, from source. Directory` contains all the files created during the build. #. **Examine Your Local Configuration File:** When you set up the build - environment, a local configuration file named ``local.conf`` becomes + environment, a local configuration file named :ref:`structure-build-conf-local.conf` becomes available in a ``conf`` sub-directory of the :term:`Build Directory`. For this example, the defaults are set to build for a ``qemux86-64`` target, which is suitable for emulation. The package manager used is set to the RPM diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst index 5c4e7df5d..0bdc1351e 100644 --- a/documentation/dev-manual/upgrading-recipes.rst +++ b/documentation/dev-manual/upgrading-recipes.rst @@ -96,14 +96,14 @@ The following steps describe how to set up the AUH utility: undesirably. #. *Make Configurations in Your Local Configuration File:* Several - settings are needed in the ``local.conf`` file in the build + settings are needed in the :ref:`structure-build-conf-local.conf` file in the build directory you just created for AUH. Make these following configurations: - If you want to enable :ref:`Build History `, which is optional, you need the following lines in the - ``conf/local.conf`` file:: + :ref:`structure-build-conf-local.conf` file:: INHERIT =+ "buildhistory" BUILDHISTORY_COMMIT = "1" diff --git a/documentation/dev-manual/x32-psabi.rst b/documentation/dev-manual/x32-psabi.rst index 0a19d2823..4ee5a5379 100644 --- a/documentation/dev-manual/x32-psabi.rst +++ b/documentation/dev-manual/x32-psabi.rst @@ -38,7 +38,7 @@ follows: - There is support for large images. -To use the x32 psABI, you need to edit your ``conf/local.conf`` +To use the x32 psABI, you need to edit your :ref:`structure-build-conf-local.conf` configuration file as follows:: MACHINE = "qemux86-64" diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst index af06e8dcd..2a65055e2 100644 --- a/documentation/kernel-dev/common.rst +++ b/documentation/kernel-dev/common.rst @@ -93,7 +93,7 @@ section: #. *Inform the BitBake Build Environment About Your Layer:* As directed when you created your layer, you need to add the layer to the :term:`BBLAYERS` variable in the - ``bblayers.conf`` file as follows:: + :ref:`structure-build-conf-bblayers.conf` file as follows:: $ cd bitbake-builds/build $ bitbake-layers add-layer ../../meta-mylayer @@ -148,7 +148,7 @@ section: #. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is set to "qemux86-64", which is fine if you are building for the QEMU emulator in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE` - variable appropriately in your ``conf/local.conf`` file found in the + variable appropriately in your :ref:`structure-build-conf-local.conf` file found in the :term:`Build Directory` (i.e. ``bitbake-builds/build`` in this example). Also, since you are preparing to work on the kernel image, you need @@ -189,7 +189,7 @@ section: #. *Inform the BitBake Build Environment About Your Layer:* As directed when you created your layer, you need to add the layer to the :term:`BBLAYERS` variable in the - ``bblayers.conf`` file as follows:: + :ref:`structure-build-conf-bblayers.conf` file as follows:: $ cd bitbake-builds/build $ bitbake-layers add-layer ../../meta-mylayer @@ -835,16 +835,16 @@ Section. pick up the changes. #. *Update Your local.conf File to Point to Your Source Files:* In - addition to your ``local.conf`` file specifying to use + addition to your :ref:`structure-build-conf-local.conf` file specifying to use "kernel-modules" and the "qemux86" machine, it must also point to the updated kernel source files. Add :term:`SRC_URI` and :term:`SRCREV` statements similar - to the following to your ``local.conf``:: + to the following to your :ref:`structure-build-conf-local.conf`:: $ cd bitbake-builds/build/conf - Add the following to the ``local.conf``:: + Add the following to the :ref:`structure-build-conf-local.conf`:: SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" @@ -859,7 +859,7 @@ Section. example, the branch is ``standard/base`` and the machine is ``qemux86``. #. *Build the Image:* With the source modified, your changes staged and - committed, and the ``local.conf`` file pointing to the kernel files, + committed, and the :ref:`structure-build-conf-local.conf` file pointing to the kernel files, you can now use BitBake to build the image:: $ cd bitbake-builds/build @@ -1193,7 +1193,7 @@ information on how to use the output as a configuration fragment. Where do you put your configuration fragment files? You can place these files in an area pointed to by :term:`SRC_URI` as directed by your -``bblayers.conf`` file, which is located in your layer. The OpenEmbedded +:ref:`structure-build-conf-bblayers.conf` file, which is located in your layer. The OpenEmbedded build system picks up the configuration and adds it to the kernel's configuration. For example, suppose you had a set of configuration options in a file called ``myconfig.cfg``. If you put that file inside a diff --git a/documentation/migration-guides/migration-1.3.rst b/documentation/migration-guides/migration-1.3.rst index 594320d5e..0c378aabe 100644 --- a/documentation/migration-guides/migration-1.3.rst +++ b/documentation/migration-guides/migration-1.3.rst @@ -12,7 +12,7 @@ Local Configuration ------------------- Differences include changes for -:term:`SSTATE_MIRRORS` and ``bblayers.conf``. +:term:`SSTATE_MIRRORS` and :ref:`structure-build-conf-bblayers.conf`. .. _migration-1.3-sstate-mirrors: @@ -42,7 +42,7 @@ The ``meta-yocto`` layer consists of two parts that correspond to the Poky reference distribution and the reference hardware Board Support Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``. When running BitBake for the first time after upgrading, your -``conf/bblayers.conf`` file will be updated to handle this change and +:ref:`structure-build-conf-bblayers.conf` file will be updated to handle this change and you will be asked to re-run or restart for the changes to take effect. .. _1.3-recipes: diff --git a/documentation/migration-guides/migration-1.6.rst b/documentation/migration-guides/migration-1.6.rst index b052a43a3..e55924e38 100644 --- a/documentation/migration-guides/migration-1.6.rst +++ b/documentation/migration-guides/migration-1.6.rst @@ -247,15 +247,15 @@ the :ref:`ref-classes-autotools` or ``autotools_stage`` classes. ``qemu-native`` now builds without SDL-based graphical output support by default. The following additional lines are needed in your -``local.conf`` to enable it:: +:ref:`structure-build-conf-local.conf` to enable it:: PACKAGECONFIG_pn-qemu-native = "sdl" ASSUME_PROVIDED += "libsdl-native" .. note:: - The default ``local.conf`` contains these statements. Consequently, if you - are building a headless system and using a default ``local.conf`` + The default :ref:`structure-build-conf-local.conf` contains these statements. Consequently, if you + are building a headless system and using a default :ref:`structure-build-conf-local.conf` file, you will need comment these two lines out. .. _migration-1.6-core-image-basic: diff --git a/documentation/migration-guides/migration-1.7.rst b/documentation/migration-guides/migration-1.7.rst index 1a5704fd4..8527213b8 100644 --- a/documentation/migration-guides/migration-1.7.rst +++ b/documentation/migration-guides/migration-1.7.rst @@ -14,10 +14,10 @@ Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf`` The QEMU recipe now uses a number of :term:`PACKAGECONFIG` options to enable various optional features. The method used to set defaults for these options -means that existing ``local.conf`` files will need to be modified to +means that existing :ref:`structure-build-conf-local.conf` files will need to be modified to append to :term:`PACKAGECONFIG` for ``qemu-native`` and ``nativesdk-qemu`` instead of setting it. In other words, to enable graphical output for -QEMU, you should now have these lines in ``local.conf``:: +QEMU, you should now have these lines in :ref:`structure-build-conf-local.conf`:: PACKAGECONFIG_append_pn-qemu-native = " sdl" PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" diff --git a/documentation/migration-guides/migration-2.0.rst b/documentation/migration-guides/migration-2.0.rst index 13be9846d..b98f2277e 100644 --- a/documentation/migration-guides/migration-2.0.rst +++ b/documentation/migration-guides/migration-2.0.rst @@ -195,7 +195,7 @@ configuration are now automatically removed from sysroot as well as removed from any other place managed by shared state. This automatic cleanup means that the build system now properly handles situations such as renaming the build system side of recipes, removal of layers from -``bblayers.conf``, and :term:`DISTRO_FEATURES` +:ref:`structure-build-conf-bblayers.conf`, and :term:`DISTRO_FEATURES` changes. Additionally, work directories for old versions of recipes are now diff --git a/documentation/migration-guides/migration-2.1.rst b/documentation/migration-guides/migration-2.1.rst index 4d7aa15af..473dd10ff 100644 --- a/documentation/migration-guides/migration-2.1.rst +++ b/documentation/migration-guides/migration-2.1.rst @@ -251,7 +251,7 @@ The following changes have been made for the Poky distribution: distribution. The ``meta-yocto-bsp`` layer retains its original name since it provides reference machines for the Yocto Project and it is otherwise unrelated to Poky. References to ``meta-yocto`` in your - ``conf/bblayers.conf`` should automatically be updated, so you should + :ref:`structure-build-conf-bblayers.conf` should automatically be updated, so you should not need to change anything unless you are relying on this naming elsewhere. diff --git a/documentation/migration-guides/migration-4.1.rst b/documentation/migration-guides/migration-4.1.rst index 86721b987..2daaffb1d 100644 --- a/documentation/migration-guides/migration-4.1.rst +++ b/documentation/migration-guides/migration-4.1.rst @@ -87,7 +87,7 @@ existing ``classes`` subdirectory will continue to work in any context as before Other than knowing where to look when manually browsing the class files, this is not likely to require any changes to your configuration. However, if in your configuration you were using some classes in the incorrect context, you will now -receive an error during parsing. For example, the following in ``local.conf`` will +receive an error during parsing. For example, the following in :ref:`structure-build-conf-local.conf` will now cause an error:: INHERIT += "testimage" diff --git a/documentation/migration-guides/migration-4.2.rst b/documentation/migration-guides/migration-4.2.rst index f5f12c887..990e16e8f 100644 --- a/documentation/migration-guides/migration-4.2.rst +++ b/documentation/migration-guides/migration-4.2.rst @@ -164,7 +164,7 @@ Additionally, the :term:`LAYERSERIES_COMPAT` value for the devtool workspace layer is now set at the time of creation, thus if you upgrade with the workspace layer enabled and you wish to retain it, you will need to manually update the :term:`LAYERSERIES_COMPAT` value in ``workspace/conf/layer.conf`` -(or remove the path from :term:`BBLAYERS` in ``conf/bblayers.conf`` and +(or remove the path from :term:`BBLAYERS` in :ref:`structure-build-conf-bblayers.conf` and delete/move the ``workspace`` directory out of the way if you no longer need it). @@ -183,7 +183,7 @@ possibly Internet reachable network interfaces. Thus, in this release we limit qemu port forwarding to localhost (127.0.0.1). However, if you need the qemu machine to be reachable from the -network, then it can be enabled via ``conf/local.conf`` or machine +network, then it can be enabled via :ref:`structure-build-conf-local.conf` or machine config variable ``QB_SLIRP_OPT``:: QB_SLIRP_OPT = "-netdev user,id=net0,hostfwd=tcp::2222-:22" diff --git a/documentation/migration-guides/release-notes-4.2.rst b/documentation/migration-guides/release-notes-4.2.rst index 529be7da2..f50ef180a 100644 --- a/documentation/migration-guides/release-notes-4.2.rst +++ b/documentation/migration-guides/release-notes-4.2.rst @@ -242,7 +242,7 @@ New Features / Enhancements in 4.2 - bitbake-layers improvements: - ``layerindex-fetch``: checkout layer(s) branch when clone exists - - ``create``: add ``-a``/``--add-layer option`` to add layer to ``bblayers.conf`` after creating layer + - ``create``: add ``-a``/``--add-layer option`` to add layer to :ref:`structure-build-conf-bblayers.conf` after creating layer - ``show-layers``: improve output layout - Other BitBake improvements: diff --git a/documentation/migration-guides/release-notes-5.2.rst b/documentation/migration-guides/release-notes-5.2.rst index b5483c903..111162bc9 100644 --- a/documentation/migration-guides/release-notes-5.2.rst +++ b/documentation/migration-guides/release-notes-5.2.rst @@ -383,7 +383,7 @@ New Features / Enhancements in |yocto-ver| was left off in the previous execution. - ``knotty`` now hints the user if :term:`MACHINE` was not set in - the ``local.conf`` file. + the :ref:`structure-build-conf-local.conf` file. - ``utils``: add Go mod h1 checksum support, specific to Go modules. Use with ``goh1``. diff --git a/documentation/migration-guides/release-notes-6.0.rst b/documentation/migration-guides/release-notes-6.0.rst index 1ce7d5120..5ae78daf0 100644 --- a/documentation/migration-guides/release-notes-6.0.rst +++ b/documentation/migration-guides/release-notes-6.0.rst @@ -451,7 +451,7 @@ New Features / Enhancements in |yocto-ver| - Share :ref:`overview-manual/concepts:Shared State` by default between builds, by adding a definition for :term:`SSTATE_DIR` and - :term:`BB_HASHSERVE_DB_DIR` in the ``site.conf`` file created by + :term:`BB_HASHSERVE_DB_DIR` in the :ref:`structure-build-conf-auto.conf` file created by :ref:`bitbake:ref-bbsetup-command-init` (:bitbake_rev:`a70c336790a9188aae67975fac6ca13579ad1d3e`) diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index e0e3c0398..3bf672c78 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst @@ -273,23 +273,23 @@ Here is a non-exhaustive list: .. note:: - Configurations set in the ``conf/local.conf`` file can also be set - in the ``conf/site.conf`` and ``conf/auto.conf`` configuration files. + Configurations set in the :ref:`structure-build-conf-local.conf` file can also be set + in the :ref:`structure-build-conf-site.conf` and :ref:`structure-build-conf-auto.conf` configuration files. -The ``bblayers.conf`` file tells BitBake what layers you want considered +The :ref:`structure-build-conf-bblayers.conf` file tells BitBake what layers you want considered during the build. By default, the layers listed in this file include layers minimally needed by the build system. However, you must manually add any custom layers you have created. You can find more information on -working with the ``bblayers.conf`` file in the +working with the :ref:`structure-build-conf-bblayers.conf` file in the ":ref:`dev-manual/layers:enabling your layer`" section in the Yocto Project Development Tasks Manual. -The files ``site.conf`` and ``auto.conf`` are not created by the -environment initialization script. If you want the ``site.conf`` file, -you need to create it yourself. The ``auto.conf`` file is typically +The files ``site.conf`` and :ref:`structure-build-conf-auto.conf` are not created by the +environment initialization script. If you want the :ref:`structure-build-conf-auto.conf` file, +you need to create it yourself. The :ref:`structure-build-conf-auto.conf` file is typically created by an autobuilder: -- *site.conf:* You can use the ``conf/site.conf`` configuration +- *site.conf:* You can use the :ref:`structure-build-conf-site.conf` configuration file to configure multiple build directories. For example, suppose you had several build environments and they shared some common features. You can set these default build properties here. A good @@ -298,7 +298,7 @@ created by an autobuilder: - *auto.conf:* The file is usually created and written to by an autobuilder. The settings put into the file are typically the same as - you would find in the ``conf/local.conf`` or the ``conf/site.conf`` + you would find in the :ref:`structure-build-conf-local.conf` or the :ref:`structure-build-conf-site.conf` files. You can edit all configuration files to further define any particular @@ -309,16 +309,16 @@ When you launch your build with the ``bitbake target`` command, BitBake sorts out the configurations to ultimately define your build environment. It is important to understand that the :term:`OpenEmbedded Build System` reads the -configuration files in a specific order: ``site.conf``, ``auto.conf``, -and ``local.conf``. And, the build system applies the normal assignment +configuration files in a specific order: ``site.conf``, :ref:`structure-build-conf-auto.conf`, +and :ref:`structure-build-conf-local.conf`. And, the build system applies the normal assignment statement rules as described in the ":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" chapter of the BitBake User Manual. Because the files are parsed in a specific order, variable assignments for the same variable could be affected. For -example, if the ``auto.conf`` file and the ``local.conf`` set variable1 -to different values, because the build system parses ``local.conf`` -after ``auto.conf``, variable1 is assigned the value from the -``local.conf`` file. +example, if the :ref:`structure-build-conf-auto.conf` file and the ``local.conf`` set variable1 +to different values, because the build system parses :ref:`structure-build-conf-local.conf` +after :ref:`structure-build-conf-auto.conf`, variable1 is assigned the value from the +:ref:`structure-build-conf-local.conf` file. Metadata, Machine Configuration, and Policy Configuration --------------------------------------------------------- @@ -389,7 +389,7 @@ Repositories <>` also shows layers categorized under "Yocto Metadata Layers." found in the OpenEmbedded Layer Index. Such layers are either deprecated or experimental in nature. -BitBake uses the ``conf/bblayers.conf`` file, which is part of the user +BitBake uses the :ref:`structure-build-conf-bblayers.conf` file, which is part of the user configuration, to find what layers it should be using as part of the build. @@ -400,7 +400,7 @@ A distribution layer provides policy configurations for your distribution. Best practices dictate that you isolate these types of configurations into their own layer. Settings you provide in ``conf/distro/distro.conf`` override similar settings that BitBake finds -in your ``conf/local.conf`` file in the :term:`Build Directory`. +in your :ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`. The following list provides some explanation and references for what you typically find in a distribution layer (recall that @@ -538,7 +538,7 @@ source tree used by the group). The canonical method through which to include a local project is to use the :ref:`ref-classes-externalsrc` class to include that local project. You use -either ``local.conf`` or a recipe's append file to override or set the +either :ref:`structure-build-conf-local.conf` or a recipe's append file to override or set the recipe to point to the local directory from which to fetch the source. Source Control Managers (Optional) diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst index 6241dffcb..e0c7fd5e5 100644 --- a/documentation/profile-manual/intro.rst +++ b/documentation/profile-manual/intro.rst @@ -43,7 +43,7 @@ an ``sdk`` image, perhaps one of:: $ bitbake core-image-rt-sdk Alternatively, you can add ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` line in -your ``local.conf`` file:: +your :ref:`structure-build-conf-local.conf` file:: EXTRA_IMAGE_FEATURES:append = " tools-profile" @@ -59,7 +59,7 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.: You can prevent that by setting the :term:`INHIBIT_PACKAGE_STRIP` - variable to "1" in your ``local.conf`` when you build the image:: + variable to "1" in your :ref:`structure-build-conf-local.conf` when you build the image:: INHIBIT_PACKAGE_STRIP = "1" @@ -69,11 +69,11 @@ If you've already built a stripped image, you can generate debug packages (xxx-dbg) which you can manually install as needed. To generate debug info for packages, you can add ``dbg-pkgs`` to -:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example:: +:term:`EXTRA_IMAGE_FEATURES` in :ref:`structure-build-conf-local.conf`. For example:: EXTRA_IMAGE_FEATURES:append = " dbg-pkgs" Additionally, in order to generate the right type of debug info, we also need to -set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file:: +set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the :ref:`structure-build-conf-local.conf` file:: PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index ec768b755..eb28c794d 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -2708,7 +2708,7 @@ It is used to generate a JSON specification file from the features listed in The :ref:`ref-classes-sanity` class checks to see if prerequisite software is present on the host system so that users can be notified of potential problems that might affect their build. The class also performs basic user -configuration checks from the ``local.conf`` configuration file to +configuration checks from the :ref:`structure-build-conf-local.conf` configuration file to prevent common mistakes that cause build failures. Distribution policy usually determines whether to include this class. diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst index 6b21d302f..d2e80611a 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst @@ -312,7 +312,7 @@ the layer into which to write an append file:: The ``*.bbappend`` file is created at the appropriate path within the specified layer directory, which may or may -not be in your ``bblayers.conf`` file. If an append file already exists, +not be in your :ref:`structure-build-conf-bblayers.conf` file. If an append file already exists, the command updates it appropriately. .. _devtool-checking-on-the-upgrade-status-of-a-recipe: diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst index ff103a55e..676d274c9 100644 --- a/documentation/ref-manual/structure.rst +++ b/documentation/ref-manual/structure.rst @@ -116,7 +116,7 @@ and so forth.) This directory adds additional recipes and append files used by the OpenEmbedded selftests to verify the behavior of the build system. You -do not have to add this layer to your ``bblayers.conf`` file unless you +do not have to add this layer to your :ref:`structure-build-conf-bblayers.conf` file unless you want to run the selftests. .. _structure-meta-skeleton: @@ -310,7 +310,7 @@ file, it is recommended to put them into a distro :term:`configuration file`, or to create layer :term:`configuration fragments ` from changes made here. -The :term:`OpenEmbedded Build System` can create the ``local.conf`` file from a +The :term:`OpenEmbedded Build System` can create the :ref:`structure-build-conf-local.conf` file from a ``local.conf.sample`` file when you ``source`` the top-level build environment setup script :ref:`structure-core-script`. @@ -343,7 +343,7 @@ file, it uses ``sed`` to substitute final This configuration file defines :ref:`layers `, which are directory trees, traversed (or walked) by BitBake. The -``bblayers.conf`` file uses the :term:`BBLAYERS` +:ref:`structure-build-conf-bblayers.conf` file uses the :term:`BBLAYERS` variable to list the layers BitBake tries to find. The OpenEmbedded build system can create it from a ``bblayers.conf.sample`` file @@ -382,7 +382,7 @@ want to access downloaded files (:term:`DL_DIR`). This file can be shared for multiple build directories. For example, :doc:`bitbake-setup ` makes the :ref:`structure-build-conf-site.conf` file a symbolic link to a common -``site.conf`` file:: +:ref:`structure-build-conf-auto.conf` file:: ├── poky-master-poky-distro_poky-machine_qemux86-64/ │   └── build/ @@ -831,9 +831,9 @@ For reference information on classes, see the This directory contains the core set of configuration files that start from ``bitbake.conf`` and from which all other configuration files are included. See the include statements at the end of the ``bitbake.conf`` -file and you will note that even ``local.conf`` is loaded from there. +file and you will note that even :ref:`structure-build-conf-local.conf` is loaded from there. While ``bitbake.conf`` sets up the defaults, you can often override -these by using the (``local.conf``) file, machine file or the +these by using the (:ref:`structure-build-conf-local.conf`) file, machine file or the distribution configuration file. .. _structure-meta-conf-machine: diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index 7c2ae896f..0310d27f8 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst @@ -266,11 +266,11 @@ universal, the list includes them just in case: :term:`Container Layer` A flexible definition that typically refers to a single Git checkout which contains multiple (and typically related) sub-layers which can - be included independently in your project's ``bblayers.conf`` file. + be included independently in your project's :ref:`structure-build-conf-bblayers.conf` file. In some cases, such as with OpenEmbedded's :oe_git:`meta-openembedded ` layer, the top level ``meta-openembedded/`` directory is not itself an actual layer, - so you would never explicitly include it in a ``bblayers.conf`` file; + so you would never explicitly include it in a :ref:`structure-build-conf-bblayers.conf` file; rather, you would include any number of its layer subdirectories, such as :oe_git:`meta-oe `, :oe_git:`meta-python ` and so on. @@ -279,7 +279,7 @@ universal, the list includes them just in case: :yocto_git:`meta-security `) have a top-level directory that is itself an actual layer, as well as a variety of sub-layers, both of which could be included in your - ``bblayers.conf`` file. + :ref:`structure-build-conf-bblayers.conf` file. In either case, the phrase "container layer" is simply used to describe a directory structure which contains multiple valid OpenEmbedded layers. diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index c04b24ce0..8e67acaaf 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -432,7 +432,7 @@ system and gives an overview of their function and contents. you to control the build based on these parameters. Disk space monitoring is disabled by default. To enable monitoring, - add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file + add the :term:`BB_DISKMON_DIRS` variable to your :ref:`structure-build-conf-local.conf` file found in the :term:`Build Directory`. Use the following form: @@ -480,7 +480,7 @@ system and gives an overview of their function and contents. The first example works only if you also provide the :term:`BB_DISKMON_WARNINTERVAL` - variable in the ``conf/local.conf``. This example causes the build + variable in the :ref:`structure-build-conf-local.conf`. This example causes the build system to immediately stop when either the disk space in ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops below 100 Kbytes. Because two directories are provided with the @@ -501,7 +501,7 @@ system and gives an overview of their function and contents. :term:`BB_DISKMON_WARNINTERVAL` Defines the disk space and free inode warning intervals. To set these - intervals, define the variable in your ``conf/local.conf`` file in + intervals, define the variable in your :ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`. If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you @@ -721,7 +721,7 @@ system and gives an overview of their function and contents. server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how long the BitBake server stays resident between invocations. - For example, the following statement in your ``local.conf`` file + For example, the following statement in your :ref:`structure-build-conf-local.conf` file instructs the server to be unloaded after 20 seconds of inactivity:: BB_SERVER_TIMEOUT = "20" @@ -885,7 +885,7 @@ system and gives an overview of their function and contents. :term:`BBLAYERS` Lists the layers to enable during the build. This variable is defined - in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. + in the :ref:`structure-build-conf-bblayers.conf` configuration file in the :term:`Build Directory`. Here is an example:: BBLAYERS = " \ @@ -1981,7 +1981,7 @@ system and gives an overview of their function and contents. :term:`COREBASE_FILES` Lists files from the :term:`COREBASE` directory that should be copied other than the layers listed in the - ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows + :ref:`structure-build-conf-bblayers.conf` file. The :term:`COREBASE_FILES` variable allows to copy metadata from the OpenEmbedded build system into the extensible SDK. @@ -2626,7 +2626,7 @@ system and gives an overview of their function and contents. variable. You can set this directory by defining the :term:`DL_DIR` variable in the - ``conf/local.conf`` file. This directory is self-maintaining and you + :ref:`structure-build-conf-local.conf` file. This directory is self-maintaining and you should not have to touch it. By default, the directory is ``downloads`` in the :term:`Build Directory`:: @@ -2819,7 +2819,7 @@ system and gives an overview of their function and contents. Directs BitBake to exclude a recipe from world builds (i.e. ``bitbake world``). During world builds, BitBake locates, parses and builds all recipes found in every layer exposed in the - ``bblayers.conf`` configuration file. + :ref:`structure-build-conf-bblayers.conf` configuration file. To exclude a recipe from a world build using this variable, set the variable to "1" in the recipe. @@ -3868,7 +3868,7 @@ system and gives an overview of their function and contents. If you specifically remove the locale ``en_US.UTF-8``, you must set :term:`IMAGE_LINGUAS` appropriately. - You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file for + You can set :term:`GLIBC_GENERATE_LOCALES` in your :ref:`structure-build-conf-local.conf` file for local testing or in your distro :term:`configuration file`. By default, all locales are generated:: @@ -4327,7 +4327,7 @@ system and gives an overview of their function and contents. :term:`IMAGE_FEATURES` The primary list of features to include in an image. Typically, you configure this variable in an image recipe. Although you can use this - variable from your ``local.conf`` file, which is found in the + variable from your :ref:`structure-build-conf-local.conf` file, which is found in the :term:`Build Directory`, best practices dictate that you do not. @@ -4415,7 +4415,7 @@ system and gives an overview of their function and contents. - Using :term:`IMAGE_INSTALL` with the :ref:`+= ` - BitBake operator within the ``/conf/local.conf`` file or from + BitBake operator within the :ref:`structure-build-conf-local.conf` file or from within an image recipe is not recommended. Use of this operator in these ways can cause ordering issues. Since :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a @@ -4423,7 +4423,7 @@ system and gives an overview of their function and contents. :ref:`?= ` operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` results in unexpected behavior when used within - ``conf/local.conf``. Furthermore, the same operation from within an + :ref:`structure-build-conf-local.conf`. Furthermore, the same operation from within an image recipe may or may not succeed depending on the specific situation. In both these cases, the behavior is contrary to how most users expect the ``+=`` operator to work. @@ -7074,7 +7074,7 @@ system and gives an overview of their function and contents. Consider the following example where the :term:`PACKAGE_FEED_URIS`, :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are - defined in your ``local.conf`` file:: + defined in your :ref:`structure-build-conf-local.conf` file:: PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ https://example.com/packagerepos/updates" @@ -7103,7 +7103,7 @@ system and gives an overview of their function and contents. Consider the following example where the :term:`PACKAGE_FEED_URIS`, :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are - defined in your ``local.conf`` file:: + defined in your :ref:`structure-build-conf-local.conf` file:: PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ https://example.com/packagerepos/updates" @@ -7132,7 +7132,7 @@ system and gives an overview of their function and contents. Consider the following example where the :term:`PACKAGE_FEED_URIS`, :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are - defined in your ``local.conf`` file:: + defined in your :ref:`structure-build-conf-local.conf` file:: PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ https://example.com/packagerepos/updates" @@ -7507,7 +7507,7 @@ system and gives an overview of their function and contents. places you in the right location so that you can manually resolve the conflicts. - Set this variable in your ``local.conf`` file. + Set this variable in your :ref:`structure-build-conf-local.conf` file. :term:`PATCHTOOL` Specifies the utility used to apply patches for a recipe during the @@ -7898,7 +7898,7 @@ system and gives an overview of their function and contents. Typically, you could add a specific server for the build system to attempt before any others by adding something like the following to - the ``local.conf`` configuration file in the + the :ref:`structure-build-conf-site.conf` configuration file in the :term:`Build Directory`:: PREMIRRORS:prepend = "\ @@ -8629,7 +8629,7 @@ system and gives an overview of their function and contents. ROOT_HOME ?= "/root" You can also override the default by setting the variable in your distro - configuration or in the ``local.conf`` file. + configuration or in the :ref:`structure-build-conf-local.conf` file. :term:`ROOTFS` Indicates a filesystem image to include as the root filesystem. @@ -9382,7 +9382,7 @@ system and gives an overview of their function and contents. build the recipe. To prevent a recipe from being built, use the :term:`SKIP_RECIPE` - variable in your ``local.conf`` file or distribution configuration. + variable in your :ref:`structure-build-conf-local.conf` file or distribution configuration. Here is an example which prevents ``myrecipe`` from being built:: SKIP_RECIPE[myrecipe] = "Not supported by our organization." @@ -10961,8 +10961,8 @@ system and gives an overview of their function and contents. The layer's ``README`` file contains information on how to use the Sourcery G++ Toolchain as an external toolchain. You will have to - add the layer to your ``bblayers.conf`` file and then set the - :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to + add the layer to your :ref:`structure-build-conf-bblayers.conf` file and then set the + :term:`EXTERNAL_TOOLCHAIN` variable in your :ref:`structure-build-conf-local.conf` file to the location of the toolchain. The fundamentals used for this example apply to any external diff --git a/documentation/ref-manual/varlocality.rst b/documentation/ref-manual/varlocality.rst index 29ab6081c..855bd6938 100644 --- a/documentation/ref-manual/varlocality.rst +++ b/documentation/ref-manual/varlocality.rst @@ -74,7 +74,7 @@ Local ----- This section lists variables whose configuration context is the local -configuration through the ``local.conf`` file. +configuration through the :ref:`structure-build-conf-local.conf` file. - :term:`DISTRO` (can also be set by the :ref:`ref-fragments-builtin-core-distro` :term:`built-in fragment`) diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst index 65fd4af9f..5392b1200 100644 --- a/documentation/sdk-manual/appendix-customizing.rst +++ b/documentation/sdk-manual/appendix-customizing.rst @@ -53,7 +53,7 @@ build system applies them against :ref:`structure-build-conf-local.conf` and class. Additionally, the contents of ``conf/sdk-extra.conf``, when present, are -appended to the end of ``conf/local.conf`` within the produced SDK, +appended to the end of :ref:`structure-build-conf-local.conf` within the produced SDK, without any filtering. The ``sdk-extra.conf`` file is particularly useful if you want to set a variable value just for the SDK and not the OpenEmbedded build system used to create the SDK. @@ -114,7 +114,7 @@ adjustments: - If you have adjusted the list of files and directories that appear in :term:`COREBASE` (other than - layers that are enabled through ``bblayers.conf``), then you must + layers that are enabled through :ref:`structure-build-conf-bblayers.conf`), then you must list these files in :term:`COREBASE_FILES` so that the files are copied into the SDK. @@ -287,7 +287,7 @@ source, you need to do a number of things: SDK and the SDK itself (i.e. the mirror is accessible in both places or it will fail quickly on the OpenEmbedded build system side, and its contents will not interfere with the build), then - you can set the variable in your ``local.conf`` or custom distro + you can set the variable in your :ref:`structure-build-conf-local.conf` or custom distro configuration file. You can then pass the variable to the SDK by adding the following: diff --git a/documentation/security-manual/securing-images.rst b/documentation/security-manual/securing-images.rst index 9772b52d3..3aa55c2aa 100644 --- a/documentation/security-manual/securing-images.rst +++ b/documentation/security-manual/securing-images.rst @@ -80,7 +80,7 @@ your build output more secure. The security flags are in the Depending on the recipe, certain security flags are enabled and disabled by default. -Use the following line in your ``local.conf`` file or in your custom +Use the following line in your :ref:`structure-build-conf-local.conf` file or in your custom distro :term:`configuration file` to enable the security compiler and linker flags for your build:: diff --git a/documentation/test-manual/runtime-testing.rst b/documentation/test-manual/runtime-testing.rst index 4eef9d059..55c19900f 100644 --- a/documentation/test-manual/runtime-testing.rst +++ b/documentation/test-manual/runtime-testing.rst @@ -223,7 +223,7 @@ The final thing you need to do when setting :term:`TEST_TARGET` to "SystemdbootTarget" is to set up the test image: #. *Set up your local.conf file:* Make sure you have the following - statements in your ``local.conf`` file:: + statements in your :ref:`structure-build-conf-local.conf` file:: IMAGE_FSTYPES += "tar.gz" IMAGE_CLASSES += "testimage" @@ -244,7 +244,7 @@ power: :term:`TEST_POWERCONTROL_EXTRA_ARGS` as a command that runs on the host and does power cycling. The test code passes one argument to that command: off, on or cycle (off then on). Here is an example that - could appear in your ``local.conf`` file:: + could appear in your :ref:`structure-build-conf-local.conf` file:: TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1" @@ -318,7 +318,7 @@ You can start the tests automatically or manually: - *Automatically running tests:* To run the tests automatically after the OpenEmbedded build system successfully creates an image, first set the - :term:`TESTIMAGE_AUTO` variable to "1" in your ``local.conf`` file in the + :term:`TESTIMAGE_AUTO` variable to "1" in your :ref:`structure-build-conf-local.conf` file in the :term:`Build Directory`:: TESTIMAGE_AUTO = "1" @@ -330,7 +330,7 @@ You can start the tests automatically or manually: - *Manually running tests:* To manually run the tests, first globally inherit the :ref:`ref-classes-testimage` class by editing your - ``local.conf`` file:: + :ref:`structure-build-conf-local.conf` file:: IMAGE_CLASSES += "testimage" @@ -346,7 +346,7 @@ individual tests. Tests are usually grouped together by the area tested You can add tests to any layer provided you place them in the proper area and you extend :term:`BBPATH` in -the ``local.conf`` file as normal. Be sure that tests reside in +the :ref:`structure-build-conf-local.conf` file as normal. Be sure that tests reside in ``layer/lib/oeqa/runtime/cases``. .. note:: @@ -356,7 +356,7 @@ the ``local.conf`` file as normal. Be sure that tests reside in You can change the set of tests run by appending or overriding :term:`TEST_SUITES` variable in -``local.conf``. Each name in :term:`TEST_SUITES` represents a required test +:ref:`structure-build-conf-local.conf`. Each name in :term:`TEST_SUITES` represents a required test for the image. Test modules named within :term:`TEST_SUITES` cannot be skipped even if a test is not suitable for an image (e.g. running the RPM tests on an image without ``rpm``). Appending "auto" to @@ -401,7 +401,7 @@ test execution off to a scheduler. You can only export tests that are defined in :term:`TEST_SUITES`. If your image is already built, make sure the following are set in your -``local.conf`` file:: +:ref:`structure-build-conf-local.conf` file:: IMAGE_CLASSES += "testexport" TEST_TARGET_IP = "IP-address-for-the-test-target" diff --git a/documentation/test-manual/understand-autobuilder.rst b/documentation/test-manual/understand-autobuilder.rst index 0015c2e57..e65490607 100644 --- a/documentation/test-manual/understand-autobuilder.rst +++ b/documentation/test-manual/understand-autobuilder.rst @@ -58,7 +58,7 @@ Combining these two entries you can see that ``qemux86-64`` is a three step build where ``bitbake BBTARGETS`` would be run, then ``bitbake SANITYTARGETS`` for each step; all for ``MACHINE="qemux86-64"`` but with differing :term:`SDKMACHINE` settings. In step 1, an extra variable is added to the -``auto.conf`` file to enable wic image generation. +:ref:`structure-build-conf-auto.conf` file to enable wic image generation. While not every detail of this is covered here, you can see how the template mechanism allows quite complex configurations to be built up @@ -222,7 +222,7 @@ following: ``bitbake-layers add-layer`` command (logging as stepXa) #. Call the ``scripts/setup-config`` script to generate the necessary - ``auto.conf`` configuration file for the build + :ref:`structure-build-conf-auto.conf` configuration file for the build #. Run the ``bitbake BBTARGETS`` command (logging as stepXb) diff --git a/documentation/toaster-manual/reference.rst b/documentation/toaster-manual/reference.rst index 08e8a12e0..d0c63a084 100644 --- a/documentation/toaster-manual/reference.rst +++ b/documentation/toaster-manual/reference.rst @@ -32,7 +32,7 @@ through a :wikipedia:`REST ` API, store the information about the layers in the Toaster database, and then show the information to users. Users are then able to view that information and build layers from Toaster itself without having to -clone or edit the BitBake layers configuration file ``bblayers.conf``. +clone or edit the BitBake layers configuration file :ref:`structure-build-conf-bblayers.conf`. Tying a layer source into Toaster is convenient when you have many custom layers that need to be built on a regular basis by a community of diff --git a/documentation/transitioning-to-a-custom-environment.rst b/documentation/transitioning-to-a-custom-environment.rst index 13f906eea..4b54be804 100644 --- a/documentation/transitioning-to-a-custom-environment.rst +++ b/documentation/transitioning-to-a-custom-environment.rst @@ -66,7 +66,7 @@ Transitioning to a custom environment for systems development 64-bit x86-based machine, copy the conf/intel-corei7-64 definition and give the machine a relevant name (think board name, not product name). Make sure the layer configuration is dependent on the ``meta-intel`` layer (or at least, - ``meta-intel`` remains in your ``bblayers.conf`` file). Now you can put your custom BSP + ``meta-intel`` remains in your :ref:`structure-build-conf-bblayers.conf` file). Now you can put your custom BSP settings into your layer and you can re-use it for different applications. #. **Write your own recipe to build additional software support that isn't