diff options
Diffstat (limited to 'poky/documentation')
35 files changed, 327 insertions, 639 deletions
diff --git a/poky/documentation/README b/poky/documentation/README index fad19683c..1e7b4f0e6 100644 --- a/poky/documentation/README +++ b/poky/documentation/README @@ -34,26 +34,21 @@ Manual Organization Here the folders corresponding to individual manuals: -* sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide. -* bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide -* dev-manual - The Yocto Project Development Tasks Manual -* kernel-dev - The Yocto Project Linux Kernel Development Tasks Manual -* ref-manual - The Yocto Project Reference Manual -* brief-yoctoprojectqs - The Yocto Project Quick Start -* profile-manual - The Yocto Project Profile and Tracing Manual -* toaster-manual - The Toaster Manual -* test-manual - The Test Environment Manual +* overview-manual - Yocto Project Overview and Concepts Manual +* sdk-manual - Yocto Project Software Development Kit (SDK) Developer's Guide. +* bsp-guide - Yocto Project Board Support Package (BSP) Developer's Guide +* dev-manual - Yocto Project Development Tasks Manual +* kernel-dev - Yocto Project Linux Kernel Development Manual +* ref-manual - Yocto Project Reference Manual +* brief-yoctoprojectqs - Yocto Project Quick Start +* profile-manual - Yocto Project Profiling and Tracing Manual +* toaster-manual - Toaster User Manual +* test-manual - Yocto Project Test Environment Manual Each folder is self-contained regarding content and figures. If you want to find HTML versions of the Yocto Project manuals on the web, -go to https://www.yoctoproject.org and click on the "Docs" tab. From -there you have access to archived documentation from previous releases, current -documentation for the latest release, and "Docs in Progress" for the release -currently being developed. - -In general, the Yocto Project site (https://www.yoctoproject.org) is a great -reference for both information and downloads. +the current versions reside at https://docs.yoctoproject.org. poky.yaml ========= diff --git a/poky/documentation/boilerplate.rst b/poky/documentation/boilerplate.rst index baccc9fe4..9b64d91ef 100644 --- a/poky/documentation/boilerplate.rst +++ b/poky/documentation/boilerplate.rst @@ -14,5 +14,5 @@ Commons. To report any inaccuracies or problems with this (or any other Yocto Project) manual, or to send additions or changes, please send email/patches to the Yocto Project documentation mailing list at ``docs@lists.yoctoproject.org`` or -log into the Freenode ``#yocto`` channel. +log into the `Libera Chat <https://libera.chat/>`__ ``#yocto`` channel. diff --git a/poky/documentation/bsp-guide/history.rst b/poky/documentation/bsp-guide/history.rst deleted file mode 100644 index d7cd8ef7f..000000000 --- a/poky/documentation/bsp-guide/history.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 0.9 - - November 2010 - - The initial document released with the Yocto Project 0.9 Release - * - 1.0 - - April 2011 - - Released with the Yocto Project 1.0 Release. - * - 1.1 - - October 2011 - - Released with the Yocto Project 1.1 Release. - * - 1.2 - - April 2012 - - Released with the Yocto Project 1.2 Release. - * - 1.3 - - October 2012 - - Released with the Yocto Project 1.3 Release. - * - 1.4 - - April 2013 - - Released with the Yocto Project 1.4 Release. - * - 1.5 - - October 2013 - - Released with the Yocto Project 1.5 Release. - * - 1.6 - - April 2014 - - Released with the Yocto Project 1.6 Release. - * - 1.7 - - October 2014 - - Released with the Yocto Project 1.7 Release. - * - 1.8 - - April 2015 - - Released with the Yocto Project 1.8 Release. - * - 2.0 - - October 2015 - - Released with the Yocto Project 2.0 Release. - * - 2.1 - - April 2016 - - Released with the Yocto Project 2.1 Release. - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/bsp-guide/index.rst b/poky/documentation/bsp-guide/index.rst index a4394a85e..9a8e034ae 100644 --- a/poky/documentation/bsp-guide/index.rst +++ b/poky/documentation/bsp-guide/index.rst @@ -11,6 +11,5 @@ Yocto Project Board Support Package Developer's Guide :numbered: bsp - history .. include:: /boilerplate.rst diff --git a/poky/documentation/dev-manual/common-tasks.rst b/poky/documentation/dev-manual/common-tasks.rst index 4a5011ea7..b81f51bf8 100644 --- a/poky/documentation/dev-manual/common-tasks.rst +++ b/poky/documentation/dev-manual/common-tasks.rst @@ -25,7 +25,7 @@ Creating Your Own Layer ----------------------- It is very easy to create your own layers to use with the OpenEmbedded -build system. The Yocto Project ships with tools that speed up creating +build system, as the Yocto Project ships with tools that speed up creating layers. This section describes the steps you perform by hand to create layers so that you can better understand them. For information about the layer-creation tools, see the @@ -422,8 +422,9 @@ 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 found in the :term:`Build Directory`. -The following example shows how to enable a layer named -``meta-mylayer``:: +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 out earlier):: # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly @@ -434,7 +435,7 @@ The following example shows how to enable a layer named /home/user/poky/meta \ /home/user/poky/meta-poky \ /home/user/poky/meta-yocto-bsp \ - /home/user/poky/meta-mylayer \ + /home/user/mystuff/meta-mylayer \ " BitBake parses each ``conf/layer.conf`` file from the top down as @@ -554,6 +555,67 @@ The end result of this ``.bbappend`` file is that on a Raspberry Pi, where used during :ref:`ref-tasks-fetch` and the test for a non-zero file size in :ref:`ref-tasks-install` will return true, and the file will be installed. +Installing Additional Files Using Your Layer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As another example, consider the main ``xserver-xf86-config`` recipe and a +corresponding ``xserver-xf86-config`` append file both from the :term:`Source +Directory`. Here is the main ``xserver-xf86-config`` recipe, which is named +``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at +``meta/recipes-graphics/xorg-xserver``:: + + SUMMARY = "X.Org X server configuration file" + HOMEPAGE = "http://www.x.org" + SECTION = "x11/base" + LICENSE = "MIT-X" + LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + PR = "r33" + + SRC_URI = "file://xorg.conf" + + S = "${WORKDIR}" + + CONFFILES:${PN} = "${sysconfdir}/X11/xorg.conf" + + PACKAGE_ARCH = "${MACHINE_ARCH}" + ALLOW_EMPTY:${PN} = "1" + + do_install () { + if test -s ${WORKDIR}/xorg.conf; then + install -d ${D}/${sysconfdir}/X11 + install -m 0644 ${WORKDIR}/xorg.conf ${D}/${sysconfdir}/X11/ + fi + } + +Following is the append file, which is named ``xserver-xf86-config_%.bbappend`` +and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The +file is in the layer at ``recipes-graphics/xorg-xserver``:: + + FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" + + SRC_URI:append:rpi = " \ + file://xorg.conf.d/98-pitft.conf \ + file://xorg.conf.d/99-calibration.conf \ + " + do_install:append:rpi () { + PITFT="${@bb.utils.contains("MACHINE_FEATURES", "pitft", "1", "0", d)}" + if [ "${PITFT}" = "1" ]; then + install -d ${D}/${sysconfdir}/X11/xorg.conf.d/ + install -m 0644 ${WORKDIR}/xorg.conf.d/98-pitft.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ + install -m 0644 ${WORKDIR}/xorg.conf.d/99-calibration.conf ${D}/${sysconfdir}/X11/xorg.conf.d/ + fi + } + + FILES:${PN}:append:rpi = " ${sysconfdir}/X11/xorg.conf.d/*" + +Building off of the previous example, we once again are setting the +:term:`FILESEXTRAPATHS` variable. In this case we are also using +:term:`SRC_URI` to list additional source files to use when ``rpi`` is found in +the list of :term:`OVERRIDES`. The :ref:`ref-tasks-install` task will then perform a +check for an additional :term:`MACHINE_FEATURES` that if set will cause these +additional files to be installed. These additional files are listed in +:term:`FILES` so that they will be packaged. + Prioritizing Your Layer ----------------------- @@ -843,8 +905,8 @@ the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:: IMAGE_INSTALL:append = " strace" -Use of the syntax is important - -specifically, the space between the quote and the package name, which is +Use of the syntax is important; specifically, the leading space +after the opening quote and before the package name, which is ``strace`` in this example. This space is required since the ``:append`` operator does not add the space. @@ -2361,7 +2423,7 @@ into separate packages:: require xorg-lib-common.inc SUMMARY = "Xpm: X Pixmap extension library" - LICENSE = "BSD" + LICENSE = "MIT" LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" DEPENDS += "libxext libsm libxt" PE = "1" @@ -3476,7 +3538,7 @@ Similar to working within a development shell as described in the previous section, you can also spawn and work within an interactive Python development shell. When debugging certain commands or even when just editing packages, ``devpyshell`` can be a useful tool. When you -invoke ``devpyshell``, all tasks up to and including +invoke the ``devpyshell`` task, all tasks up to and including :ref:`ref-tasks-patch` are run for the specified target. Then a new terminal is opened. Additionally, key Python objects and code are available in the same way they are to @@ -3486,7 +3548,7 @@ functions:: pydevshell> d.getVar("STAGING_DIR") '/media/build1/poky/build/tmp/sysroots' - pydevshell> d.getVar("STAGING_DIR") + pydevshell> d.getVar("STAGING_DIR", False) '${TMPDIR}/sysroots' pydevshell> d.setVar("FOO", "bar") pydevshell> d.getVar("FOO") @@ -3517,9 +3579,9 @@ either by using Ctrl+d or closing the terminal window. Building ======== -This section describes various build procedures. For example, the steps -needed for a simple build, a target that uses multiple configurations, -building an image for more than one machine, and so forth. +This section describes various build procedures, such as the steps +needed for a simple build, building a target for multiple configurations, +generating an image for more than one machine, and so forth. Building a Simple Image ----------------------- @@ -3575,8 +3637,10 @@ The following figure and list overviews the build process: .. note:: A common practice is to use a different Build Directory for - different targets. For example, ``~/build/x86`` for a ``qemux86`` - target, and ``~/build/arm`` for a ``qemuarm`` target. + different targets; for example, ``~/build/x86`` for a ``qemux86`` + target, and ``~/build/arm`` for a ``qemuarm`` target. In any + event, it's typically cleaner to locate the build directory + somewhere outside of your source directory. 3. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the ``conf/local.conf`` configuration file, which is found in the Build @@ -3599,7 +3663,7 @@ The following figure and list overviews the build process: The target is the name of the recipe you want to build. Common targets are the images in ``meta/recipes-core/images``, ``meta/recipes-sato/images``, and so forth all found in the - :term:`Source Directory`. Or, the target + :term:`Source Directory`. Alternatively, the target can be the name of a recipe for a specific piece of software such as BusyBox. For more details about the images the OpenEmbedded build system supports, see the @@ -3810,7 +3874,7 @@ Follow these steps to create an initramfs image: .. note:: - It is recommended that you do bundle the initramfs image with the + It is recommended that you bundle the initramfs image with the kernel image to avoid circular dependencies between the kernel recipe and the initramfs recipe should the initramfs image include kernel modules. @@ -3824,6 +3888,12 @@ Follow these steps to create an initramfs image: .. note:: + Bundling the initramfs with the kernel conflates the code in the initramfs + with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 compatible + software may be part of a bundled initramfs. + + .. note:: + If you choose to not bundle the initramfs image with the kernel image, you are essentially using an `Initial RAM Disk (initrd) <https://en.wikipedia.org/wiki/Initrd>`__. @@ -4430,7 +4500,7 @@ directory: SRCREV = "${AUTOREV}" When a recipe sets :term:`SRCREV` to - ``${AUTOREV}``, the build system accesses the network in an + ``${``\ :term:`AUTOREV`\ ``}``, the build system accesses the network in an attempt to determine the latest version of software from the SCM. Typically, recipes that use :term:`AUTOREV` are custom or modified recipes. Recipes that reside in public repositories usually do not @@ -5197,17 +5267,19 @@ command to return the available Wic images as follows:: $ wic list images genericx86 Create an EFI disk image for genericx86* - beaglebone-yocto Create SD card image for Beaglebone edgerouter Create SD card image for Edgerouter - qemux86-directdisk Create a QEMU machine 'pcbios' direct disk image - directdisk-gpt Create a 'pcbios' direct disk image - mkefidisk Create an EFI disk image - directdisk Create a 'pcbios' direct disk image + beaglebone-yocto Create SD card image for Beaglebone + qemux86-directdisk Create a qemu machine 'pcbios' direct disk image systemd-bootdisk Create an EFI disk image with systemd-boot mkhybridiso Create a hybrid ISO image + mkefidisk Create an EFI disk image sdimage-bootpart Create SD card image with a boot partition directdisk-multi-rootfs Create multi rootfs image using rootfs plugin + directdisk Create a 'pcbios' direct disk image directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config + qemuriscv Create qcow2 image for RISC-V QEMU machines + directdisk-gpt Create a 'pcbios' direct disk image + efi-bootdisk Once you know the list of available Wic images, you can use ``help`` with the command to get help on a @@ -7571,7 +7643,7 @@ Selecting a Device Manager The Yocto Project provides multiple ways to manage the device manager (``/dev``): -- Persistent and Pre-Populated\ ``/dev``: For this case, the ``/dev`` +- Persistent and Pre-Populated ``/dev``: For this case, the ``/dev`` directory is persistent and the required device nodes are created during the build. @@ -7581,7 +7653,7 @@ The Yocto Project provides multiple ways to manage the device manager configuration of device nodes is done in user space by a device manager like ``udev`` or ``busybox-mdev``. -Using Persistent and Pre-Populated\ ``/dev`` +Using Persistent and Pre-Populated ``/dev`` -------------------------------------------- To use the static method for device population, you need to set the @@ -10478,7 +10550,7 @@ been followed: and email address. In this example, the email address is a mailing list:: - $ poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org + $ poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@lists.yoctoproject.org You need to follow the prompts as the script is interactive. diff --git a/poky/documentation/dev-manual/history.rst b/poky/documentation/dev-manual/history.rst deleted file mode 100644 index 1ba312422..000000000 --- a/poky/documentation/dev-manual/history.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 1.1 - - October 2011 - - The initial document released with the Yocto Project 1.1 Release - * - 1.2 - - April 2012 - - Released with the Yocto Project 1.2 Release. - * - 1.3 - - October 2012 - - Released with the Yocto Project 1.3 Release. - * - 1.4 - - April 2013 - - Released with the Yocto Project 1.4 Release. - * - 1.5 - - October 2013 - - Released with the Yocto Project 1.5 Release. - * - 1.6 - - April 2014 - - Released with the Yocto Project 1.6 Release. - * - 1.7 - - October 2014 - - Released with the Yocto Project 1.7 Release. - * - 1.8 - - April 2015 - - Released with the Yocto Project 1.8 Release. - * - 2.0 - - October 2015 - - Released with the Yocto Project 2.0 Release. - * - 2.1 - - April 2016 - - Released with the Yocto Project 2.1 Release. - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/dev-manual/index.rst b/poky/documentation/dev-manual/index.rst index 941db2df8..f16b135c4 100644 --- a/poky/documentation/dev-manual/index.rst +++ b/poky/documentation/dev-manual/index.rst @@ -14,6 +14,5 @@ Yocto Project Development Tasks Manual start common-tasks qemu - history .. include:: /boilerplate.rst diff --git a/poky/documentation/dev-manual/intro.rst b/poky/documentation/dev-manual/intro.rst index 23c848e87..0f7370a96 100644 --- a/poky/documentation/dev-manual/intro.rst +++ b/poky/documentation/dev-manual/intro.rst @@ -7,16 +7,16 @@ The Yocto Project Development Tasks Manual Welcome ======= -Welcome to the Yocto Project Development Tasks Manual! This manual +Welcome to the Yocto Project Development Tasks Manual. This manual provides relevant procedures necessary for developing in the Yocto Project environment (i.e. developing embedded Linux images and -user-space applications that run on targeted devices). The manual groups +user-space applications that run on targeted devices). This manual groups related procedures into higher-level sections. Procedures can consist of high-level steps or low-level steps depending on the topic. This manual provides the following: -- Procedures that help you get going with the Yocto Project. For +- Procedures that help you get going with the Yocto Project; for example, procedures that show you how to set up a build host and work with the Yocto Project source repositories. @@ -24,25 +24,25 @@ This manual provides the following: Changes can be improvements, new features, or bug fixes. - Procedures related to "everyday" tasks you perform while developing - images and applications using the Yocto Project. For example, - procedures to create a layer, customize an image, write a new recipe, + images and applications using the Yocto Project, such as + creating a new layer, customizing an image, writing a new recipe, and so forth. This manual does not provide the following: -- Redundant Step-by-step Instructions: For example, the +- Redundant step-by-step instructions: For example, the :doc:`/sdk-manual/index` manual contains detailed instructions on how to install an SDK, which is used to develop applications for target hardware. -- Reference or Conceptual Material: This type of material resides in an - appropriate reference manual. For example, system variables are +- Reference or conceptual material: This type of material resides in an + appropriate reference manual. As an example, system variables are documented in the :doc:`/ref-manual/index`. -- Detailed Public Information Not Specific to the Yocto Project: For - example, exhaustive information on how to use the Source Control - Manager Git is better covered with Internet searches and official Git - Documentation than through the Yocto Project documentation. +- Detailed public information not specific to the Yocto Project: For + example, exhaustive information on how to use the Git version + control system is better covered with Internet searches and official Git + documentation than through the Yocto Project documentation. Other Information ================= diff --git a/poky/documentation/dev-manual/start.rst b/poky/documentation/dev-manual/start.rst index c3276c950..fc1b7c307 100644 --- a/poky/documentation/dev-manual/start.rst +++ b/poky/documentation/dev-manual/start.rst @@ -321,7 +321,7 @@ Project Build Host: - gcc &MIN_GCC_VERSION; or greater. - If your build host does not meet any of these three listed version + If your build host does not meet any of these listed version requirements, you can take steps to prepare the system so that you can still use the Yocto Project. See the ":ref:`ref-manual/system-requirements:required git, tar, python and gcc versions`" diff --git a/poky/documentation/kernel-dev/history.rst b/poky/documentation/kernel-dev/history.rst deleted file mode 100644 index 761b506ac..000000000 --- a/poky/documentation/kernel-dev/history.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 1.4 - - April 2013 - - The initial document released with the Yocto Project 1.4 Release - * - 1.5 - - October 2013 - - Released with the Yocto Project 1.5 Release. - * - 1.6 - - April 2014 - - Released with the Yocto Project 1.6 Release. - * - 1.7 - - October 2014 - - Released with the Yocto Project 1.7 Release. - * - 1.8 - - April 2015 - - Released with the Yocto Project 1.8 Release. - * - 2.0 - - October 2015 - - Released with the Yocto Project 2.0 Release. - * - 2.1 - - April 2016 - - Released with the Yocto Project 2.1 Release. - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/kernel-dev/index.rst b/poky/documentation/kernel-dev/index.rst index a8848ec8c..bd20e371e 100644 --- a/poky/documentation/kernel-dev/index.rst +++ b/poky/documentation/kernel-dev/index.rst @@ -16,6 +16,5 @@ Yocto Project Linux Kernel Development Manual concepts-appx maint-appx faq - history .. include:: /boilerplate.rst diff --git a/poky/documentation/overview-manual/concepts.rst b/poky/documentation/overview-manual/concepts.rst index c8b89885e..301763752 100644 --- a/poky/documentation/overview-manual/concepts.rst +++ b/poky/documentation/overview-manual/concepts.rst @@ -1908,8 +1908,8 @@ Behind the scenes, the shared state code works by looking in shared state files. Here is an example:: SSTATE_MIRRORS ?= "\ - file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ - file://.\* file:///some/local/dir/sstate/PATH" + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" .. note:: diff --git a/poky/documentation/overview-manual/history.rst b/poky/documentation/overview-manual/history.rst deleted file mode 100644 index 6fc700a01..000000000 --- a/poky/documentation/overview-manual/history.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 2.5 - - May 2018 - - The initial document released with the Yocto Project 2.5 Release - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/overview-manual/index.rst b/poky/documentation/overview-manual/index.rst index 123aed9b8..04061f8f4 100644 --- a/poky/documentation/overview-manual/index.rst +++ b/poky/documentation/overview-manual/index.rst @@ -14,6 +14,5 @@ Yocto Project Overview and Concepts Manual yp-intro development-environment concepts - history .. include:: /boilerplate.rst diff --git a/poky/documentation/poky.yaml b/poky/documentation/poky.yaml index 19441f099..feb792fb4 100644 --- a/poky/documentation/poky.yaml +++ b/poky/documentation/poky.yaml @@ -1,12 +1,12 @@ -DISTRO : "3.3.2" +DISTRO : "3.3.3" DISTRO_NAME_NO_CAP : "hardknott" DISTRO_NAME : "Hardknott" DISTRO_NAME_NO_CAP_MINUS_ONE : "gatesgarth" DISTRO_NAME_NO_CAP_LTS : "dunfell" -YOCTO_DOC_VERSION : "3.3.2" +YOCTO_DOC_VERSION : "3.3.3" YOCTO_DOC_VERSION_MINUS_ONE : "3.2.4" -DISTRO_REL_TAG : "yocto-3.3.2" -POKYVERSION : "25.0.2" +DISTRO_REL_TAG : "yocto-3.3.3" +POKYVERSION : "25.0.3" YOCTO_POKY : "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;" YOCTO_DL_URL : "https://downloads.yoctoproject.org" YOCTO_AB_URL : "https://autobuilder.yoctoproject.org" diff --git a/poky/documentation/profile-manual/history.rst b/poky/documentation/profile-manual/history.rst deleted file mode 100644 index 761b506ac..000000000 --- a/poky/documentation/profile-manual/history.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 1.4 - - April 2013 - - The initial document released with the Yocto Project 1.4 Release - * - 1.5 - - October 2013 - - Released with the Yocto Project 1.5 Release. - * - 1.6 - - April 2014 - - Released with the Yocto Project 1.6 Release. - * - 1.7 - - October 2014 - - Released with the Yocto Project 1.7 Release. - * - 1.8 - - April 2015 - - Released with the Yocto Project 1.8 Release. - * - 2.0 - - October 2015 - - Released with the Yocto Project 2.0 Release. - * - 2.1 - - April 2016 - - Released with the Yocto Project 2.1 Release. - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/profile-manual/index.rst b/poky/documentation/profile-manual/index.rst index 6e54133e0..0270932ca 100644 --- a/poky/documentation/profile-manual/index.rst +++ b/poky/documentation/profile-manual/index.rst @@ -14,6 +14,5 @@ Yocto Project Profiling and Tracing Manual arch usage examples - history .. include:: /boilerplate.rst diff --git a/poky/documentation/ref-manual/classes.rst b/poky/documentation/ref-manual/classes.rst index 3af023895..5c60fd8c8 100644 --- a/poky/documentation/ref-manual/classes.rst +++ b/poky/documentation/ref-manual/classes.rst @@ -543,7 +543,7 @@ which the OpenEmbedded build system places the generated objects built from the recipes. By default, the :term:`B` directory is set to the following, which is separate from the source directory (:term:`S`):: - ${WORKDIR}/${BPN}/{PV}/ + ${WORKDIR}/${BPN}-{PV}/ See these variables for more information: :term:`WORKDIR`, :term:`BPN`, and @@ -1710,6 +1710,55 @@ one such example. However, being aware of this class can reduce the proliferation of different versions of similar classes across multiple layers. +.. _ref-classes-overlayfs: + +``overlayfs.bbclass`` +======================= + +It's often desired in Embedded System design to have a read-only rootfs. +But a lot of different applications might want to have read-write access to +some parts of a filesystem. It can be especially useful when your update mechanism +overwrites the whole rootfs, but you may want your application data to be preserved +between updates. The :ref:`overlayfs <ref-classes-overlayfs>` class provides a way +to achieve that by means of ``overlayfs`` and at the same time keeping the base +rootfs read-only. + +To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper +layer in your machine configuration. The underlying file system can be anything that +is supported by ``overlayfs``. This has to be done in your machine configuration:: + + OVERLAYFS_MOUNT_POINT[data] = "/data" + +.. note:: + + * QA checks fail to catch file existence if you redefine this variable in your recipe! + * Only the existence of the systemd mount unit file is checked, not its contents. + * To get more details on ``overlayfs``, its internals and supported operations, please refer + to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_. + +The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP +(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image. + +Then you can specify writable directories on a recipe basis (e.g. in my-application.bb):: + + OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" + +To support several mount points you can use a different variable flag. Assuming we +want to have a writable location on the file system, but do not need that the data +survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` file system. + +In your machine configuration:: + + OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay" + +and then in your recipe:: + + OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application" + +.. note:: + + The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it. + .. _ref-classes-own-mirrors: ``own-mirrors.bbclass`` diff --git a/poky/documentation/ref-manual/devtool-reference.rst b/poky/documentation/ref-manual/devtool-reference.rst index 1862c481d..a1a8bcdc9 100644 --- a/poky/documentation/ref-manual/devtool-reference.rst +++ b/poky/documentation/ref-manual/devtool-reference.rst @@ -78,7 +78,7 @@ has a number of sub-commands for each function. You can run As directed in the general help output, you can get more syntax on a specific command by providing the command name and -using "--help":: +using ``--help``:: $ devtool add --help NOTE: Starting bitbake server... @@ -284,10 +284,7 @@ is identified using the ``EDITOR`` variable, on the specified recipe. When you use the ``devtool edit-recipe`` command, you must supply the root name of the recipe (i.e. no version, paths, or extensions). Also, the recipe file itself must reside in the workspace as a result of the -``devtool add`` or ``devtool upgrade`` commands. However, you can -override that requirement by using the "-a" or "--any-recipe" option. -Using either of these options allows you to edit any recipe regardless -of its location. +``devtool add`` or ``devtool upgrade`` commands. .. _devtool-updating-a-recipe: @@ -331,23 +328,37 @@ Checking on the Upgrade Status of a Recipe Upstream recipes change over time. Consequently, you might find that you need to determine if you can upgrade a recipe to a newer version. -To check on the upgrade status of a recipe, use the -``devtool check-upgrade-status`` command. The command displays a table -of your current recipe versions, the latest upstream versions, the email -address of the recipe's maintainer, and any additional information such -as commit hash strings and reasons you might not be able to upgrade a -particular recipe. +To check on the upgrade status of a recipe, you can use the +``devtool latest-version recipe`` command, which quickly shows the current +version and the latest version available upstream. To get a more global +picture, use the ``devtool check-upgrade-status`` command, which takes a +list of recipes as input, or no arguments, in which case it checks all +available recipes. This command will only print the recipes for which +a new upstream version is available. Each such recipe will have its current +version and latest upstream version, as well as the email of the maintainer +and any additional information such as the commit hash or reason for not +being able to upgrade it, displayed in a table. + +This upgrade checking mechanism relies on the optional :term:`UPSTREAM_CHECK_URI`, +:term:`UPSTREAM_CHECK_REGEX`, :term:`UPSTREAM_CHECK_GITTAGREGEX`, +:term:`UPSTREAM_CHECK_COMMITS` and :term:`UPSTREAM_VERSION_UNKNOWN` +variables in package recipes. .. note:: + - Most of the time, the above variables are unnecessary. They are only + required when upstream does something unusual, and default + mechanisms cannot find the new upstream versions. + - For the ``oe-core`` layer, recipe maintainers come from the :yocto_git:`maintainers.inc </poky/tree/meta/conf/distro/include/maintainers.inc>` file. - If the recipe is using the :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:git fetcher (\`\`git://\`\`)` - rather than a - tarball, the commit hash points to the commit that matches the - recipe's latest version tag. + rather than a tarball, the commit hash points to the commit that matches + the recipe's latest version tag, or in the absence of suitable tags, + to the latest commit (when :term:`UPSTREAM_CHECK_COMMITS` set to ``1`` + in the recipe). As with all ``devtool`` commands, you can get help on the individual command:: @@ -372,29 +383,25 @@ Following is a partial example table that reports on all the recipes. Notice the reported reason for not upgrading the ``base-passwd`` recipe. In this example, while a new version is available upstream, you do not want to use it because the dependency on ``cdebconf`` is not easily -satisfied. - -.. note:: - - When a reason for not upgrading displays, the reason is usually - written into the recipe using the ``RECIPE_NO_UPDATE_REASON`` - variable. See the - :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>` - recipe for an example. +satisfied. Maintainers can explicit the reason that is shown by adding +the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe. +See :yocto_git:`base-passwd.bb </poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>` +for an example. :: $ devtool check-upgrade-status ... - NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com> - NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff - NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff - . - . - . - NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility - NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> - NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com> + INFO: bind 9.16.20 9.16.21 Armin Kuster <akuster808@gmail.com> + INFO: inetutils 2.1 2.2 Tom Rini <trini@konsulko.com> + INFO: iproute2 5.13.0 5.14.0 Changhyeok Bae <changhyeok.bae@gmail.com> + INFO: openssl 1.1.1l 3.0.0 Alexander Kanavin <alex.kanavin@gmail.com> + INFO: base-passwd 3.5.29 3.5.51 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility + ... + +Last but not least, you may set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` +in a recipe when there's currently no way to determine its latest upstream +version. .. _devtool-upgrading-a-recipe: @@ -471,7 +478,7 @@ Use the ``devtool build`` command to build your recipe. The When you use the ``devtool build`` command, you must supply the root name of the recipe (i.e. do not provide versions, paths, or extensions). -You can use either the "-s" or the "--disable-parallel-make" options to +You can use either the ``-s`` or the ``--disable-parallel-make`` options to disable parallel makes during the build. Here is an example:: $ devtool build recipe diff --git a/poky/documentation/ref-manual/history.rst b/poky/documentation/ref-manual/history.rst deleted file mode 100644 index dc0a2ae79..000000000 --- a/poky/documentation/ref-manual/history.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 0.9 - - November 2010 - - The initial document released with the Yocto Project 0.9 Release - * - 1.0 - - April 2011 - - Released with the Yocto Project 1.0 Release. - * - 1.1 - - October 2011 - - Released with the Yocto Project 1.1 Release. - * - 1.2 - - April 2012 - - Released with the Yocto Project 1.2 Release. - * - 1.3 - - October 2012 - - Released with the Yocto Project 1.3 Release. - * - 1.4 - - April 2013 - - Released with the Yocto Project 1.4 Release. - * - 1.5 - - October 2013 - - Released with the Yocto Project 1.5 Release. - * - 1.6 - - April 2014 - - Released with the Yocto Project 1.6 Release. - * - 1.7 - - October 2014 - - Released with the Yocto Project 1.7 Release. - * - 1.8 - - April 2015 - - Released with the Yocto Project 1.8 Release. - * - 2.0 - - October 2015 - - Released with the Yocto Project 2.0 Release. - * - 2.1 - - April 2016 - - Released with the Yocto Project 2.1 Release. - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. - diff --git a/poky/documentation/ref-manual/index.rst b/poky/documentation/ref-manual/index.rst index 5cf10c5c2..a746dde49 100644 --- a/poky/documentation/ref-manual/index.rst +++ b/poky/documentation/ref-manual/index.rst @@ -25,6 +25,5 @@ Yocto Project Reference Manual varlocality faq resources - history .. include:: /boilerplate.rst diff --git a/poky/documentation/ref-manual/qa-checks.rst b/poky/documentation/ref-manual/qa-checks.rst index c3e40dba5..792c099d0 100644 --- a/poky/documentation/ref-manual/qa-checks.rst +++ b/poky/documentation/ref-manual/qa-checks.rst @@ -151,7 +151,7 @@ Errors and Warnings occur if you add a path which contains a ``.debug`` directory and do not explicitly add the ``.debug`` directory to the ``-dbg`` package. If this is the case, add the ``.debug`` directory explicitly to - ``FILES_${PN}-dbg``. See :term:`FILES` for additional + ``FILES:${PN}-dbg``. See :term:`FILES` for additional information on :term:`FILES`. @@ -435,7 +435,7 @@ Errors and Warnings (e.g. :term:`PN` happens to be the same as :term:`MACHINE` or :term:`DISTRO`), it can have unexpected consequences. For example, assignments such as - ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. + ``FILES:${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. Rename your recipe (or if :term:`PN` is being set explicitly, change the :term:`PN` value) so that the conflict does not occur. See :term:`FILES` for additional information. diff --git a/poky/documentation/ref-manual/resources.rst b/poky/documentation/ref-manual/resources.rst index 5ffd2b399..c94238466 100644 --- a/poky/documentation/ref-manual/resources.rst +++ b/poky/documentation/ref-manual/resources.rst @@ -90,12 +90,12 @@ For more Yocto Project-related mailing lists, see the Internet Relay Chat (IRC) ========================= -Two IRC channels on Freenode are available for the Yocto Project and -Poky discussions: +Two IRC channels on `Libera Chat <https://libera.chat/>`__ +are available for the Yocto Project and OpenEmbedded discussions: - ``#yocto`` -- ``#poky`` +- ``#oe`` .. _resources-links-and-related-documentation: @@ -187,9 +187,10 @@ Here is a list of resources you might find helpful: implementation of Bugzilla for logging and tracking Yocto Project defects. -- *Internet Relay Chat (IRC):* Two IRC channels on Freenode are - available for Yocto Project and Poky discussions: ``#yocto`` and - ``#poky``, respectively. +- *Internet Relay Chat (IRC):* Two IRC channels on + `Libera Chat <https://libera.chat/>`__ are + available for Yocto Project and OpenEmbeddded discussions: ``#yocto`` and + ``#oe``, respectively. - `Quick EMUlator (QEMU) <https://wiki.qemu.org/Index.html>`__\ *:* An open-source machine emulator and virtualizer. diff --git a/poky/documentation/ref-manual/system-requirements.rst b/poky/documentation/ref-manual/system-requirements.rst index e9d995c61..5e5c105d6 100644 --- a/poky/documentation/ref-manual/system-requirements.rst +++ b/poky/documentation/ref-manual/system-requirements.rst @@ -4,7 +4,7 @@ System Requirements ******************* -Welcome to the Yocto Project Reference Manual! This manual provides +Welcome to the Yocto Project Reference Manual. This manual provides reference information for the current release of the Yocto Project, and is most effectively used after you have an understanding of the basics of the Yocto Project. The manual is neither meant to be read as a @@ -277,7 +277,8 @@ installer and automatically installs the tools for you: 1. Execute the ``install-buildtools`` script. Here is an example:: $ cd poky - $ scripts/install-buildtools --without-extended-buildtools \ + $ scripts/install-buildtools \ + --without-extended-buildtools \ --base-url &YOCTO_DL_URL;/releases/yocto \ --release yocto-&DISTRO; \ --installer-version &DISTRO; diff --git a/poky/documentation/ref-manual/tasks.rst b/poky/documentation/ref-manual/tasks.rst index ecc701856..4edae3339 100644 --- a/poky/documentation/ref-manual/tasks.rst +++ b/poky/documentation/ref-manual/tasks.rst @@ -438,37 +438,6 @@ Manually Called Tasks These tasks are typically manually triggered (e.g. by using the ``bitbake -c`` command-line option): -.. _ref-tasks-checkpkg: - -``do_checkpkg`` ---------------- - -Provides information about the recipe including its upstream version and -status. The upstream version and status reveals whether or not a version -of the recipe exists upstream and a status of not updated, updated, or -unknown. - -To check the upstream version and status of a recipe, use the following -devtool commands:: - - $ devtool latest-version - $ devtool check-upgrade-status - -See the ":ref:`ref-manual/devtool-reference:\`\`devtool\`\` quick reference`" -chapter for more information on -``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" -section for information on checking the upgrade status of a recipe. - -To build the ``checkpkg`` task, use the ``bitbake`` command with the -"-c" option and task name:: - - $ bitbake core-image-minimal -c checkpkg - -By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g. -``$BUILD_DIR/tmp/log``). - -.. _ref-tasks-checkuri: - ``do_checkuri`` --------------- diff --git a/poky/documentation/ref-manual/terms.rst b/poky/documentation/ref-manual/terms.rst index 32658051a..e5a7565df 100644 --- a/poky/documentation/ref-manual/terms.rst +++ b/poky/documentation/ref-manual/terms.rst @@ -367,10 +367,16 @@ universal, the list includes them just in case: section in the Yocto Project Overview and Concepts Manual. :term:`Task` - A unit of execution for BitBake (e.g. + A per-recipe unit of execution for BitBake (e.g. :ref:`ref-tasks-compile`, :ref:`ref-tasks-fetch`, :ref:`ref-tasks-patch`, and so forth). + One of the major benefits of the build system is that, since each + recipe will typically spawn the execution of numerous tasks, + it is entirely possible that many tasks can execute in parallel, + either tasks from separate recipes or independent tasks within + the same recipe, potentially up to the parallelism of your + build system. :term:`Toaster` A web interface to the Yocto Project's :term:`OpenEmbedded Build System`. diff --git a/poky/documentation/ref-manual/variables.rst b/poky/documentation/ref-manual/variables.rst index d5ac1926b..5f6f91146 100644 --- a/poky/documentation/ref-manual/variables.rst +++ b/poky/documentation/ref-manual/variables.rst @@ -3589,6 +3589,12 @@ system and gives an overview of their function and contents. .. note:: + Bundling the initramfs with the kernel conflates the code in the + initramfs with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 + compatible software may be part of a bundled initramfs. + + .. note:: + Using an extra compilation pass to bundle the initramfs avoids a circular dependency between the kernel recipe and the initramfs recipe should the initramfs include kernel modules. Should that be @@ -5064,33 +5070,44 @@ system and gives an overview of their function and contents. ":ref:`package.bbclass <ref-classes-package>`" section. :term:`PACKAGE_DEBUG_SPLIT_STYLE` - Determines how to split up the binary and debug information when - creating ``*-dbg`` packages to be used with the GNU Project Debugger - (GDB). - - With the :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable, you can control - where debug information, which can include or exclude source files, - is stored: - - - ".debug": Debug symbol files are placed next to the binary in a - ``.debug`` directory on the target. For example, if a binary is - installed into ``/bin``, the corresponding debug symbol files are - installed in ``/bin/.debug``. Source files are placed in - ``/usr/src/debug``. - - - "debug-file-directory": Debug symbol files are placed under - ``/usr/lib/debug`` on the target, and separated by the path from - where the binary is installed. For example, if a binary is - installed in ``/bin``, the corresponding debug symbols are - installed in ``/usr/lib/debug/bin``. Source files are placed in - ``/usr/src/debug``. - - - "debug-without-src": The same behavior as ".debug" previously - described with the exception that no source files are installed. - - - "debug-with-srcpkg": The same behavior as ".debug" previously - described with the exception that all source files are placed in a - separate ``*-src`` pkg. This is the default behavior. + Determines how to split up and package debug and source information + when creating debugging packages to be used with the GNU Project + Debugger (GDB). In general, based on the value of this variable, + you can combine the source and debug info in a single package, + you can break out the source into a separate package that can be + installed independently, or you can choose to not have the source + packaged at all. + + The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable: + + - "``.debug``": All debugging and source info is placed in a single + ``*-dbg`` package; debug symbol files are placed next to the + binary in a ``.debug`` directory so that, if a binary is installed + into ``/bin``, the corresponding debug symbol file is installed + in ``/bin/.debug``. Source files are installed in the same ``*-dbg`` + package under ``/usr/src/debug``. + + - "``debug-file-directory``": As above, all debugging and source info + is placed in a single ``*-dbg`` package; debug symbol files are + placed entirely under the directory ``/usr/lib/debug`` and separated + by the path from where the binary is installed, so that if a binary + is installed in ``/bin``, the corresponding debug symbols are installed + in ``/usr/lib/debug/bin``, and so on. As above, source is installed + in the same package under ``/usr/src/debug``. + + - "``debug-with-srcpkg``": Debugging info is placed in the standard + ``*-dbg`` package as with the ``.debug`` value, while source is + placed in a separate ``*-src`` package, which can be installed + independently. This is the default setting for this variable, + as defined in Poky's ``bitbake.conf`` file. + + - "``debug-without-src``": The same behavior as with the ``.debug`` + setting, but no source is packaged at all. + + .. note:: + + Much of the above package splitting can be overridden via + use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable. You can find out more about debugging using GDB by reading the ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section @@ -5391,7 +5408,7 @@ system and gives an overview of their function and contents. The list of packages the recipe creates. The default value is the following:: - ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} During packaging, the :ref:`ref-tasks-package` task goes through :term:`PACKAGES` and uses the :term:`FILES` @@ -6132,6 +6149,13 @@ system and gives an overview of their function and contents. BitBake User Manual for additional information on tasks and dependencies. + :term:`RECIPE_NO_UPDATE_REASON` + If a recipe should not be replaced by a more recent upstream version, + putting the reason why in this variable in a recipe allows + ``devtool check-upgrade-status`` command to display it, as explained + in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`" + section. + :term:`REQUIRED_DISTRO_FEATURES` When inheriting the :ref:`features_check <ref-classes-features_check>` @@ -7503,6 +7527,7 @@ system and gives an overview of their function and contents. ${base_libdir} \ ${nonarch_base_libdir} \ ${datadir} \ + /sysroot-only \ " :term:`SYSROOT_DIRS_BLACKLIST` @@ -7516,10 +7541,16 @@ system and gives an overview of their function and contents. ${mandir} \ ${docdir} \ ${infodir} \ - ${datadir}/locale \ + ${datadir}/X11/locale \ ${datadir}/applications \ + ${datadir}/bash-completion \ ${datadir}/fonts \ + ${datadir}/gtk-doc/html \ + ${datadir}/installed-tests \ + ${datadir}/locale \ ${datadir}/pixmaps \ + ${datadir}/terminfo \ + ${libdir}/${BPN}/ptest \ " :term:`SYSROOT_DIRS_NATIVE` @@ -8476,9 +8507,21 @@ system and gives an overview of their function and contents. install initscripts package them in the main package for the recipe, you rarely need to set this variable in individual recipes. + :term:`UPSTREAM_CHECK_COMMITS` + You can perform a per-recipe check for what the latest upstream + source code version is by calling ``devtool latest-version recipe``. If + the recipe source code is provided from Git repositories, but + releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS` + to ``1`` in the recipe, and the OpenEmbedded build system + will compare the latest commit with the one currently specified + by the recipe (:term:`SRCREV`). + :: + + UPSTREAM_CHECK_COMMITS = "1" + :term:`UPSTREAM_CHECK_GITTAGREGEX` You can perform a per-recipe check for what the latest upstream - source code version is by calling ``bitbake -c checkpkg`` recipe. If + source code version is by calling ``devtool latest-version recipe``. If the recipe source code is provided from Git repositories, the OpenEmbedded build system determines the latest upstream version by picking the latest tag from the list of all repository tags. @@ -8501,7 +8544,7 @@ system and gives an overview of their function and contents. :term:`UPSTREAM_CHECK_URI` You can perform a per-recipe check for what the latest upstream - source code version is by calling ``bitbake -c checkpkg`` recipe. If + source code version is by calling ``devtool latest-version recipe``. If the source code is provided from tarballs, the latest version is determined by fetching the directory listing where the tarball is and attempting to find a later tarball. When this approach does not work, @@ -8511,6 +8554,18 @@ system and gives an overview of their function and contents. UPSTREAM_CHECK_URI = "recipe_url" + :term:`UPSTREAM_VERSION_UNKNOWN` + You can perform a per-recipe check for what the latest upstream + source code version is by calling ``devtool latest-version recipe``. + If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`, + :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in + the recipe allows to determine what the latest upstream version is, + you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe + to acknowledge that the check cannot be performed. + :: + + UPSTREAM_VERSION_UNKNOWN = "1" + :term:`USE_DEVFS` Determines if ``devtmpfs`` is used for ``/dev`` population. The default value used for :term:`USE_DEVFS` is "1" when no value is diff --git a/poky/documentation/releases.rst b/poky/documentation/releases.rst index 3f9646407..bb881a2e2 100644 --- a/poky/documentation/releases.rst +++ b/poky/documentation/releases.rst @@ -11,6 +11,7 @@ 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) @@ -37,6 +38,7 @@ Release Series 3.1 (dunfell) - :yocto_docs:`3.1.8 Documentation </3.1.8>` - :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>` ========================== Outdated Release Manuals diff --git a/poky/documentation/sdk-manual/history.rst b/poky/documentation/sdk-manual/history.rst deleted file mode 100644 index 8c10f6d2e..000000000 --- a/poky/documentation/sdk-manual/history.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 2.1 - - April 2016 - - The initial document released with the Yocto Project 2.1 Release - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/sdk-manual/index.rst b/poky/documentation/sdk-manual/index.rst index fce2b199c..dc7186b91 100644 --- a/poky/documentation/sdk-manual/index.rst +++ b/poky/documentation/sdk-manual/index.rst @@ -17,6 +17,5 @@ Yocto Project Application Development and the Extensible Software Development Ki appendix-obtain appendix-customizing appendix-customizing-standard - history .. include:: /boilerplate.rst diff --git a/poky/documentation/sphinx-static/switchers.js b/poky/documentation/sphinx-static/switchers.js index 6243724da..1e37b625a 100644 --- a/poky/documentation/sphinx-static/switchers.js +++ b/poky/documentation/sphinx-static/switchers.js @@ -3,9 +3,9 @@ var all_versions = { 'dev': 'dev (3.4)', - '3.3.2': '3.3.2', + '3.3.3': '3.3.3', '3.2.4': '3.2.4', - '3.1.10': '3.1.10', + '3.1.11': '3.1.11', '3.0.4': '3.0.4', '2.7.4': '2.7.4', }; diff --git a/poky/documentation/test-manual/history.rst b/poky/documentation/test-manual/history.rst deleted file mode 100644 index 89d4aad21..000000000 --- a/poky/documentation/test-manual/history.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 3.2 - - October 2020 - - The initial document released with the Yocto Project 3.2 Release diff --git a/poky/documentation/test-manual/index.rst b/poky/documentation/test-manual/index.rst index 4c590a6aa..86a2f436e 100644 --- a/poky/documentation/test-manual/index.rst +++ b/poky/documentation/test-manual/index.rst @@ -15,6 +15,5 @@ Yocto Project Test Environment Manual understand-autobuilder reproducible-builds yocto-project-compatible - history .. include:: /boilerplate.rst diff --git a/poky/documentation/toaster-manual/history.rst b/poky/documentation/toaster-manual/history.rst deleted file mode 100644 index 05b63e5b9..000000000 --- a/poky/documentation/toaster-manual/history.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-2.0-UK - -*********************** -Manual Revision History -*********************** - -.. list-table:: - :widths: 10 15 40 - :header-rows: 1 - - * - Revision - - Date - - Note - * - 1.8 - - April 2015 - - The initial document released with the Yocto Project 1.8 Release - * - 2.0 - - October 2015 - - Released with the Yocto Project 2.0 Release. - * - 2.1 - - April 2016 - - Released with the Yocto Project 2.1 Release. - * - 2.2 - - October 2016 - - Released with the Yocto Project 2.2 Release. - * - 2.3 - - May 2017 - - Released with the Yocto Project 2.3 Release. - * - 2.4 - - October 2017 - - Released with the Yocto Project 2.4 Release. - * - 2.5 - - May 2018 - - Released with the Yocto Project 2.5 Release. - * - 2.6 - - November 2018 - - Released with the Yocto Project 2.6 Release. - * - 2.7 - - May 2019 - - Released with the Yocto Project 2.7 Release. - * - 3.0 - - October 2019 - - Released with the Yocto Project 3.0 Release. - * - 3.1 - - April 2020 - - Released with the Yocto Project 3.1 Release. diff --git a/poky/documentation/toaster-manual/index.rst b/poky/documentation/toaster-manual/index.rst index f13ba7b8a..3ff4c6913 100644 --- a/poky/documentation/toaster-manual/index.rst +++ b/poky/documentation/toaster-manual/index.rst @@ -14,6 +14,5 @@ Toaster User Manual start setup-and-use reference - history .. include:: /boilerplate.rst |