Merge branch 'master' into m9-performance-test-report-view

bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables-context.rst

@@ -0,0 +1,91 @@
+.. SPDX-License-Identifier: CC-BY-2.5
+
+================
+Variable Context
+================
+
+|
+
+Variables might only have an impact or can be used in certain contexts. Some
+should only be used in global files like ``.conf``, while others are intended only
+for local files like ``.bb``. This chapter aims to describe some important variable
+contexts.
+
+.. _ref-varcontext-configuration:
+
+BitBake's own configuration
+===========================
+
+Variables starting with ``BB_`` usually configure the behaviour of BitBake itself.
+For example, one could configure:
+
+- System resources, like disk space to be used (:term:`BB_DISKMON_DIRS`),
+  or the number of tasks to be run in parallel by BitBake (:term:`BB_NUMBER_THREADS`).
+
+- How the fetchers shall behave, e.g., :term:`BB_FETCH_PREMIRRORONLY` is used
+  by BitBake to determine if BitBake's fetcher shall search only
+  :term:`PREMIRRORS` for files.
+
+Those variables are usually configured globally.
+
+BitBake configuration
+=====================
+
+There are variables:
+
+- Like :term:`B` or :term:`T`, that are used to specify directories used by
+  BitBake during the build of a particular recipe. Those variables are
+  specified in ``bitbake.conf``. Some, like :term:`B`, are quite often
+  overwritten in recipes.
+
+- Starting with ``FAKEROOT``, to configure how the ``fakeroot`` command is
+  handled. Those are usually set by ``bitbake.conf`` and might get adapted in a
+  ``bbclass``.
+
+- Detailing where BitBake will store and fetch information from, for
+  data reuse between build runs like :term:`CACHE`, :term:`DL_DIR` or
+  :term:`PERSISTENT_DIR`. Those are usually global.
+
+
+Layers and files
+================
+
+Variables starting with ``LAYER`` configure how BitBake handles layers.
+Additionally, variables starting with ``BB`` configure how layers and files are
+handled. For example:
+
+- :term:`LAYERDEPENDS` is used to configure on which layers a given layer
+  depends.
+
+- The configured layers are contained in :term:`BBLAYERS` and files in
+  :term:`BBFILES`.
+
+Those variables are often used in the files ``layer.conf`` and ``bblayers.conf``.
+
+Recipes and packages
+====================
+
+Variables handling recipes and packages can be split into:
+
+- :term:`PN`, :term:`PV` or :term:`PF` for example, contain information about
+  the name or revision of a recipe or package. Usually, the default set in
+  ``bitbake.conf`` is used, but those are from time to time overwritten in
+  recipes.
+
+- :term:`SUMMARY`, :term:`DESCRIPTION`, :term:`LICENSE` or :term:`HOMEPAGE`
+  contain the expected information and should be set specifically for every
+  recipe.
+
+- In recipes, variables are also used to control build and runtime
+  dependencies between recipes/packages with other recipes/packages. The
+  most common should be: :term:`PROVIDES`, :term:`RPROVIDES`, :term:`DEPENDS`,
+  and :term:`RDEPENDS`.
+
+- There are further variables starting with ``SRC`` that specify the sources in
+  a recipe like :term:`SRC_URI` or :term:`SRCDATE`. Those are also usually set
+  in recipes.
+
+- Which version or provider of a recipe should be given preference when
+  multiple recipes would provide the same item, is controlled by variables
+  starting with ``PREFERRED_``. Those are normally set in the configuration
+  files of a ``MACHINE`` or ``DISTRO``.

bitbake/doc/index.rst

@@ -13,6 +13,7 @@ BitBake User Manual
    bitbake-user-manual/bitbake-user-manual-intro
    bitbake-user-manual/bitbake-user-manual-execution
    bitbake-user-manual/bitbake-user-manual-metadata
+   bitbake-user-manual/bitbake-user-manual-ref-variables-context
    bitbake-user-manual/bitbake-user-manual-fetching
    bitbake-user-manual/bitbake-user-manual-ref-variables
    bitbake-user-manual/bitbake-user-manual-hello

bitbake/lib/bb/fetch2/wget.py

@@ -87,7 +87,10 @@ def urldata_init(self, ud, d):
         if not ud.localfile:
             ud.localfile = d.expand(urllib.parse.unquote(ud.host + ud.path).replace("/", "."))
 
-        self.basecmd = d.getVar("FETCHCMD_wget") or "/usr/bin/env wget -t 2 -T 30 --passive-ftp"
+        self.basecmd = d.getVar("FETCHCMD_wget") or "/usr/bin/env wget -t 2 -T 30"
+
+        if ud.type == 'ftp' or ud.type == 'ftps':
+            self.basecmd += " --passive-ftp"
 
         if not self.check_certs(d):
             self.basecmd += " --no-check-certificate"

documentation/Makefile

