summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/bsp-guide/bsp.rst7
-rw-r--r--documentation/conf.py23
-rw-r--r--documentation/dev-manual/common-tasks.rst2
-rw-r--r--documentation/kernel-dev/common.rst2
-rw-r--r--documentation/migration-guides/migration-3.1.rst5
-rw-r--r--documentation/migration-guides/migration-3.4.rst217
-rw-r--r--documentation/migration-guides/migration-general.rst26
-rw-r--r--documentation/overview-manual/yp-intro.rst4
-rw-r--r--documentation/poky.yaml29
-rw-r--r--documentation/ref-manual/classes.rst37
-rw-r--r--documentation/ref-manual/system-requirements.rst11
-rw-r--r--documentation/ref-manual/tasks.rst16
-rw-r--r--documentation/ref-manual/variables.rst47
-rw-r--r--documentation/releases.rst36
-rw-r--r--documentation/sphinx-static/switchers.js7
-rw-r--r--documentation/test-manual/reproducible-builds.rst12
16 files changed, 391 insertions, 90 deletions
diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index 65652ff898..1cc92d721d 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -166,8 +166,9 @@ section.
#. *Determine the BSP Layer You Want:* The Yocto Project supports many
BSPs, which are maintained in their own layers or in layers designed
to contain several BSPs. To get an idea of machine support through
- BSP layers, you can look at the `index of
- machines <&YOCTO_RELEASE_DL_URL;/machines>`__ for the release.
+ BSP layers, you can look at the
+ :yocto_dl:`index of machines </releases/yocto/yocto-&DISTRO;/machines>`
+ for the release.
#. *Optionally Clone the meta-intel BSP Layer:* If your hardware is
based on current Intel CPUs and devices, you can leverage this BSP
@@ -877,7 +878,7 @@ Yocto Project:
your BSP layer as listed in the ``recipes.txt`` file, which is found
in ``poky/meta`` directory of the :term:`Source Directory`
or in the OpenEmbedded-Core Layer (``openembedded-core``) at
- https://git.openembedded.org/openembedded-core/tree/meta.
+ :oe_git:`/openembedded-core/tree/meta`.
You should place recipes (``*.bb`` files) and recipe modifications
(``*.bbappend`` files) into ``recipes-*`` subdirectories by
diff --git a/documentation/conf.py b/documentation/conf.py
index 8e0847938e..22d0dd604a 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -15,8 +15,27 @@
import os
import sys
import datetime
+try:
+ import yaml
+except ImportError:
+ sys.stderr.write("The Yocto Project Sphinx documentation requires PyYAML.\
+ \nPlease make sure to install pyyaml python package.\n")
+ sys.exit(1)
-current_version = "dev"
+# current_version = "dev"
+# bitbake_version = "" # Leave empty for development branch
+# Obtain versions from poky.yaml instead
+with open("poky.yaml") as data:
+ buff = data.read()
+ subst_vars = yaml.safe_load(buff)
+ if "DOCCONF_VERSION" not in subst_vars:
+ sys.stderr.write("Please set DOCCONF_VERSION in poky.yaml")
+ sys.exit(1)
+ current_version = subst_vars["DOCCONF_VERSION"]
+ if "BITBAKE_SERIES" not in subst_vars:
+ sys.stderr.write("Please set BITBAKE_SERIES in poky.yaml")
+ sys.exit(1)
+ bitbake_version = subst_vars["BITBAKE_SERIES"]
# String used in sidebar
version = 'Version: ' + current_version
@@ -90,7 +109,7 @@ extlinks = {
# Intersphinx config to use cross reference with Bitbake user manual
intersphinx_mapping = {
- 'bitbake': ('https://docs.yoctoproject.org/bitbake/', None)
+ 'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
}
# Suppress "WARNING: unknown mimetype for ..."
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 4683b1c045..fa9cd58b37 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -4781,7 +4781,7 @@ configuration would be as follows::
require conf/multilib.conf
MULTILIBS = "multilib:lib32"
DEFAULTTUNE:virtclass-multilib-lib32 = "x86"
- IMAGE_INSTALL:append = "lib32-glib-2.0"
+ IMAGE_INSTALL:append = " lib32-glib-2.0"
This example enables an additional library named
``lib32`` alongside the normal target packages. When combining these
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index d42ca5f99a..631c46631e 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -1062,7 +1062,7 @@ Section.
contents::
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
- SRC_URI:append = "file://0001-calibrate.c-Added-some-printk-statements.patch"
+ SRC_URI:append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements
enable the OpenEmbedded build system to find the patch file.
diff --git a/documentation/migration-guides/migration-3.1.rst b/documentation/migration-guides/migration-3.1.rst
index 80b8f6baa5..a7614e5da4 100644
--- a/documentation/migration-guides/migration-3.1.rst
+++ b/documentation/migration-guides/migration-3.1.rst
@@ -55,8 +55,9 @@ Reproducible builds now enabled by default
In order to avoid unnecessary differences in output files (aiding binary
reproducibility), the Poky distribution configuration
-(``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by
-default.
+(``DISTRO = "poky"``) now inherits the
+:ref:`reproducible-build <ref-classes-reproducible-build>` class
+by default.
.. _migration-3.1-ptest-feature-impact:
diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst
index e83e936b74..8143cd4813 100644
--- a/documentation/migration-guides/migration-3.4.rst
+++ b/documentation/migration-guides/migration-3.4.rst
@@ -7,17 +7,18 @@ Project 3.4 Release (codename "honister") from the prior release.
Override syntax changes
-----------------------
-This release requires changes to the metadata to indicate where overrides are
-being used in variable key names. This is done with the ``:`` character replacing
-the use of ``_`` previously. This means that an entry like::
+In this release, the ``:`` character replaces the use of ``_`` to
+refer to an override, most commonly when making a conditional assignment
+of a variable. This means that an entry like::
SRC_URI_qemux86 = "file://somefile"
-becomes::
+now becomes::
SRC_URI:qemux86 = "file://somefile"
-since ``qemux86`` is an override. This applies to any use of override syntax so::
+since ``qemux86`` is an override. This applies to any use of override
+syntax, so the following::
SRC_URI_append = " file://somefile"
SRC_URI_append_qemux86 = " file://somefile2"
@@ -29,7 +30,7 @@ since ``qemux86`` is an override. This applies to any use of override syntax so:
SRCREV_pn-bash = "abc"
BB_TASK_NICE_LEVEL_task-testimage = '0'
-becomes::
+would now become::
SRC_URI:append = " file://somefile"
SRC_URI:append:qemux86 = " file://somefile2"
@@ -63,8 +64,8 @@ suffix to variables in ``layer.conf`` files such as :term:`BBFILE_PATTERN`,
may be the same as a :term:`DISTRO` override causing some confusion. We do
plan to try and improve consistency as these issues are identified.
-To help with migration of layers there is a script in OE-Core. Once configured
-with the overrides used by a layer, this can be run as::
+To help with migration of layers, a script has been provided in OE-Core.
+Once configured with the overrides used by a layer, this can be run as::
<oe-core>/scripts/contrib/convert-overrides.py <layerdir>
@@ -74,10 +75,198 @@ with the overrides used by a layer, this can be run as::
expected to handle every case. In particular, it needs to be told which overrides
the layer uses (usually machine and distro names/overrides) and the result should
be carefully checked since it can be a little enthusiastic and will convert
- references to ``_append``, ``_remove`` and ``_prepend`` in function and variables names.
+ references to ``_append``, ``_remove`` and ``_prepend`` in function and variable
+ names.
-For reference, this conversion is important as it allows BitBake to know what is
-an override and what is not. This should allow us to proceed with other syntax
-improvements and simplifications for usability. It also means bitbake no longer
-has to guess and maintain large lookup lists just in case ``functionname`` in
-``my_functionname`` is an override and this should improve efficiency.
+For reference, this conversion is important as it allows BitBake to more reliably
+determine what is an override and what is not, as underscores are also used in
+variable names without intending to be overrides. This should allow us to proceed
+with other syntax improvements and simplifications for usability. It also means
+BitBake no longer has to guess and maintain large lookup lists just in case
+e.g. ``functionname`` in ``my_functionname`` is an override, and thus should improve
+efficiency.
+
+
+New host dependencies
+---------------------
+
+The ``lz4c``, ``pzstd`` and ``zstd`` commands are now required to be
+installed on the build host to support LZ4 and Zstandard compression
+functionality. These are typically provided by ``lz4`` and ``zstd``
+packages in most Linux distributions. Alternatively they are available
+as part of ``buildtools-tarball`` if your distribution does not provide
+them. For more information see
+:ref:`ref-manual/system-requirements:required packages for the build host`.
+
+
+Removed recipes
+---------------
+
+The following recipes have been removed in this release:
+
+- ``assimp``: problematic from a licensing perspective and no longer
+ needed by anything else
+- ``clutter-1.0``: legacy component moved to meta-gnome
+- ``clutter-gst-3.0``: legacy component moved to meta-gnome
+- ``clutter-gtk-1.0``: legacy component moved to meta-gnome
+- ``cogl-1.0``: legacy component moved to meta-gnome
+- ``core-image-clutter``: removed along with clutter
+- ``linux-yocto``: removed version 5.4 recipes (5.14 and 5.10 still
+ provided)
+- ``mklibs-native``: not actively tested and upstream mklibs still
+ requires Python 2
+- ``mx-1.0``: obsolete (last release 2012) and isn't used by anything in
+ any known layer
+- ``packagegroup-core-clutter``: removed along with clutter
+
+
+Removed classes
+---------------
+
+- ``clutter``: moved to meta-gnome along with clutter itself
+- ``image-mklibs``: not actively tested and upstream mklibs still
+ requires Python 2
+- ``meta``: no longer useful. Recipes that need to skip installing
+ packages should inherit ``nopackages`` instead.
+
+
+Prelinking disabled by default
+------------------------------
+
+Recent tests have shown that prelinking works only when PIE is not
+enabled (see `here <https://rlbl.me/prelink-1>`__ and `here <https://rlbl.me/prelink-2>`__),
+and as PIE is both a desirable security feature, and the only
+configuration provided and tested by the Yocto Project, there is
+simply no sense in continuing to enable prelink.
+
+There's also a concern that no one is maintaining the code, and there
+are open bugs (including :yocto_bugs:`this serious one </show_bug.cgi?id=14429>`).
+Given that prelink does intricate address arithmetic and rewriting
+of binaries the best option is to disable the feature. It is recommended
+that you consider disabling this feature in your own configuration if
+it is currently enabled.
+
+
+Virtual runtime provides
+------------------------
+
+Recipes shouldn't use the ``virtual/`` string in :term:`RPROVIDES` and
+:term:`RDEPENDS` - it is confusing because ``virtual/`` has no special
+meaning in :term:`RPROVIDES` and :term:`RDEPENDS` (unlike in the
+corresponding build-time :term:`PROVIDES` and :term:`DEPENDS`).
+
+
+Tune files moved to architecture-specific directories
+-----------------------------------------------------
+
+The tune files found in ``conf/machine/include`` have now been moved
+into their respective architecture name directories under that same
+location; e.g. x86 tune files have moved into an ``x86`` subdirectory,
+MIPS tune files have moved into a ``mips`` subdirectory, etc.
+The ARM tunes have an extra level (``armv8a``, ``armv8m``, etc.) and
+some have been renamed to make them uniform with the rest of the tunes.
+See `this commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=1d381f21f5f13aa0c4e1a45683ed656ebeedd37d>`__
+for reference.
+
+If you have any references to tune files (e.g. in custom machine
+configuration files) they will need to be updated.
+
+
+Extensible SDK host extension
+-----------------------------
+
+For a normal SDK, some layers append to :term:`TOOLCHAIN_HOST_TASK`
+unconditionally which is fine, until the eSDK tries to override the
+variable to its own values. Instead of installing packages specified
+in this variable it uses native recipes instead - a very different
+approach. This has led to confusing errors when binaries are added
+to the SDK but not relocated.
+
+To avoid these issues, a new :term:`TOOLCHAIN_HOST_TASK_ESDK` variable has
+been created. If you wish to extend what is installed in the host
+portion of the eSDK then you will now need to set this variable.
+
+
+Package/recipe splitting
+------------------------
+
+- ``perl-cross`` has been split out from the main ``perl`` recipe to
+ its own ``perlcross`` recipe for maintenance reasons. If you have
+ bbappends for the perl recipe then these may need extending.
+
+- The ``wayland`` recipe now packages its binaries in a
+ ``wayland-tools`` package rather than putting them into
+ ``wayland-dev``.
+
+- Xwayland has been split out of the xserver-xorg tree and thus is now
+ in its own ``xwayland`` recipe. If you need Xwayland in your image
+ then you may now need to add it explicitly.
+
+- The ``rpm`` package no longer has ``rpm-build`` in its :term:`RRECOMMENDS`;
+ if by chance you still need rpm package building functionality in
+ your image and you have not already done so then you should add
+ ``rpm-build`` to your image explicitly.
+
+- The Python ``statistics`` standard module is now packaged in its own
+ ``python3-statistics`` package instead of ``python3-misc`` as
+ previously.
+
+
+Image / SDK generation changes
+------------------------------
+
+- Recursive dependencies on the ``do_build`` task are now disabled when
+ building SDKs. These are generally not needed; in the unlikely event
+ that you do encounter problems then it will probably be as a result of
+ missing explicit dependencies that need to be added.
+
+- Errors during "complementary" package installation (e.g. for ``*-dbg``
+ and ``*-dev`` packages) during image construction are no longer
+ ignored. Historically some of these packages had installation problems,
+ that is no longer the case. In the unlikely event that you see errors
+ as a result, you will need to fix the installation/packaging issues.
+
+- When building an image, only packages that will be used in building
+ the image (i.e. the first entry in :term:`PACKAGE_CLASSES`) will be
+ produced if multiple package types are enabled (which is not a typical
+ configuration). If in your CI system you need to have the original
+ behaviour, use ``bitbake --runall build <target>``.
+
+- The ``-lic`` package is no longer automatically added to
+ :term:`RRECOMMENDS` for every other package when
+ :term:`LICENSE_CREATE_PACKAGE` is set to "1". If you wish all license
+ packages to be installed corresponding to packages in your image, then
+ you should instead add the new ``lic-pkgs`` feature to
+ :term:`IMAGE_FEATURES`.
+
+
+Miscellaneous
+-------------
+
+- Certificates are now properly checked when bitbake fetches sources
+ over HTTPS. If you receive errors as a result for your custom recipes,
+ you will need to use a mirror or address the issue with the operators
+ of the server in question.
+
+- ``avahi`` has had its GTK+ support disabled by default. If you wish to
+ re-enable it, set ``AVAHI_GTK = "gtk3"`` in a bbappend for the
+ ``avahi`` recipe or in your custom distro configuration file.
+
+- Setting the :term:`BUILD_REPRODUCIBLE_BINARIES` variable to "0" no longer
+ uses a strangely old fallback date of April 2011, it instead disables
+ building reproducible binaries as you would logically expect.
+
+- Setting noexec/nostamp/fakeroot varflags to any value besides "1" will
+ now trigger a warning. These should be either set to "1" to enable, or
+ not set at all to disable.
+
+- The previously deprecated ``COMPRESS_CMD`` and
+ ``CVE_CHECK_CVE_WHITELIST`` variables have been removed. Use
+ ``CONVERSION_CMD`` and :term:`CVE_CHECK_WHITELIST` respectively
+ instead.
+
+- The obsolete ``oe_machinstall`` function previously provided in the
+ :ref:`utils <ref-classes-utils>` class has been removed. For
+ machine-specific installation it is recommended that you use the
+ built-in override support in the fetcher or overrides in general
+ instead.
diff --git a/documentation/migration-guides/migration-general.rst b/documentation/migration-guides/migration-general.rst
index 182482ec43..9eecf69af8 100644
--- a/documentation/migration-guides/migration-general.rst
+++ b/documentation/migration-guides/migration-general.rst
@@ -1,5 +1,17 @@
+Introduction
+============
+
+This guide provides a list of the backwards-incompatible changes you
+might need to adapt to in your existing Yocto Project configuration
+when upgrading to a new release.
+
+If you are upgrading over multiple releases, you will need to follow
+the sections from the version following the one you were previously
+using up to the new version you are upgrading to.
+
+
General Migration Considerations
-================================
+--------------------------------
Some considerations are not tied to a specific Yocto Project release.
This section presents information you should consider when migrating to
@@ -26,16 +38,17 @@ any new Yocto Project release.
The better solution (where practical) is to use append files
(``*.bbappend``) to capture any customizations you want to make to a
- recipe. Doing so, isolates your changes from the main recipe making
+ recipe. Doing so isolates your changes from the main recipe, making
them much more manageable. However, sometimes it is not practical to
use an append file. A good example of this is when introducing a
newer or older version of a recipe in another layer.
+
- *Updating Append Files*:
- Since append files generally only contain
+ Since append (``.bbappend``) files generally only contain
your customizations, they often do not need to be adjusted for new
- releases. However, if the ``.bbappend`` file is specific to a
+ releases. However, if the append file is specific to a
particular version of the recipe (i.e. its name does not use the %
wildcard) and the version of the recipe to which it is appending has
changed, then you will at a minimum need to rename the append file to
@@ -50,5 +63,10 @@ any new Yocto Project release.
this is the case and assuming the patch is still needed, you must
modify the patch file so that it does apply.
+ .. tip::
+
+ You can list all append files used in your configuration by running:
+
+ bitbake-layers show-appends
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
index 7aee9db04f..3ca81428cf 100644
--- a/documentation/overview-manual/yp-intro.rst
+++ b/documentation/overview-manual/yp-intro.rst
@@ -217,8 +217,8 @@ your Metadata, the easier it is to cope with future changes.
- Use Board Support Package (BSP) layers from silicon vendors when
possible.
- - Familiarize yourself with the `Yocto Project curated layer
- index <https://www.yoctoproject.org/software-overview/layers/>`__
+ - Familiarize yourself with the
+ :yocto_home:`Yocto Project curated layer index</software-overview/layers/>`
or the :oe_layerindex:`OpenEmbedded layer index <>`.
The latter contains more layers but they are less universally
validated.
diff --git a/documentation/poky.yaml b/documentation/poky.yaml
index feb792fb49..fc7ec9ec3c 100644
--- a/documentation/poky.yaml
+++ b/documentation/poky.yaml
@@ -1,12 +1,14 @@
-DISTRO : "3.3.3"
-DISTRO_NAME_NO_CAP : "hardknott"
-DISTRO_NAME : "Hardknott"
-DISTRO_NAME_NO_CAP_MINUS_ONE : "gatesgarth"
+DISTRO : "3.4.4"
+DISTRO_NAME_NO_CAP : "honister"
+DISTRO_NAME : "Honister"
+DISTRO_NAME_NO_CAP_MINUS_ONE : "hardknott"
DISTRO_NAME_NO_CAP_LTS : "dunfell"
-YOCTO_DOC_VERSION : "3.3.3"
-YOCTO_DOC_VERSION_MINUS_ONE : "3.2.4"
-DISTRO_REL_TAG : "yocto-3.3.3"
-POKYVERSION : "25.0.3"
+YOCTO_DOC_VERSION : "3.4.4"
+YOCTO_DOC_VERSION_MINUS_ONE : "3.3.6"
+DISTRO_REL_TAG : "yocto-3.4.4"
+DOCCONF_VERSION : "3.4.4"
+BITBAKE_SERIES : "1.52"
+POKYVERSION : "26.0.4"
YOCTO_POKY : "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;"
YOCTO_DL_URL : "https://downloads.yoctoproject.org"
YOCTO_AB_URL : "https://autobuilder.yoctoproject.org"
@@ -14,23 +16,24 @@ YOCTO_RELEASE_DL_URL : "&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;"
UBUNTU_HOST_PACKAGES_ESSENTIAL : "gawk wget git diffstat unzip texinfo gcc \
build-essential chrpath socat cpio python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
- pylint3 xterm python3-subunit mesa-common-dev"
+ pylint3 xterm python3-subunit mesa-common-dev zstd liblz4-tool"
FEDORA_HOST_PACKAGES_ESSENTIAL : "gawk make wget tar bzip2 gzip python3 unzip perl patch \
diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \
ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-bignum socat \
python3-pexpect findutils which file cpio python python3-pip xz python3-GitPython \
python3-jinja2 SDL-devel xterm rpcgen mesa-libGL-devel perl-FindBin perl-File-Compare \
- perl-File-Copy perl-locale"
+ perl-File-Copy perl-locale zstd lz4"
OPENSUSE_HOST_PACKAGES_ESSENTIAL : "python gcc gcc-c++ git chrpath make wget python-xml \
diffstat makeinfo python-curses patch socat python3 python3-curses tar python3-pip \
- python3-pexpect xz which python3-Jinja2 Mesa-libEGL1 libSDL-devel xterm rpcgen Mesa-dri-devel
+ python3-pexpect xz which python3-Jinja2 Mesa-libEGL1 libSDL-devel xterm rpcgen Mesa-dri-devel \
+ zstd lz4
\n\ $ sudo pip3 install GitPython"
CENTOS7_HOST_PACKAGES_ESSENTIAL : "-y epel-release
\n\ $ sudo yum makecache
\n\ $ sudo yum install gawk make wget tar bzip2 gzip python3 unzip perl patch \
diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \
perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python36-pip xz \
- which SDL-devel xterm mesa-libGL-devel
+ which SDL-devel xterm mesa-libGL-devel zstd lz4
\n\ $ sudo pip3 install GitPython jinja2"
CENTOS8_HOST_PACKAGES_ESSENTIAL : "-y epel-release
\n\ $ sudo dnf config-manager --set-enabled PowerTools
@@ -39,7 +42,7 @@ CENTOS8_HOST_PACKAGES_ESSENTIAL : "-y epel-release
diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath ccache \
socat perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python3-pip \
python3-GitPython python3-jinja2 python3-pexpect xz which SDL-devel xterm \
- rpcgen mesa-libGL-devel"
+ rpcgen mesa-libGL-devel zstd lz4"
PIP3_HOST_PACKAGES_DOC : "$ sudo pip3 install sphinx sphinx_rtd_theme pyyaml"
MIN_PYTHON_VERSION : "3.6.0"
MIN_TAR_VERSION : "1.28"
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index ffaad9bfc9..694e20ebc3 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -590,19 +590,25 @@ Here is an example that uses this class in an image recipe::
"
Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
-passwords::
+passwords. First on host, create the password hash::
+
+ mkpasswd -m sha256crypt tester01
+
+The resulting hash is set to a variable and used in ``useradd`` command parameters.
+Remember to escape the character ``$``::
inherit extrausers
+ PASSWD = "\$X\$ABC123\$A-Long-Hash"
EXTRA_USERS_PARAMS = "\
- useradd -P tester01 tester-jim; \
- useradd -P tester01 tester-sue; \
+ useradd -p '${PASSWD}' tester-jim; \
+ useradd -p '${PASSWD}' tester-sue; \
"
-Finally, here is an example that sets the root password to "1876*18"::
+Finally, here is an example that sets the root password::
inherit extrausers
EXTRA_USERS_PARAMS = "\
- usermod -P 1876*18 root; \
+ usermod -p '${PASSWD}' root; \
"
.. _ref-classes-features_check:
@@ -1494,15 +1500,6 @@ messages for various BitBake severity levels (i.e. ``bbplain``,
This class is enabled by default since it is inherited by the ``base``
class.
-.. _ref-classes-meta:
-
-``meta.bbclass``
-================
-
-The ``meta`` class is inherited by recipes that do not build any output
-packages themselves, but act as a "meta" target for building other
-recipes.
-
.. _ref-classes-metadata_scm:
``metadata_scm.bbclass``
@@ -2218,6 +2215,18 @@ commit, and log. From the information, report files using a JSON format
are created and stored in
``${``\ :term:`LOG_DIR`\ ``}/error-report``.
+.. _ref-classes-reproducible-build:
+
+``reproducible_build.bbclass``
+==============================
+
+The ``reproducible_build.bbclass`` class enables
+:ref:`test-manual/reproducible-builds:reproducible builds` by computing
+a :term:`SOURCE_DATE_EPOCH` value in each component's build environment, so
+that the build is independent from the time when the component was built.
+
+Poky inherits this class by default since version 3.1.
+
.. _ref-classes-rm-work:
``rm_work.bbclass``
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
index d12e8dfbe3..6df59a1745 100644
--- a/documentation/ref-manual/system-requirements.rst
+++ b/documentation/ref-manual/system-requirements.rst
@@ -37,17 +37,13 @@ Supported Linux Distributions
Currently, the Yocto Project is supported on the following
distributions:
-- Ubuntu 16.04 (LTS)
-
- Ubuntu 18.04 (LTS)
- Ubuntu 20.04 (LTS)
-- Fedora 30
-
-- Fedora 31
+- Fedora 33
-- Fedora 32
+- Fedora 34
- CentOS 7.x
@@ -61,6 +57,7 @@ distributions:
- openSUSE Leap 15.1
+- openSUSE Leap 15.2
.. note::
@@ -323,7 +320,7 @@ If you would prefer not to use the ``install-buildtools`` script, you can instea
download and run a pre-built buildtools installer yourself with the following
steps:
-1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
+1. Locate and download the ``*.sh`` at :yocto_dl:`/releases/yocto/yocto-&DISTRO;/buildtools/`
2. Execute the installation script. Here is an example for the
traditional installer::
diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index 4edae33392..2438c023b4 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -326,21 +326,19 @@ file as a patch file::
file://file;apply=yes \
"
-Conversely, if you have a directory full of patch files and you want to
-exclude some so that the ``do_patch`` task does not apply them during
-the patch phase, you can use the "apply=no" parameter with the
+Conversely, if you have a file whose file type is ``.patch`` or ``.diff``
+and you want to exclude it so that the ``do_patch`` task does not apply
+it during the patch phase, you can use the "apply=no" parameter with the
:term:`SRC_URI` statement::
SRC_URI = " \
git://path_to_repo/some_package \
- file://path_to_lots_of_patch_files \
- file://path_to_lots_of_patch_files/patch_file5;apply=no \
+ file://file1.patch \
+ file://file2.patch;apply=no \
"
-In the
-previous example, assuming all the files in the directory holding the
-patch files end with either ``.patch`` or ``.diff``, every file would be
-applied as a patch by default except for the ``patch_file5`` patch.
+In the previous example ``file1.patch`` would be applied as a patch by default
+while ``file2.patch`` would not be applied.
You can find out more about the patching process in the
":ref:`overview-manual/concepts:patching`" section in
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 85f65cae35..7aef27337e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -906,6 +906,19 @@ system and gives an overview of their function and contents.
:term:`TARGET_PREFIX` when building for
``native`` recipes.
+ :term:`BUILD_REPRODUCIBLE_BINARIES`
+ This variable allows the image building classes and recipes to produce
+ :ref:`reproducible binaries <test-manual/reproducible-builds:reproducible builds>`
+
+ If you inherit the
+ :ref:`reproducible-build <ref-classes-reproducible-build>` class,
+ which is the case of the Poky reference distribution, this sets this
+ variable to "1".
+
+ If your build inherits this classs but you wish to disable reproducible
+ binary generation for specific packages or images, you can set this
+ variable to "0" in the corresponding recipes.
+
:term:`BUILD_STRIP`
Specifies the command to be used to strip debugging symbols from
binaries produced for the build host. By default, :term:`BUILD_STRIP`
@@ -3966,10 +3979,10 @@ system and gives an overview of their function and contents.
statements add specific configurations to targeted machine types::
KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
- KERNEL_FEATURES:append = "${KERNEL_EXTRA_FEATURES}"
- KERNEL_FEATURES:append:qemuall = "cfg/virtio.scc"
+ KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
+ KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc"
KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
- KERNEL_FEATURES:append:qemux86-64 = "cfg/sound.scc"
+ KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc"
:term:`KERNEL_FIT_LINK_NAME`
The link name of the kernel flattened image tree (FIT) image. This
@@ -4157,7 +4170,7 @@ system and gives an overview of their function and contents.
SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
KMACHINE:core2-32-intel-common = "intel-core2-32"
KBRANCH:core2-32-intel-common = "standard/base"
- KERNEL_FEATURES:append:core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
+ KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}"
The :term:`KMACHINE` statement says
that the kernel understands the machine name as "intel-core2-32".
@@ -6925,6 +6938,23 @@ system and gives an overview of their function and contents.
You will see this variable referenced in the default values of
``FILES:${PN}-dev``.
+ :term:`SOURCE_DATE_EPOCH`
+ This defines a date expressed in number of seconds since
+ the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by
+ multiple build systems to force a timestamp in built binaries.
+ Many upstream projects already support this variable.
+
+ You will find more details in the `official specifications
+ <https://reproducible-builds.org/specs/source-date-epoch/>`__.
+
+ A value for each recipe is computed from the sources by
+ the :ref:`reproducible-build <ref-classes-reproducible-build>` class.
+
+ If a recipe wishes to override the default behavior, it should set its
+ own :term:`SOURCE_DATE_EPOCH` value::
+
+ SOURCE_DATE_EPOCH = "1613559011"
+
: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
@@ -8158,6 +8188,15 @@ system and gives an overview of their function and contents.
information on setting up a cross-development environment, see the
:doc:`/sdk-manual/index` manual.
+ Note that this variable applies to building an SDK, not an eSDK,
+ in which case the term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be
+ used instead.
+
+ :term:`TOOLCHAIN_HOST_TASK_ESDK`
+ This variable allows to extend what is installed in the host
+ portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK`
+ applying to SDKs.
+
:term:`TOOLCHAIN_OUTPUTNAME`
This variable defines the name used for the toolchain output. The
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
diff --git a/documentation/releases.rst b/documentation/releases.rst
index bb881a2e24..7a71ac4087 100644
--- a/documentation/releases.rst
+++ b/documentation/releases.rst
@@ -4,6 +4,15 @@
Supported Release Manuals
===========================
+*****************************
+Release Series 3.4 (honister)
+*****************************
+
+- :yocto_docs:`3.4 Documentation </3.4>`
+- :yocto_docs:`3.4.1 Documentation </3.4.1>`
+- :yocto_docs:`3.4.2 Documentation </3.4.2>`
+- :yocto_docs:`3.4.3 Documentation </3.4.3>`
+
******************************
Release Series 3.3 (hardknott)
******************************
@@ -11,17 +20,9 @@ Release Series 3.3 (hardknott)
- :yocto_docs:`3.3 Documentation </3.3>`
- :yocto_docs:`3.3.1 Documentation </3.3.1>`
- :yocto_docs:`3.3.2 Documentation </3.3.2>`
-- :yocto_docs:`3.3.2 Documentation </3.3.3>`
-
-*******************************
-Release Series 3.2 (gatesgarth)
-*******************************
-
-- :yocto_docs:`3.2 Documentation </3.2>`
-- :yocto_docs:`3.2.1 Documentation </3.2.1>`
-- :yocto_docs:`3.2.2 Documentation </3.2.2>`
-- :yocto_docs:`3.2.3 Documentation </3.2.3>`
-- :yocto_docs:`3.2.4 Documentation </3.2.4>`
+- :yocto_docs:`3.3.3 Documentation </3.3.3>`
+- :yocto_docs:`3.3.4 Documentation </3.3.4>`
+- :yocto_docs:`3.3.5 Documentation </3.3.5>`
****************************
Release Series 3.1 (dunfell)
@@ -39,11 +40,24 @@ Release Series 3.1 (dunfell)
- :yocto_docs:`3.1.9 Documentation </3.1.9>`
- :yocto_docs:`3.1.10 Documentation </3.1.10>`
- :yocto_docs:`3.1.11 Documentation </3.1.11>`
+- :yocto_docs:`3.1.12 Documentation </3.1.12>`
+- :yocto_docs:`3.1.13 Documentation </3.1.13>`
+- :yocto_docs:`3.1.14 Documentation </3.1.14>`
==========================
Outdated Release Manuals
==========================
+*******************************
+Release Series 3.2 (gatesgarth)
+*******************************
+
+- :yocto_docs:`3.2 Documentation </3.2>`
+- :yocto_docs:`3.2.1 Documentation </3.2.1>`
+- :yocto_docs:`3.2.2 Documentation </3.2.2>`
+- :yocto_docs:`3.2.3 Documentation </3.2.3>`
+- :yocto_docs:`3.2.4 Documentation </3.2.4>`
+
*************************
Release Series 3.0 (zeus)
*************************
diff --git a/documentation/sphinx-static/switchers.js b/documentation/sphinx-static/switchers.js
index 1e37b625a6..feea5f2abf 100644
--- a/documentation/sphinx-static/switchers.js
+++ b/documentation/sphinx-static/switchers.js
@@ -2,10 +2,11 @@
'use strict';
var all_versions = {
- 'dev': 'dev (3.4)',
- '3.3.3': '3.3.3',
+ 'dev': 'dev (3.5)',
+ '3.4.2': '3.4.2',
+ '3.3.5': '3.3.5',
'3.2.4': '3.2.4',
- '3.1.11': '3.1.11',
+ '3.1.14': '3.1.14',
'3.0.4': '3.0.4',
'2.7.4': '2.7.4',
};
diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst
index 349cd1953e..01980d083e 100644
--- a/documentation/test-manual/reproducible-builds.rst
+++ b/documentation/test-manual/reproducible-builds.rst
@@ -44,6 +44,18 @@ same.
before finalizing your production images. It would be too late if you
only address this issue when the first updates are required.
+================
+How to enable it
+================
+
+You can enable build reproducibility by inheriting the
+:ref:`reproducible-build <ref-classes-reproducible-build>` class
+in the configuration for your distribution.
+
+This is what the Poky reference distribution does::
+
+ INHERIT += "reproducible_build"
+
===================
How we implement it
===================
generated by cgit 1.2.3-korg (git 2.39.0) at 2024-04-27 05:44:02 +0000