@@ -53,9 +53,8 @@ stylecheck:
 	vale sync
 	vale $(VALEOPTS) $(VALEDOCS)
 
-stylecheck:
-	vale sync
-	vale $(VALEOPTS) $(VALEDOCS)
+sphinx-lint:
+	sphinx-lint $(SOURCEDIR)
 
 epub: $(PNGs)
 	$(SOURCEDIR)/set_versions.py

documentation/README

@@ -165,6 +165,20 @@ To run Vale:
 
  $ make stylecheck
 
+Link checking the Yocto Project documentation
+=============================================
+
+To fix errors which are not reported by Sphinx itself,
+the project uses sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint).
+
+To install sphinx-lint:
+
+ $ pip install sphinx-lint
+
+To run sphinx-lint:
+
+ $ make sphinx-lint
+
 Sphinx theme and CSS customization
 ==================================
 

documentation/conf.py

@@ -159,8 +159,8 @@
 html_secnumber_suffix = " "
 
 latex_elements = {
-    'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
-    'preamble': '\setcounter{tocdepth}{2}',
+    'passoptionstopackages': '\\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
+    'preamble': '\\setcounter{tocdepth}{2}',
 }
 
 # Make the EPUB builder prefer PNG to SVG because of issues rendering Inkscape SVG

documentation/contributor-guide/submit-changes.rst

@@ -440,7 +440,7 @@ varies by component:
 
 For changes to other layers and tools hosted in the Yocto Project source
 repositories (i.e. :yocto_git:`git.yoctoproject.org <>`), use the
-:yocto_lists:`yocto </g/yocto/>` general mailing list.
+:yocto_lists:`yocto-patches </g/yocto-patches/>` general mailing list.
 
 For changes to other layers hosted in the OpenEmbedded source
 repositories (i.e. :oe_git:`git.openembedded.org <>`), use

documentation/dev-manual/init-manager.rst

@@ -121,7 +121,7 @@ increasing levels of complexity and functionality:
    :widths: 40 20 20 20
    :header-rows: 1
 
-   * - 
+   * -
      - BusyBox init
      - SysVinit
      - systemd

documentation/dev-manual/layers.rst

@@ -732,7 +732,7 @@ The following list describes the available commands:
 
 -  ``save-build-conf``: Saves the currently active build configuration
    (``conf/local.conf``, ``conf/bblayers.conf``) as a template into a layer.
-   This template can later be used for setting up builds via :term:``TEMPLATECONF``.
+   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`".
 

documentation/dev-manual/start.rst

@@ -619,7 +619,7 @@ containing the release you wish to use, for example
 
 You will find there source archives of individual components (if you wish
 to use them individually), and of the corresponding Poky release bundling
-a selection of these components. 
+a selection of these components.
 
 .. note::
 

documentation/dev-manual/wic.rst

@@ -146,7 +146,7 @@ command to return the available Wic images as follows::
      qemuloongarch                 		Create qcow2 image for LoongArch QEMU machines
      directdisk-multi-rootfs       		Create multi rootfs image using rootfs plugin
      directdisk                    		Create a 'pcbios' direct disk image
-     efi-bootdisk                  		
+     efi-bootdisk
      mkhybridiso                   		Create a hybrid ISO image
      directdisk-gpt                		Create a 'pcbios' direct disk image
      systemd-bootdisk              		Create an EFI disk image with systemd-boot
@@ -289,7 +289,7 @@ Use the following command to list the available kickstart files::
      qemuloongarch                 		Create qcow2 image for LoongArch QEMU machines
      directdisk-multi-rootfs       		Create multi rootfs image using rootfs plugin
      directdisk                    		Create a 'pcbios' direct disk image
-     efi-bootdisk                  		
+     efi-bootdisk
      mkhybridiso                   		Create a hybrid ISO image
      directdisk-gpt                		Create a 'pcbios' direct disk image
      systemd-bootdisk              		Create an EFI disk image with systemd-boot

documentation/kernel-dev/common.rst

@@ -315,11 +315,7 @@ home directory:
 
 #. *Create Structure*: Create the layer's structure::
 
-      $ mkdir meta-mylayer
-      $ mkdir meta-mylayer/conf
-      $ mkdir meta-mylayer/recipes-kernel
-      $ mkdir meta-mylayer/recipes-kernel/linux
-      $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
+      $ mkdir -p meta-mylayer/conf meta-mylayer/recipes-kernel/linux/linux-yocto
 
    The ``conf`` directory holds your configuration files, while the
    ``recipes-kernel`` directory holds your append file and eventual
@@ -964,9 +960,7 @@ Section.
    additional structure to your layer using the following commands::
 
       $ cd ~/meta-mylayer
-      $ mkdir recipes-kernel
-      $ mkdir recipes-kernel/linux
-      $ mkdir recipes-kernel/linux/linux-yocto
+      $ mkdir -p recipes-kernel recipes-kernel/linux/linux-yocto
 
    Once you have created this
    hierarchy in your layer, you can move the patch file using the

documentation/migration-guides/migration-4.0.rst

@@ -68,7 +68,7 @@ changes and you need to review them before committing. An example warning
 looks like::
 
     poky/scripts/lib/devtool/upgrade.py needs further work at line 275 since it contains abort
-    
+
 Fetching changes
 ~~~~~~~~~~~~~~~~
 
@@ -111,7 +111,7 @@ License changes
   If they do not, by default a warning will be shown. A
   :oe_git:`convert-spdx-licenses.py </openembedded-core/tree/scripts/contrib/convert-spdx-licenses.py>`
   script can be used to update your recipes.
-  
+
 - :term:`INCOMPATIBLE_LICENSE` should now use `SPDX identifiers <https://spdx.org/licenses/>`__.
   Additionally, wildcarding is now limited to specifically supported values -
   see the :term:`INCOMPATIBLE_LICENSE` documentation for further information.
@@ -121,7 +121,7 @@ License changes
   which can cause signature issues for users. In addition the ``available_licenses()``
   function has been removed from the :ref:`ref-classes-license` class as
   it is no longer needed.
-  
+
 Removed recipes
 ~~~~~~~~~~~~~~~
 
@@ -136,11 +136,11 @@ The following recipes have been removed in this release:
 
 Python changes
 ~~~~~~~~~~~~~~
-     
+
 - ``distutils`` has been deprecated upstream in Python 3.10 and thus the ``distutils*``
   classes have been moved to ``meta-python``. Recipes that inherit the ``distutils*``
   classes should be updated to inherit ``setuptools*`` equivalents instead.
-  
+
 - The Python package build process is now based on `wheels <https://pythonwheels.com/>`__.
   The new Python packaging classes that should be used are
   :ref:`ref-classes-python_flit_core`, :ref:`ref-classes-python_setuptools_build_meta`
@@ -159,7 +159,7 @@ Prelink removed
 Prelink has been dropped by ``glibc`` upstream in 2.36. It already caused issues with
 binary corruption, has a number of open bugs and is of questionable benefit
 without disabling load address randomization and PIE executables.
-    
+
 We disabled prelinking by default in the honister (3.4) release, but left it able
 to be enabled if desired. However, without glibc support it cannot be maintained
 any further, so all of the prelinking functionality has been removed in this release.
@@ -170,7 +170,7 @@ reference(s).
 Reproducible as standard
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Reproducibility is now considered as standard functionality, thus the 
+Reproducibility is now considered as standard functionality, thus the
 ``reproducible`` class has been removed and its previous contents merged into the
 :ref:`ref-classes-base` class. If you have references in your configuration to
 ``reproducible`` in :term:`INHERIT`, :term:`USER_CLASSES` etc. then they should be
@@ -212,7 +212,7 @@ and :ref:`bitbake-user-manual/bitbake-user-manual-metadata:removal (override sty
 
 Miscellaneous changes
 ~~~~~~~~~~~~~~~~~~~~~
-  
+
 - ``blacklist.bbclass`` is removed and the functionality moved to the
   :ref:`ref-classes-base` class with a more descriptive
   ``varflag`` variable named :term:`SKIP_RECIPE` which will use the `bb.parse.SkipRecipe()`
@@ -252,7 +252,7 @@ Miscellaneous changes
 - The ``cortexa72-crc`` and ``cortexa72-crc-crypto`` tunes have been removed since
   the crc extension is now enabled by default for cortexa72. Replace any references to
   these with ``cortexa72`` and ``cortexa72-crypto`` respectively.
-  
+
 - The Python development shell (previously known as ``devpyshell``) feature has been
   renamed to ``pydevshell``. To start it you should now run::
 
@@ -261,7 +261,7 @@ Miscellaneous changes
 - The ``packagegroups-core-full-cmdline-libs`` packagegroup is no longer produced, as
   libraries should normally be brought in via dependencies. If you have any references
   to this then remove them.
-  
+
 - The :term:`TOPDIR` variable and the current working directory are no longer modified
   when parsing recipes. Any code depending on the previous behaviour will no longer
   work - change any such code to explicitly use appropriate path variables instead.

documentation/migration-guides/migration-4.2.rst

@@ -121,7 +121,7 @@ Removed variables
 The following variables have been removed:
 
 -  ``SERIAL_CONSOLE``, deprecated since version 2.6, replaced by :term:`SERIAL_CONSOLES`.
--  ``PACKAGEBUILDPKGD``, a mostly internal variable in the ref:`ref-classes-package`
+-  ``PACKAGEBUILDPKGD``, a mostly internal variable in the :ref:`ref-classes-package`
    class was rarely used to customise packaging. If you were using this in your custom
    recipes or bbappends, you will need to switch to using :term:`PACKAGE_PREPROCESS_FUNCS`
    or :term:`PACKAGESPLITFUNCS` instead.