diff options
| author | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-02-01 18:27:11 +0300 |
|---|---|---|
| committer | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-03-13 05:51:39 +0300 |
| commit | 6e60e8b2b2bab889379b380a28a167a0edd9d1d3 (patch) | |
| tree | f12f54d5ba8e74e67e5fad3651a1e125bb8f4191 /import-layers/yocto-poky/documentation | |
| parent | 509842add85b53e13164c1569a1fd43d5b8d91c5 (diff) | |
| download | openbmc-6e60e8b2b2bab889379b380a28a167a0edd9d1d3.tar.xz | |
Yocto 2.3
Move OpenBMC to Yocto 2.3(pyro).
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I50744030e771f4850afc2a93a10d3507e76d36bc
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Resolves: openbmc/openbmc#2461
Diffstat (limited to 'import-layers/yocto-poky/documentation')
39 files changed, 4672 insertions, 1468 deletions
diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml index bf6a6f8710..f0ee3991c6 100644 --- a/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml +++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml @@ -114,14 +114,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -135,12 +150,34 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Board + Support Package (BSP) Developer's Guide associated with + this Yocto Project release (version + &YOCTO_DOC_VERSION;), + see the Yocto Project Board Support Package (BSP) + Developer's Guide from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Board Support Package (BSP) Developer's Guide, see + <ulink url='&YOCTO_DOCS_URL;/latest/bsp-guide/bsp-guide.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> </bookinfo> diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml index 4d0ace0484..a92e6115b1 100644 --- a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml +++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml @@ -352,135 +352,139 @@ </para> <section id="bsp-filelayout-license"> - <title>License Files</title> + <title>License Files</title> - <para> - You can find these files in the BSP Layer at: - <literallayout class='monospaced'> + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> - </literallayout> - </para> + </literallayout> + </para> - <para> - These optional files satisfy licensing requirements for the BSP. - The type or types of files here can vary depending on the licensing requirements. - For example, in the Raspberry Pi BSP all licensing requirements are handled with the - <filename>COPYING.MIT</filename> file. - </para> + <para> + These optional files satisfy licensing requirements for the BSP. + The type or types of files here can vary depending on the licensing requirements. + For example, in the Raspberry Pi BSP all licensing requirements are handled with the + <filename>COPYING.MIT</filename> file. + </para> - <para> - Licensing files can be MIT, BSD, GPLv*, and so forth. - These files are recommended for the BSP but are optional and totally up to the BSP developer. - </para> + <para> + Licensing files can be MIT, BSD, GPLv*, and so forth. + These files are recommended for the BSP but are optional and totally up to the BSP developer. + </para> </section> <section id="bsp-filelayout-readme"> - <title>README File</title> - <para> - You can find this file in the BSP Layer at: - <literallayout class='monospaced'> + <title>README File</title> + + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/README - </literallayout> - </para> + </literallayout> + </para> - <para> - This file provides information on how to boot the live images that are optionally - included in the <filename>binary/</filename> directory. - The <filename>README</filename> file also provides special information needed for - building the image. - </para> + <para> + This file provides information on how to boot the live images that are optionally + included in the <filename>binary/</filename> directory. + The <filename>README</filename> file also provides special information needed for + building the image. + </para> - <para> - At a minimum, the <filename>README</filename> file must - contain a list of dependencies, such as the names of - any other layers on which the BSP depends and the name of - the BSP maintainer with his or her contact information. - </para> + <para> + At a minimum, the <filename>README</filename> file must + contain a list of dependencies, such as the names of + any other layers on which the BSP depends and the name of + the BSP maintainer with his or her contact information. + </para> </section> <section id="bsp-filelayout-readme-sources"> - <title>README.sources File</title> - <para> - You can find this file in the BSP Layer at: - <literallayout class='monospaced'> + <title>README.sources File</title> + + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/README.sources - </literallayout> - </para> + </literallayout> + </para> - <para> - This file provides information on where to locate the BSP - source files used to build the images (if any) that reside in - <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. - Images in the <filename>binary</filename> would be images - released with the BSP. - The information in the <filename>README.sources</filename> - file also helps you find the - <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> - used to generate the images that ship with the BSP. - <note> - If the BSP's <filename>binary</filename> directory is - missing or the directory has no images, an existing - <filename>README.sources</filename> file is - meaningless. - </note> - </para> + <para> + This file provides information on where to locate the BSP + source files used to build the images (if any) that reside in + <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. + Images in the <filename>binary</filename> would be images + released with the BSP. + The information in the <filename>README.sources</filename> + file also helps you find the + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + used to generate the images that ship with the BSP. + <note> + If the BSP's <filename>binary</filename> directory is + missing or the directory has no images, an existing + <filename>README.sources</filename> file is + meaningless. + </note> + </para> </section> <section id="bsp-filelayout-binary"> - <title>Pre-built User Binaries</title> - <para> - You can find these files in the BSP Layer at: - <literallayout class='monospaced'> + <title>Pre-built User Binaries</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> - </literallayout> - </para> + </literallayout> + </para> - <para> - This optional area contains useful pre-built kernels and - user-space filesystem images released with the BSP that are - appropriate to the target system. - This directory typically contains graphical (e.g. Sato) and - minimal live images when the BSP tarball has been created and - made available in the - <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. - You can use these kernels and images to get a system running - and quickly get started on development tasks. - </para> + <para> + This optional area contains useful pre-built kernels and + user-space filesystem images released with the BSP that are + appropriate to the target system. + This directory typically contains graphical (e.g. Sato) and + minimal live images when the BSP tarball has been created and + made available in the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. + You can use these kernels and images to get a system running + and quickly get started on development tasks. + </para> - <para> - The exact types of binaries present are highly - hardware-dependent. - The <filename>README</filename> file should be present in the - BSP Layer and it will explain how to use the images with the - target hardware. - Additionally, the <filename>README.sources</filename> file - should be present to locate the sources used to build the - images and provide information on the Metadata. - </para> + <para> + The exact types of binaries present are highly + hardware-dependent. + The <filename>README</filename> file should be present in the + BSP Layer and it will explain how to use the images with the + target hardware. + Additionally, the <filename>README.sources</filename> file + should be present to locate the sources used to build the + images and provide information on the Metadata. + </para> </section> <section id='bsp-filelayout-layer'> - <title>Layer Configuration File</title> - <para> - You can find this file in the BSP Layer at: - <literallayout class='monospaced'> + <title>Layer Configuration File</title> + + <para> + You can find this file in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/conf/layer.conf - </literallayout> - </para> + </literallayout> + </para> - <para> - The <filename>conf/layer.conf</filename> file identifies the file structure as a - layer, identifies the - contents of the layer, and contains information about how the build - system should use it. - Generally, a standard boilerplate file such as the following works. - In the following example, you would replace "<replaceable>bsp</replaceable>" and - "<replaceable>_bsp</replaceable>" with the actual name - of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template). - </para> + <para> + The <filename>conf/layer.conf</filename> file identifies the file structure as a + layer, identifies the + contents of the layer, and contains information about how the build + system should use it. + Generally, a standard boilerplate file such as the following works. + In the following example, you would replace "<replaceable>bsp</replaceable>" and + "<replaceable>_bsp</replaceable>" with the actual name + of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template). + </para> - <para> - <literallayout class='monospaced'> + <para> + <literallayout class='monospaced'> # We have a conf and classes directory, add to BBPATH BBPATH .= ":${LAYERDIR}" @@ -493,13 +497,13 @@ BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" - </literallayout> - </para> + </literallayout> + </para> - <para> - To illustrate the string substitutions, here are the corresponding statements - from the Raspberry Pi <filename>conf/layer.conf</filename> file: - <literallayout class='monospaced'> + <para> + To illustrate the string substitutions, here are the corresponding statements + from the Raspberry Pi <filename>conf/layer.conf</filename> file: + <literallayout class='monospaced'> # We have a conf and classes directory, append to BBPATH BBPATH .= ":${LAYERDIR}" @@ -513,316 +517,196 @@ # Additional license directories. LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" - </literallayout> - </para> + </literallayout> + </para> - <para> - This file simply makes - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - aware of the recipes and configuration directories. - The file must exist so that the OpenEmbedded build system can recognize the BSP. - </para> + <para> + This file simply makes + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> + aware of the recipes and configuration directories. + The file must exist so that the OpenEmbedded build system can recognize the BSP. + </para> </section> <section id="bsp-filelayout-machine"> - <title>Hardware Configuration Options</title> - <para> - You can find these files in the BSP Layer at: - <literallayout class='monospaced'> + <title>Hardware Configuration Options</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf - </literallayout> - </para> + </literallayout> + </para> - <para> - The machine files bind together all the information contained elsewhere - in the BSP into a format that the build system can understand. - If the BSP supports multiple machines, multiple machine configuration files - can be present. - These filenames correspond to the values to which users have set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. - </para> + <para> + The machine files bind together all the information contained elsewhere + in the BSP into a format that the build system can understand. + If the BSP supports multiple machines, multiple machine configuration files + can be present. + These filenames correspond to the values to which users have set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. + </para> - <para> - These files define things such as the kernel package to use - (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> - of virtual/kernel), the hardware drivers to - include in different types of images, any special software components - that are needed, any bootloader information, and also any special image - format requirements. - </para> + <para> + These files define things such as the kernel package to use + (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> + of virtual/kernel), the hardware drivers to + include in different types of images, any special software components + that are needed, any bootloader information, and also any special image + format requirements. + </para> - <para> - Each BSP Layer requires at least one machine file. - However, you can supply more than one file. - </para> + <para> + Each BSP Layer requires at least one machine file. + However, you can supply more than one file. + </para> - <para> - This configuration file could also include a hardware "tuning" - file that is commonly used to define the package architecture - and specify optimization flags, which are carefully chosen - to give best performance on a given processor. - </para> + <para> + This configuration file could also include a hardware "tuning" + file that is commonly used to define the package architecture + and specify optimization flags, which are carefully chosen + to give best performance on a given processor. + </para> - <para> - Tuning files are found in the <filename>meta/conf/machine/include</filename> - directory within the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - For example, the <filename>ia32-base.inc</filename> file resides in the - <filename>meta/conf/machine/include</filename> directory. - </para> + <para> + Tuning files are found in the <filename>meta/conf/machine/include</filename> + directory within the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + For example, the <filename>ia32-base.inc</filename> file resides in the + <filename>meta/conf/machine/include</filename> directory. + </para> - <para> - To use an include file, you simply include them in the - machine configuration file. - For example, the Raspberry Pi BSP - <filename>raspberrypi3.conf</filename> contains the - following statement: - <literallayout class='monospaced'> + <para> + To use an include file, you simply include them in the + machine configuration file. + For example, the Raspberry Pi BSP + <filename>raspberrypi3.conf</filename> contains the + following statement: + <literallayout class='monospaced'> include conf/machine/raspberrypi2.conf - </literallayout> - </para> + </literallayout> + </para> </section> <section id='bsp-filelayout-misc-recipes'> - <title>Miscellaneous BSP-Specific Recipe Files</title> - <para> - You can find these files in the BSP Layer at: - <literallayout class='monospaced'> + <title>Miscellaneous BSP-Specific Recipe Files</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* - </literallayout> - </para> + </literallayout> + </para> - <para> - This optional directory contains miscellaneous recipe files for - the BSP. - Most notably would be the formfactor files. - For example, in the Raspberry Pi BSP there is the - <filename>formfactor_0.0.bbappend</filename> file, which is an - append file used to augment the recipe that starts the build. - Furthermore, there are machine-specific settings used during - the build that are defined by the - <filename>machconfig</filename> file further down in the - directory. - Here is the <filename>machconfig</filename> - file for the Raspberry Pi BSP: - <literallayout class='monospaced'> + <para> + This optional directory contains miscellaneous recipe files for + the BSP. + Most notably would be the formfactor files. + For example, in the Raspberry Pi BSP there is the + <filename>formfactor_0.0.bbappend</filename> file, which is an + append file used to augment the recipe that starts the build. + Furthermore, there are machine-specific settings used during + the build that are defined by the + <filename>machconfig</filename> file further down in the + directory. + Here is the <filename>machconfig</filename> + file for the Raspberry Pi BSP: + <literallayout class='monospaced'> HAVE_TOUCHSCREEN=0 HAVE_KEYBOARD=1 DISPLAY_CAN_ROTATE=0 DISPLAY_ORIENTATION=0 DISPLAY_DPI=133 - </literallayout> - </para> + </literallayout> + </para> - <note><para> - If a BSP does not have a formfactor entry, defaults are established according to - the formfactor configuration file that is installed by the main - formfactor recipe - <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, - which is found in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - </para></note> + <note><para> + If a BSP does not have a formfactor entry, defaults are established according to + the formfactor configuration file that is installed by the main + formfactor recipe + <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, + which is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para></note> </section> <section id='bsp-filelayout-recipes-graphics'> - <title>Display Support Files</title> - <para> - You can find these files in the BSP Layer at: - <literallayout class='monospaced'> + <title>Display Support Files</title> + + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* - </literallayout> - </para> + </literallayout> + </para> - <para> - This optional directory contains recipes for the BSP if it has - special requirements for graphics support. - All files that are needed for the BSP to support a display are - kept here. - </para> + <para> + This optional directory contains recipes for the BSP if it has + special requirements for graphics support. + All files that are needed for the BSP to support a display are + kept here. + </para> </section> <section id='bsp-filelayout-kernel'> - <title>Linux Kernel Configuration</title> - <para> - You can find these files in the BSP Layer at: - <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend - </literallayout> - </para> - - <para> - These files append your specific changes to the main kernel recipe you are using. - </para> - <para> - For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> - at <filename>meta/recipes-kernel/linux</filename>. - You can append your specific changes to the kernel recipe by using a - similarly named append file, which is located in the BSP Layer (e.g. - the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). - </para> - <para> - Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build - the kernel. - In other words, you have selected the kernel in your - <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types - of statements: - <literallayout class='monospaced'> - PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "4.4%" - </literallayout> - <note> - When the preferred provider is assumed by default, the - <filename>PREFERRED_PROVIDER</filename> statement does not appear in the - <replaceable>bsp_name</replaceable><filename>.conf</filename> file. - </note> - You would use the <filename>linux-yocto_4.4.bbappend</filename> - file to append specific BSP settings to the kernel, thus - configuring the kernel for your particular BSP. - </para> - - <para> - As an example, consider the following append file - used by the BSPs in <filename>meta-yocto-bsp</filename>: - <literallayout class='monospaced'> - meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend - </literallayout> - The following listing shows the file. - Be aware that the actual commit ID strings in this - example listing might be different than the actual strings - in the file from the <filename>meta-yocto-bsp</filename> - layer upstream. - <literallayout class='monospaced'> - KBRANCH_genericx86 = "standard/base" - KBRANCH_genericx86-64 = "standard/base" - - KMACHINE_genericx86 ?= "common-pc" - KMACHINE_genericx86-64 ?= "common-pc-64" - KBRANCH_edgerouter = "standard/edgerouter" - KBRANCH_beaglebone = "standard/beaglebone" - KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" - - SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" - SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53" - - COMPATIBLE_MACHINE_genericx86 = "genericx86" - COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" - COMPATIBLE_MACHINE_edgerouter = "edgerouter" - COMPATIBLE_MACHINE_beaglebone = "beaglebone" - COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" - - LINUX_VERSION_genericx86 = "4.4.3" - LINUX_VERSION_genericx86-64 = "4.4.3" - </literallayout> - This append file contains statements used to support - several BSPs that ship with the Yocto Project. - The file defines machines using the - <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> - variable and uses the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> - variable to ensure the machine name used by the OpenEmbedded - build system maps to the machine name used by the Linux Yocto - kernel. - The file also uses the optional - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> - variable to ensure the build process uses the - appropriate kernel branch. - </para> - - <para> - Although this particular example does not use it, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable could be used to enable features specific to - the kernel. - The append file points to specific commits in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> - Git repository and the <filename>meta</filename> Git repository - branches to identify the exact kernel needed to build the - BSP. - </para> - - <para> - One thing missing in this particular BSP, which you will - typically need when developing a BSP, is the kernel configuration - file (<filename>.config</filename>) for your BSP. - When developing a BSP, you probably have a kernel configuration - file or a set of kernel configuration files that, when taken - together, define the kernel configuration for your BSP. - You can accomplish this definition by putting the configurations - in a file or a set of files inside a directory located at the - same level as your kernel's append file and having the same - name as the kernel's main recipe file. - With all these conditions met, simply reference those files in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement in the append file. - </para> + <title>Linux Kernel Configuration</title> - <para> - For example, suppose you had some configuration options - in a file called <filename>network_configs.cfg</filename>. - You can place that file inside a directory named - <filename>linux-yocto</filename> and then add - a <filename>SRC_URI</filename> statement such as the - following to the append file. - When the OpenEmbedded build system builds the kernel, the - configuration options are picked up and applied. - <literallayout class='monospaced'> - SRC_URI += "file://network_configs.cfg" - </literallayout> - </para> + <para> + You can find these files in the BSP Layer at: + <literallayout class='monospaced'> + meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend + </literallayout> + </para> - <para> - To group related configurations into multiple files, you - perform a similar procedure. - Here is an example that groups separate configurations - specifically for Ethernet and graphics into their own - files and adds the configurations by using a - <filename>SRC_URI</filename> statement like the following - in your append file: - <literallayout class='monospaced'> - SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" - </literallayout> - </para> + <para> + These files append machine-specific changes to the main + kernel recipe you are using. + </para> - <para> - Another variable you can use in your kernel recipe append - file is the - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - variable. - When you use this statement, you are extending the locations - used by the OpenEmbedded system to look for files and - patches as the recipe is processed. - </para> + <para> + For your BSP, you typically want to use an existing Yocto + Project kernel recipe found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + at <filename>meta/recipes-kernel/linux</filename>. + You can append machine-specific changes to the kernel recipe + by using a similarly named append file, which is located in + the BSP Layer for your target device (e.g. the + <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). + </para> - <note> <para> - Other methods exist to accomplish grouping and defining configuration options. - For example, if you are working with a local clone of the kernel repository, - you could checkout the kernel's <filename>meta</filename> branch, make your changes, - and then push the changes to the local bare clone of the kernel. - The result is that you directly add configuration options to the - <filename>meta</filename> branch for your BSP. - The configuration options will likely end up in that location anyway if the BSP gets - added to the Yocto Project. + Suppose you are using the <filename>linux-yocto_4.4.bb</filename> + recipe to build the kernel. + In other words, you have selected the kernel in your + <replaceable>bsp_name</replaceable><filename>.conf</filename> + file by adding + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink> + statements as follows: + <literallayout class='monospaced'> + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_VERSION_linux-yocto ?= "4.4%" + </literallayout> + <note> + When the preferred provider is assumed by default, the + <filename>PREFERRED_PROVIDER</filename> + statement does not appear in the + <replaceable>bsp_name</replaceable><filename>.conf</filename> file. + </note> + You would use the <filename>linux-yocto_4.4.bbappend</filename> + file to append specific BSP settings to the kernel, thus + configuring the kernel for your particular BSP. </para> <para> - In general, however, the Yocto Project maintainers take care of moving the - <filename>SRC_URI</filename>-specified - configuration options to the kernel's <filename>meta</filename> branch. - Not only is it easier for BSP developers to not have to worry about putting those - configurations in the branch, but having the maintainers do it allows them to apply - 'global' knowledge about the kinds of common configuration options multiple BSPs in - the tree are typically using. - This allows for promotion of common configurations into common features. + You can find more information on what your append file + should contain in the + "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>" + section in the Yocto Project Linux Kernel Development + Manual. </para> - </note> </section> </section> @@ -1052,7 +936,7 @@ <listitem><para>Create a <filename>.bbappend</filename> file for the modified recipe. For information on using append files, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>" + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" section in the Yocto Project Development Manual. </para></listitem> <listitem><para> diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml index b2a2e32c5d..598f8775db 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml @@ -45,6 +45,10 @@ You can accomplish this through a recipe that is a BitBake append (<filename>.bbappend</filename>) file, which is described later in this section. + <note> + For general information on BSP layer structure, see the + <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>. + </note> </para> <para> @@ -108,7 +112,7 @@ </para> <para> - Follow these general steps to create your layer: + Follow these general steps to create your layer without the aid of a script: <orderedlist> <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, you should be sure someone @@ -233,7 +237,18 @@ <note>In order to be compliant with the Yocto Project, a layer must contain a <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink> - </note></para></listitem> + </note> + </para></listitem> + <listitem><para> + <emphasis>Optionally Test for Compatibility:</emphasis> + If you want permission to use the Yocto Project + Compatibility logo with your layer or application that + uses your layer, perform the steps to apply for + compatibility. + See the + "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>" + section for more information. + </para></listitem> </orderedlist> </para> </section> @@ -408,6 +423,14 @@ <para> We also recommend the following: <itemizedlist> + <listitem><para>If you want permission to use the + Yocto Project Compatibility logo with your layer + or application that uses your layer, perform the + steps to apply for compatibility. + See the + "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>" + section for more information. + </para></listitem> <listitem><para>Store custom layers in a Git repository that uses the <filename>meta-<replaceable>layer_name</replaceable></filename> format. @@ -424,6 +447,204 @@ </section> </section> + <section id='making-sure-your-layer-is-compatible-with-yocto-project'> + <title>Making Sure Your Layer is Compatible With Yocto Project</title> + + <para> + When you create a layer used with the Yocto Project, it is + advantageous to make sure that the layer interacts well with + existing Yocto Project layers (i.e. the layer is compatible + with the Yocto Project). + Ensuring compatibility makes the layer easy to be consumed + by others in the Yocto Project community and allows you + permission to use the Yocto Project Compatibility logo. + </para> + + <para> + Version 1.0 of the Yocto Project Compatibility Program has + been in existence for a number of releases. + This version of the program consists of the layer application + process that requests permission to use the Yocto Project + Compatibility logo for your layer and application. + You can find version 1.0 of the form at + <ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>. + To be granted permission to use the logo, you need to be able + to answer "Yes" to the questions or have an acceptable + explanation for any questions answered "No". + </para> + + <para> + A second version (2.0) of the Yocto Project Compatibility + Program is currently under development. + Included as part of version 2.0 (and currently available) is + the <filename>yocto-compat-layer.py</filename> script. + When run against a layer, this script tests the layer against + tighter constraints based on experiences of how layers have + worked in the real world and where pitfalls have been found. + </para> + + <para> + Part of the 2.0 version of the program that is not currently + available but is in development is an updated compatibility + application form. + This updated form, among other questions, specifically + asks if your layer has passed the test using the + <filename>yocto-compat-layer.py</filename> script. + <note><title>Tip</title> + Even though the updated application form is currently + unavailable for version 2.0 of the Yocto Project + Compatibility Program, the + <filename>yocto-compat-layer.py</filename> script is + available in OE-Core. + You can use the script to assess the status of your + layers in advance of the 2.0 release of the program. + </note> + </para> + + <para> + The remainder of this section presents information on the + version 1.0 registration form and on the + <filename>yocto-compat-layer.py</filename> script. + </para> + + <section id='yocto-project-compatibility-program-application'> + <title>Yocto Project Compatibility Program Application</title> + + <para> + Use the 1.0 version of the form to apply for your + layer's compatibility approval. + Upon successful application, you can use the Yocto + Project Compatibility logo with your layer and the + application that uses your layer. + </para> + + <para> + To access the form, use this link: + <ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>. + Follow the instructions on the form to complete your + application. + </para> + + <para> + The application consists of the following sections: + <itemizedlist> + <listitem><para> + <emphasis>Contact Information:</emphasis> + Provide your contact information as the fields + require. + Along with your information, provide the + released versions of the Yocto Project for which + your layer is compatible. + </para></listitem> + <listitem><para> + <emphasis>Acceptance Criteria:</emphasis> + Provide "Yes" or "No" answers for each of the + items in the checklist. + Space exists at the bottom of the form for any + explanations for items for which you answered "No". + </para></listitem> + <listitem><para> + <emphasis>Recommendations:</emphasis> + Provide answers for the questions regarding Linux + kernel use and build success. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='yocto-compat-layer-py-script'> + <title><filename>yocto-compat-layer.py</filename> Script</title> + + <para> + The <filename>yocto-compat-layer.py</filename> script, + which is currently available, provides you a way to + assess how compatible your layer is with the Yocto + Project. + You should run this script prior to using the form to + apply for compatibility as described in the previous + section. + <note> + Because the script is part of the 2.0 release of the + Yocto Project Compatibility Program, you are not + required to successfully run your layer against it + in order to be granted compatibility status. + However, it is a good idea as it promotes + well-behaved layers and gives you an idea of where your + layer stands regarding compatibility. + </note> + </para> + + <para> + The script divides tests into three areas: COMMON, BSD, + and DISTRO. + For example, given a distribution layer (DISTRO), the + layer must pass both the COMMON and DISTRO related tests. + Furthermore, if your layer is a BSP layer, the layer must + pass the COMMON and BSP set of tests. + </para> + + <para> + To execute the script, enter the following commands from + your build directory: + <literallayout class='monospaced'> + $ source oe-init-build-env + $ yocto-compat-layer.py <replaceable>your_layer_directory</replaceable> + </literallayout> + Be sure to provide the actual directory for your layer + as part of the command. + </para> + + <para> + Entering the command causes the script to determine the + type of layer and then to execute a set of specific + tests against the layer. + The following list overviews the test: + <itemizedlist> + <listitem><para> + <filename>common.test_readme</filename>: + Tests if a <filename>README</filename> file + exists in the layer and the file is not empty. + </para></listitem> + <listitem><para> + <filename>common.test_parse</filename>: + Tests to make sure that BitBake can parse the + files without error (i.e. + <filename>bitbake -p</filename>). + </para></listitem> + <listitem><para> + <filename>common.test_show_environment</filename>: + Tests that the global or per-recipe environment + is in order without errors (i.e. + <filename>bitbake -e</filename>). + </para></listitem> + <listitem><para> + <filename>common.test_signatures</filename>: + Tests to be sure that BSP and DISTRO layers do not + come with recipes that change signatures. + </para></listitem> + <listitem><para> + <filename>bsp.test_bsp_defines_machines</filename>: + Tests if a BSP layer has machine configurations. + </para></listitem> + <listitem><para> + <filename>bsp.test_bsp_no_set_machine</filename>: + Tests to ensure a BSP layer does not set the + machine when the layer is added. + </para></listitem> + <listitem><para> + <filename>distro.test_distro_defines_distros</filename>: + Tests if a DISTRO layer has distro configurations. + </para></listitem> + <listitem><para> + <filename>distro.test_distro_no_set_distro</filename>: + Tests to ensure a DISTRO layer does not set the + distribution when the layer is added. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + <section id='enabling-your-layer'> <title>Enabling Your Layer</title> @@ -464,37 +685,46 @@ </section> <section id='using-bbappend-files'> - <title>Using .bbappend Files</title> + <title>Using .bbappend Files in Your Layer</title> <para> - Recipes used to append Metadata to other recipes are called - BitBake append files. - BitBake append files use the <filename>.bbappend</filename> file - type suffix, while the corresponding recipes to which Metadata - is being appended use the <filename>.bb</filename> file type - suffix. + A recipe that appends Metadata to another recipe is called a + BitBake append file. + A BitBake append file uses the <filename>.bbappend</filename> + file type suffix, while the corresponding recipe to which + Metadata is being appended uses the <filename>.bb</filename> + file type suffix. </para> <para> - A <filename>.bbappend</filename> file allows your layer to make - additions or changes to the content of another layer's recipe - without having to copy the other recipe into your layer. + You can use a <filename>.bbappend</filename> file in your + layer to make additions or changes to the content of another + layer's recipe without having to copy the other layer's + recipe into your layer. Your <filename>.bbappend</filename> file resides in your layer, while the main <filename>.bb</filename> recipe file to which you are appending Metadata resides in a different layer. </para> <para> - Append files must have the same root names as their corresponding - recipes. + Being able to append information to an existing recipe not only + avoids duplication, but also automatically applies recipe + changes from a different layer into your layer. + If you were copying recipes, you would have to manually merge + changes as they occur. + </para> + + <para> + When you create an append file, you must use the same root + name as the corresponding recipe file. For example, the append file <filename>someapp_&DISTRO;.bbappend</filename> must apply to <filename>someapp_&DISTRO;.bb</filename>. - This means the original recipe and append file names are version - number-specific. + This means the original recipe and append file names are + version number-specific. If the corresponding recipe is renamed to update to a newer - version, the corresponding <filename>.bbappend</filename> file must - be renamed (and possibly updated) as well. + version, you must also rename and possibly update + the corresponding <filename>.bbappend</filename> as well. During the build process, BitBake displays an error on starting if it detects a <filename>.bbappend</filename> file that does not have a corresponding recipe with a matching name. @@ -504,14 +734,6 @@ </para> <para> - Being able to append information to an existing recipe not only - avoids duplication, but also automatically applies recipe - changes in a different layer to your layer. - If you were copying recipes, you would have to manually merge - changes as they occur. - </para> - - <para> As an example, consider the main formfactor recipe and a corresponding formfactor append file both from the <link linkend='source-directory'>Source Directory</link>. @@ -523,8 +745,7 @@ SUMMARY = "Device formfactor information" SECTION = "base" LICENSE = "MIT" - LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \ - file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" + LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" PR = "r45" SRC_URI = "file://config file://machconfig" @@ -540,8 +761,7 @@ if [ -s "${S}/machconfig" ]; then install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ fi - } - </literallayout> + } </literallayout> In the main recipe, note the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable, which tells the OpenEmbedded build system where to @@ -553,7 +773,8 @@ <filename>formfactor_0.0.bbappend</filename> and is from the Raspberry Pi BSP Layer named <filename>meta-raspberrypi</filename>. - The file is in <filename>recipes-bsp/formfactor</filename>: + The file is in the layer at + <filename>recipes-bsp/formfactor</filename>: <literallayout class='monospaced'> FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" </literallayout> @@ -573,12 +794,13 @@ </para> <para> - The statement in this example extends the directories to include + The statement in this example extends the directories to + include <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>, which resolves to a directory named <filename>formfactor</filename> in the same directory in which the append file resides (i.e. - <filename>meta-raspberrypi/recipes-bsp/formfactor/formfactor</filename>. + <filename>meta-raspberrypi/recipes-bsp/formfactor</filename>. This implies that you must have the supporting directory structure set up that will contain any files or patches you will be including from the layer. @@ -586,8 +808,8 @@ <para> Using the immediate expansion assignment operator - <filename>:=</filename> is important because of the reference to - <filename>THISDIR</filename>. + <filename>:=</filename> is important because of the reference + to <filename>THISDIR</filename>. The trailing colon character is important as it ensures that items in the list remain colon-separated. <note> @@ -2470,6 +2692,93 @@ </para> </section> + <section id='new-recipe-using-headers-to-interface-with-devices'> + <title>Using Headers to Interface with Devices</title> + + <para> + If your recipe builds an application that needs to + communicate with some device or needs an API into a custom + kernel, you will need to provide appropriate header files. + Under no circumstances should you ever modify the existing + <filename>meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc</filename> + file. + These headers are used to build <filename>libc</filename> and + must not be compromised with custom or machine-specific + header information. + If you customize <filename>libc</filename> through modified + headers all other applications that use + <filename>libc</filename> thus become affected. + <note><title>Warning</title> + Never copy and customize the <filename>libc</filename> + header file (i.e. + <filename>meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc</filename>). + </note> + The correct way to interface to a device or custom kernel is + to use a separate package that provides the additional headers + for the driver or other unique interfaces. + When doing so, your application also becomes responsible for + creating a dependency on that specific provider. + </para> + + <para> + Consider the following: + <itemizedlist> + <listitem><para> + Never modify + <filename>linux-libc-headers.inc</filename>. + Consider that file to be part of the + <filename>libc</filename> system, and not something + you use to access the kernel directly. + You should access <filename>libc</filename> through + specific <filename>libc</filename> calls. + </para></listitem> + <listitem><para> + Applications that must talk directly to devices + should either provide necessary headers themselves, + or establish a dependency on a special headers package + that is specific to that driver. + </para></listitem> + </itemizedlist> + </para> + + <para> + For example, suppose you want to modify an existing header + that adds I/O control or network support. + If the modifications are used by a small number programs, + providing a unique version of a header is easy and has little + impact. + When doing so, bear in mind the guidelines in the previous + list. + <note> + If for some reason your changes need to modify the behavior + of the <filename>libc</filename>, and subsequently all + other applications on the system, use a + <filename>.bbappend</filename> to modify the + <filename>linux-kernel-headers.inc</filename> file. + However, take care to not make the changes + machine specific. + </note> + </para> + + <para> + Consider a case where your kernel is older and you need + an older <filename>libc</filename> ABI. + The headers installed by your recipe should still be a + standard mainline kernel, not your own custom one. + </para> + + <para> + When you use custom kernel headers you need to get them from + <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>, + which is the directory with kernel headers that are + required to build out-of-tree modules. + Your recipe will also need the following: + <literallayout class='monospaced'> + do_configure[depends] += "virtual/kernel:do_shared_workdir" + </literallayout> + </para> + </section> + <section id='new-recipe-compilation'> <title>Compilation</title> @@ -2883,15 +3192,16 @@ the build host. For example, an application linking to a common library needs access to the library itself and its associated headers. - The way this access is accomplished is by populating sysroot + The way this access is accomplished is by populating a sysroot with files. - One sysroot exists per "machine" for which the image is - being built. - In practical terms, this means a sysroot exists for the target - machine, and a sysroot exists for the build host. + Each recipe has two sysroots in its work directory, one for + target files + (<filename>recipe-sysroot</filename>) and one for files that + are native to the build host + (<filename>recipe-sysroot-native</filename>). <note> You could find the term "staging" used within the Yocto - project regarding files populating sysroot (e.g. the + project regarding files populating sysroots (e.g. the <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_DIR'><filename>STAGING_DIR</filename></ulink> variable). </note> @@ -2906,12 +3216,6 @@ task within the <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> directory. - </para> - - <para> - A subset of these files, as defined by the - the <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink> - variable, automatically populates the sysroot. The reason for this limitation is that almost all files that populate the sysroot are cataloged in manifests in order to ensure the files can be removed later when a recipe is either @@ -2920,24 +3224,29 @@ </para> <para> + A subset of the files installed by the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task are used by the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink> + task as defined by the the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink> + variable to automatically populate the sysroot. It is possible to modify the list of directories that populate the sysroot. The following example shows how you could add the <filename>/opt</filename> directory to the list of - directories: + directories within a recipe: <literallayout class='monospaced'> SYSROOT_DIRS += "/opt" </literallayout> </para> <para> - For information on variables you can use to help control how - files sysroot is populated, see the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></ulink>, - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></ulink> - variables. + For a more complete description of the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink> + task and its associated functions, see the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-staging'><filename>staging</filename></ulink> + class. </para> </section> @@ -2986,21 +3295,21 @@ a package on the target or during image creation when a package is included in an image. To add a post-installation script to a package, add a - <filename>pkg_postinst_PACKAGENAME()</filename> function to + <filename>pkg_postinst_</filename><replaceable>PACKAGENAME</replaceable><filename>()</filename> function to the recipe file (<filename>.bb</filename>) and replace - <filename>PACKAGENAME</filename> with the name of the package + <replaceable>PACKAGENAME</replaceable> with the name of the package you want to attach to the <filename>postinst</filename> script. To apply the post-installation script to the main package for the recipe, which is usually what is required, specify <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> - in place of <filename>PACKAGENAME</filename>. + in place of <replaceable>PACKAGENAME</replaceable>. </para> <para> A post-installation function has the following structure: <literallayout class='monospaced'> - pkg_postinst_PACKAGENAME() { + pkg_postinst_<replaceable>PACKAGENAME</replaceable>() { # Commands to carry out } </literallayout> @@ -3029,7 +3338,7 @@ To delay script execution until boot time, use the following structure in the post-installation script: <literallayout class='monospaced'> - pkg_postinst_PACKAGENAME() { + pkg_postinst_<replaceable>PACKAGENAME</replaceable>() { if [ x"$D" = "x" ]; then # Actions to carry out on the device go here else @@ -3047,6 +3356,20 @@ when executed on the first boot. </para> + <para> + If you have recipes that use <filename>pkg_postinst</filename> + scripts and they require the use of non-standard native + tools that have dependencies during rootfs construction, you + need to use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></ulink> + variable in your recipe to list these tools. + If you do not use this variable, the tools might be missing and + execution of the post-installation script is deferred until + first boot. + Deferring the script to first boot is undesirable and for + read-only rootfs impossible. + </para> + <note> Equivalent support for pre-install, pre-uninstall, and post-uninstall scripts exist by way of @@ -4475,7 +4798,7 @@ <listitem><para> Wic is a completely independent standalone utility that initially provides - easier-to-use and more flexible replacements for a + easier-to-use and more flexible replacements for an existing functionality in OE Core's <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink> class and <filename>mkefidisk.sh</filename> script. @@ -4786,7 +5109,7 @@ Creating image(s)... Info: The new image(s) can be found here: - /var/tmp/wic/build/mkefidisk-201310230946-sda.direct + <replaceable>current_directory</replaceable>/build/mkefidisk-201310230946-sda.direct The following build artifacts were used to create the image(s): ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs @@ -4811,7 +5134,8 @@ <para> The output specifies the exact image created as well as - where it was created. + where it was created, which is in the current + directory by default. The output also names the artifacts used and the exact <filename>.wks</filename> script that was used to generate the image. @@ -4823,18 +5147,26 @@ </para> <para> - Continuing with the example, you can now directly - <filename>dd</filename> the image to a USB stick, or - whatever media for which you built your image, - and boot the resulting media: + Continuing with the example, you can now write the + image to a USB stick, or whatever media for which you + built your image, and boot the resulting media. + You can write the image by using + <filename>bmaptool</filename> or + <filename>dd</filename>: + <literallayout class='monospaced'> + $ oe-run-native bmaptool copy build/mkefidisk-201310230946-sda.direct /dev/sd<replaceable>X</replaceable> + </literallayout> + or <literallayout class='monospaced'> - $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb - [sudo] password for trz: - 182274+0 records in - 182274+0 records out - 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s - [trz at empanada ~]$ sudo eject /dev/sdb + $ sudo dd if=build/mkefidisk-201310230946-sda.direct of=/dev/sd<replaceable>X</replaceable> </literallayout> + <note> + For more information on how to use the + <filename>bmaptool</filename> to flash a device + with an image, see the + "<link linkend='flashing-images-using-bmaptool'>Flashing Images Using <filename>bmaptool</filename></link>" + section. + </note> </para> </section> @@ -4910,7 +5242,7 @@ Creating image(s)... Info: The new image(s) can be found here: - /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct + <replaceable>current_directory</replaceable>/build/directdisksdb-201310231131-sdb.direct The following build artifacts were used to create the image(s): @@ -4927,7 +5259,7 @@ whatever media for which you built your image, and boot the resulting media: <literallayout class='monospaced'> - $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb + $ sudo dd if=build/directdisksdb-201310231131-sdb.direct of=/dev/sdb 86018+0 records in 86018+0 records out 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s @@ -4954,7 +5286,7 @@ Creating image(s)... Info: The new image(s) can be found here: - /var/tmp/wic/build/directdisk-201309252350-sda.direct + <replaceable>current_directory</replaceable>/build/directdisk-201309252350-sda.direct The following build artifacts were used to create the image(s): @@ -4977,8 +5309,8 @@ (runs in Raw Mode) and uses a modified kickstart file. The example also uses the <filename>-o</filename> option to cause Wic to create the output - somewhere other than the default - <filename>/var/tmp/wic</filename> directory: + somewhere other than the default output directory, + which is the current directory: <literallayout class='monospaced'> $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ @@ -5030,6 +5362,14 @@ <filename>--source</filename> keyword to a particular plug-in implementation that populates a corresponding partition. + <note> + If you use plug-ins that have build-time dependencies + (e.g. native tools, bootloaders, and so forth) + when building a Wic image, you need to specify those + dependencies using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink> + variable. + </note> </para> <para> @@ -5224,9 +5564,7 @@ <itemizedlist> <listitem><para> <filename>/<replaceable>path</replaceable></filename>: - For example, <filename>/</filename>, - <filename>/usr</filename>, or - <filename>/home</filename> + For example, "/", "/usr", or "/home" </para></listitem> <listitem><para> <filename>swap</filename>: @@ -6234,7 +6572,7 @@ and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> statements enable the OpenEmbedded build system to find the patch file. For more information on using append files, see the - "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" + "<link linkend='using-bbappend-files'>Using .bbappend Files in Your Layer</link>" section. </para></listitem> <listitem><para><emphasis>Put the patch file in your layer</emphasis>: @@ -6713,7 +7051,7 @@ <listitem><para>Add a <filename>psplash</filename> append file for a branded splash screen. For information on append files, see the - "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" + "<link linkend='using-bbappend-files'>Using .bbappend Files in Your Layer</link>" section.</para></listitem> <listitem><para>Add any other append files to make custom changes that are specific to individual @@ -6994,7 +7332,7 @@ section of the Yocto Project Linux Kernel Development Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" section, which is in this manual.</para></listitem> - <listitem><para><filename>bitbake -u depexp -g <replaceable>bitbake_target</replaceable></filename>: + <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>: Using the BitBake command with these options brings up a Dependency Explorer from which you can view file dependencies. @@ -7042,7 +7380,7 @@ the Dependency Explorer UI with the BitBake command: <literallayout class='monospaced'> $ cd <replaceable>image-directory</replaceable> - $ bitbake -u depexp -g <replaceable>image</replaceable> + $ bitbake -u taskexp -g <replaceable>image</replaceable> </literallayout> Use the interface to select potential packages you wish to eliminate and see their dependency relationships. @@ -7277,7 +7615,7 @@ you much of a performance difference across the other systems as compared to using a more general tuning across all the builds (e.g. setting - <ulink url='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink> specifically for each machine's build). Rather than "max out" each build's tunings, you can take steps that cause the OpenEmbedded build system to reuse software across the @@ -7456,7 +7794,7 @@ <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link> </para></listitem> <listitem><para> - <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link> + <link linkend='incrementing-a-binary-package-version'>Incrementing a binary package version</link> </para></listitem> <listitem><para> <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> @@ -7514,37 +7852,104 @@ </para> </section> - <section id='incrementing-a-package-revision-number'> - <title>Incrementing a Package Revision Number</title> + <section id='incrementing-a-binary-package-version'> + <title>Incrementing a Package Version</title> + + <para> + This section provides some background on how binary package + versioning is accomplished and presents some of the services, + variables, and terminology involved. + </para> + + <para> + In order to understand binary package versioning, you need + to consider the following: + <itemizedlist> + <listitem><para> + Binary Package: The binary package that is eventually + built and installed into an image. + </para></listitem> + <listitem><para> + Binary Package Version: The binary package version + is composed of two components - a version and a + revision. + <note> + Technically, a third component, the "epoch" (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>) + is involved but this discussion for the most part + ignores <filename>PE</filename>. + </note> + The version and revision are taken from the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> + variables, respectively. + </para></listitem> + <listitem><para> + <filename>PV</filename>: The recipe version. + <filename>PV</filename> represents the version of the + software being packaged. + Do not confuse <filename>PV</filename> with the + binary package version. + </para></listitem> + <listitem><para> + <filename>PR</filename>: The recipe revision. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>: + The OpenEmbedded build system uses this string + to help define the value of <filename>PV</filename> + when the source code revision needs to be included + in it. + </para></listitem> + <listitem><para> + <ulink url='https://wiki.yoctoproject.org/wiki/PR_Service'>PR Service</ulink>: + A network-based service that helps automate keeping + package feeds compatible with existing package + manager applications such as RPM, APT, and OPKG. + </para></listitem> + </itemizedlist> + </para> <para> - If a committed change results in changing the package output, - then the value of the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> - variable needs to be increased (or "bumped"). - Increasing <filename>PR</filename> occurs one of two ways: + Whenever the binary package content changes, the binary package + version must change. + Changing the binary package version is accomplished by changing + or "bumping" the <filename>PR</filename> and/or + <filename>PV</filename> values. + Increasing these values occurs one of two ways: <itemizedlist> <listitem><para>Automatically using a Package Revision - Service (PR Service).</para></listitem> + Service (PR Service). + </para></listitem> <listitem><para>Manually incrementing the - <filename>PR</filename> variable.</para></listitem> + <filename>PR</filename> and/or + <filename>PV</filename> variables. + </para></listitem> </itemizedlist> </para> <para> - Given that one of the challenges any build system and its - users face is how to maintain a package feed that is compatible - with existing package manager applications such as - RPM, APT, and OPKG, using an automated system is much - preferred over a manual system. - In either system, the main requirement is that version - numbering increases in a linear fashion and that a number of - version components exist that support that linear progression. + Given a primary challenge of any build system and its users + is how to maintain a package feed that is compatible with + existing package manager applications such as RPM, APT, and + OPKG, using an automated system is much preferred over a + manual system. + In either system, the main requirement is that binary package + version numbering increases in a linear fashion and that a + number of version components exist that support that linear + progression. + For information on how to ensure package revisioning remains + linear, see the + "<link linkend='automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</link>" + section. </para> <para> - The following two sections provide information on the PR Service - and on manual <filename>PR</filename> bumping. + The following three sections provide related information on the + PR Service, the manual method for "bumping" + <filename>PR</filename> and/or <filename>PV</filename>, and + on how to ensure binary package revisioning remains linear. </para> <section id='working-with-a-pr-service'> @@ -7585,9 +7990,10 @@ All the inputs into a given task are represented by a signature, which can trigger a rebuild when different. Thus, the build system itself does not rely on the - <filename>PR</filename> numbers to trigger a rebuild. + <filename>PR</filename>, <filename>PV</filename>, and + <filename>PE</filename> numbers to trigger a rebuild. The signatures, however, can be used to generate - <filename>PR</filename> values. + these values. </para> <para> @@ -7632,7 +8038,7 @@ </literallayout> Once the service is started, packages will automatically get increasing <filename>PR</filename> values and - BitBake will take care of starting and stopping the server. + BitBake takes care of starting and stopping the server. </para> <para> @@ -7653,8 +8059,8 @@ <para> It is also recommended you use build history, which adds - some sanity checks to package versions, in conjunction with - the server that is running the PR Service. + some sanity checks to binary package versions, in + conjunction with the server that is running the PR Service. To enable build history, add the following to each building system's <filename>local.conf</filename> file: <literallayout class='monospaced'> @@ -7668,18 +8074,23 @@ </para> <note> - <para>The OpenEmbedded build system does not maintain - <filename>PR</filename> information as part of the - shared state (sstate) packages. - If you maintain an sstate feed, its expected that either - all your building systems that contribute to the sstate - feed use a shared PR Service, or you do not run a PR - Service on any of your building systems. - Having some systems use a PR Service while others do - not leads to obvious problems.</para> - <para>For more information on shared state, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>" - section in the Yocto Project Reference Manual.</para> + <para> + The OpenEmbedded build system does not maintain + <filename>PR</filename> information as part of the + shared state (sstate) packages. + If you maintain an sstate feed, its expected that either + all your building systems that contribute to the sstate + feed use a shared PR Service, or you do not run a PR + Service on any of your building systems. + Having some systems use a PR Service while others do + not leads to obvious problems. + </para> + + <para> + For more information on shared state, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>" + section in the Yocto Project Reference Manual. + </para> </note> </section> @@ -7688,7 +8099,7 @@ <para> The alternative to setting up a PR Service is to manually - bump the + "bump" the <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variable. </para> @@ -7722,7 +8133,7 @@ </para> <para> - When upgrading the version of a package, assuming the + When upgrading the version of a binary package, assuming the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> changes, the <filename>PR</filename> variable should be reset to "r0" (or "${INC_PR}.0" if you are using @@ -7730,7 +8141,7 @@ </para> <para> - Usually, version increases occur only to packages. + Usually, version increases occur only to binary packages. However, if for some reason <filename>PV</filename> changes but does not increase, you can increase the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> @@ -7739,13 +8150,89 @@ </para> <para> - Version numbering strives to follow the + Binary package version numbering strives to follow the <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> Debian Version Field Policy Guidelines</ulink>. These guidelines define how versions are compared and what "increasing" a version means. </para> </section> + + <section id='automatically-incrementing-a-binary-package-revision-number'> + <title>Automatically Incrementing a Package Version Number</title> + + <para> + When fetching a repository, BitBake uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + variable to determine the specific source code revision + from which to build. + You set the <filename>SRCREV</filename> variable to + <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink> + to cause the OpenEmbedded build system to automatically use the + latest revision of the software: + <literallayout class='monospaced'> + SRCREV = "${AUTOREV}" + </literallayout> + </para> + + <para> + Furthermore, you need to reference <filename>SRCPV</filename> + in <filename>PV</filename> in order to automatically update + the version whenever the revision of the source code + changes. + Here is an example: + <literallayout class='monospaced'> + PV = "1.0+git${SRCPV}" + </literallayout> + The OpenEmbedded build system substitutes + <filename>SRCPV</filename> with the following: + <literallayout class='monospaced'> + AUTOINC+<replaceable>source_code_revision</replaceable> + </literallayout> + The build system replaces the <filename>AUTOINC</filename> with + a number. + The number used depends on the state of the PR Service: + <itemizedlist> + <listitem><para> + If PR Service is enabled, the build system increments + the number, which is similar to the behavior of + <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>. + This behavior results in linearly increasing package + versions, which is desirable. + Here is an example: + <literallayout class='monospaced'> + hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk + hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk + </literallayout> + </para></listitem> + <listitem><para> + If PR Service is not enabled, the build system + replaces the <filename>AUTOINC</filename> + placeholder with zero (i.e. "0"). + This results in changing the package version since + the source revision is included. + However, package versions are not increased linearly. + Here is an example: + <literallayout class='monospaced'> + hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk + hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk + </literallayout> + </para></listitem> + </itemizedlist> + </para> + + <para> + In summary, the OpenEmbedded build system does not track the + history of binary package versions for this purpose. + <filename>AUTOINC</filename>, in this case, is comparable to + <filename>PR</filename>. + If PR server is not enabled, <filename>AUTOINC</filename> + in the package version is simply replaced by "0". + If PR server is enabled, the build system keeps track of the + package versions and bumps the number when the package + revision changes. + </para> + </section> </section> <section id='handling-optional-module-packaging'> @@ -8226,13 +8713,14 @@ <title>Using RPM</title> <para> - The <filename>smart</filename> application performs + The <filename>dnf</filename> application performs runtime package management of RPM packages. You must perform an initial setup for - <filename>smart</filename> on the target machine + <filename>dnf</filename> on the target machine if the <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>, and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>, + and <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink> variables have not been set or the target image was built before the variables were set. @@ -8244,21 +8732,26 @@ <filename>all</filename>, <filename>i586</filename>, and <filename>qemux86</filename> from a server named <filename>my.server</filename>. - You must inform <filename>smart</filename> of the - availability of these databases by issuing the - following commands on the target: + You must inform <filename>dnf</filename> of the + availability of these databases by creating a + <filename>/etc/yum.repos.d/oe-packages.repo</filename> + file with the following content: <literallayout class='monospaced'> - # smart channel --add i585 type=rpm-md baseurl=http://my.server/rpm/i586 - # smart channel --add qemux86 type=rpm-md baseurl=http://my.server/rpm/qemux86 - # smart channel --add all type=rpm-md baseurl=http://my.server/rpm/all + [oe-packages] + baseurl="http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all" </literallayout> From the target machine, fetch the repository: <literallayout class='monospaced'> - # smart update + # dnf makecache </literallayout> - After everything is set up, <filename>smart</filename> + After everything is set up, <filename>dnf</filename> is able to find, install, and upgrade packages from the specified repository. + <note> + See the + <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF documentation</ulink> + for additional information. + </note> </para> </section> @@ -8364,6 +8857,127 @@ </section> </section> + <section id='generating-and-using-signed-packages'> + <title>Generating and Using Signed Packages</title> + <para> + In order to add security to RPM packages used during a build, + you can take steps to securely sign them. + Once a signature is verified, the OpenEmbedded build system + can use the package in the build. + If security fails for a signed package, the build system + aborts the build. + </para> + + <para> + This section describes how to sign RPM packages during a build + and how to use signed package feeds (repositories) when + doing a build. + </para> + + <section id='signing-rpm-packages'> + <title>Signing RPM Packages</title> + + <para> + To enable signing RPM packages, you must set up the + following configurations in either your + <filename>local.config</filename> or + <filename>distro.config</filename> file: + <literallayout class='monospaced'> + # Inherit sign_rpm.bbclass to enable signing functionality + INHERIT += " sign_rpm" + # Define the GPG key that will be used for signing. + RPM_GPG_NAME = "<replaceable>key_name</replaceable>" + # Provide passphrase for the key + RPM_GPG_PASSPHRASE = "<replaceable>passphrase</replaceable>" + </literallayout> + <note> + Be sure to supply appropriate values for both + <replaceable>key_name</replaceable> and + <replaceable>passphrase</replaceable> + </note> + Aside from the + <filename>RPM_GPG_NAME</filename> and + <filename>RPM_GPG_PASSPHRASE</filename> variables in the + previous example, two optional variables related to signing + exist: + <itemizedlist> + <listitem><para> + <emphasis><filename>GPG_BIN</filename>:</emphasis> + Specifies a <filename>gpg</filename> binary/wrapper + that is executed when the package is signed. + </para></listitem> + <listitem><para> + <emphasis><filename>GPG_PATH</filename>:</emphasis> + Specifies the <filename>gpg</filename> home + directory used when the package is signed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='processing-package-feeds'> + <title>Processing Package Feeds</title> + + <para> + In addition to being able to sign RPM packages, you can + also enable the OpenEmbedded build system to be able to + handle previously signed package feeds for IPK + packages. + <note> + The OpenEmbedded build system does not currently + support signed DPKG or RPM package feeds. + </note> + The steps you need to take to enable signed package feed + use are similar to the steps used to sign RPM packages. + You must define the following in your + <filename>local.config</filename> or + <filename>distro.config</filename> file: + <literallayout class='monospaced'> + INHERIT += "sign_package_feed" + PACKAGE_FEED_GPG_NAME = "<replaceable>key_name</replaceable>" + PACKAGE_FEED_GPG_PASSPHRASE_FILE = "<replaceable>path_to_file_containing_passphrase</replaceable>" + </literallayout> + For signed package feeds, the passphrase must exist in a + separate file, which is pointed to by the + <filename>PACKAGE_FEED_GPG_PASSPHRASE_FILE</filename> + variable. + Regarding security, keeping a plain text passphrase out of + the configuration is more secure. + </para> + + <para> + Aside from the + <filename>PACKAGE_FEED_GPG_NAME</filename> and + <filename>PACKAGE_FEED_GPG_PASSPHRASE_FILE</filename> + variables, three optional variables related to signed + package feeds exist: + <itemizedlist> + <listitem><para> + <emphasis><filename>GPG_BIN</filename>:</emphasis> + Specifies a <filename>gpg</filename> binary/wrapper + that is executed when the package is signed. + </para></listitem> + <listitem><para> + <emphasis><filename>GPG_PATH</filename>:</emphasis> + Specifies the <filename>gpg</filename> home + directory used when the package is signed. + </para></listitem> + <listitem><para> + <emphasis><filename>PACKAGE_FEED_GPG_SIGNATURE_TYPE</filename>:</emphasis> + Specifies the type of <filename>gpg</filename> + signature. + This variable applies only to RPM and IPK package + feeds. + Allowable values for the + <filename>PACKAGE_FEED_GPG_SIGNATURE_TYPE</filename> + are "ASC", which is the default and specifies ascii + armored, and "BIN", which specifies binary. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + <section id='testing-packages-with-ptest'> <title>Testing Packages With ptest</title> @@ -9129,6 +9743,13 @@ tests, run available tests, and write and add your own tests. </para> + <para> + For information on the test and QA infrastructure available + within the Yocto Project, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#testing-and-quality-assurance'>Testing and Quality Assurance</ulink>" + section in the Yocto Project Reference Manual. + </para> + <section id='enabling-tests'> <title>Enabling Tests</title> @@ -9182,12 +9803,13 @@ <listitem><para><emphasis>Be sure your host's firewall accepts incoming connections from 192.168.7.0/24:</emphasis> - Some of the tests (in particular smart tests) start an - HTTP server on a random high number port, which is - used to serve files to the target. - The smart module serves - <filename>${DEPLOY_DIR}/rpm</filename> so it can run - smart channel commands. That means your host's firewall + Some of the tests (in particular DNF tests) start + an HTTP server on a random high number port, + which is used to serve files to the target. + The DNF module serves + <filename>${WORKDIR}/oe-rootfs-repo</filename> + so it can run DNF channel commands. + That means your host's firewall must accept incoming connections from 192.168.7.0/24, which is the default IP range used for tap devices by <filename>runqemu</filename>.</para></listitem> @@ -9687,7 +10309,7 @@ <listitem><para>The default tests for the image are defined as: <literallayout class='monospaced'> - DEFAULT_TEST_SUITES_pn-<replaceable>image</replaceable> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" + DEFAULT_TEST_SUITES_pn-<replaceable>image</replaceable> = "ping ssh df connman syslog xorg scp vnc date rpm dnf dmesg" </literallayout></para></listitem> <listitem><para>Add your own test to the list of the by using the following: @@ -9885,7 +10507,7 @@ </para></listitem> <listitem><para><emphasis><filename>server_ip</filename>:</emphasis> The host's IP address, which is - usually used by the "smart" test + usually used by the DNF test suite. </para></listitem> <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis> @@ -10044,16 +10666,16 @@ </para> <para> - To help get past the previously mentioned constraints, you can use Gdbserver. - Gdbserver runs on the remote target and does not load any debugging information - from the debugged process. + To help get past the previously mentioned constraints, you can use + gdbserver, which runs on the remote target and does not load any + debugging information from the debugged process. Instead, a GDB instance processes the debugging information that is run on a remote computer - the host GDB. - The host GDB then sends control commands to Gdbserver to make it stop or start the debugged + The host GDB then sends control commands to gdbserver to make it stop or start the debugged program, as well as read or write memory regions of that debugged program. All the debugging information loaded and processed as well as all the heavy debugging is done by the host GDB. - Offloading these processes gives the Gdbserver running on the target a chance to remain + Offloading these processes gives the gdbserver running on the target a chance to remain small and fast. </para> @@ -10064,7 +10686,7 @@ with their debugging information and also be sure the target is compiled with no optimizations. The host GDB must also have local access to all the libraries used by the debugged program. - Because Gdbserver does not need any local debugging information, the binaries on + Because gdbserver does not need any local debugging information, the binaries on the remote target can remain stripped. However, the binaries must also be compiled without optimization so they match the host's binaries. @@ -10107,7 +10729,7 @@ the partial filesystem with the full filesystem. </para></listitem> <listitem><para> - <emphasis>Configure the system to include Gdbserver in + <emphasis>Configure the system to include gdbserver in the target filesystem:</emphasis></para> <para>Make the following addition in either your @@ -10204,18 +10826,18 @@ <listitem><para> <emphasis>Debug a program:</emphasis></para> - <para>Debugging a program involves running Gdbserver + <para>Debugging a program involves running gdbserver on the target and then running Gdb on the host. The example in this step debugs <filename>gzip</filename>: <literallayout class='monospaced'> root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help </literallayout> - For additional Gdbserver options, see the - <ulink url='https://www.gnu.org/software/gdb/documentation/'>Gdb Server Documentation</ulink>. + For additional gdbserver options, see the + <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>. </para> - <para>After running Gdbserver on the target, you need + <para>After running gdbserver on the target, you need to run Gdb on the host and configure it and connect to the target. Use these commands: @@ -10285,10 +10907,10 @@ </section> <section id="platdev-gdb-remotedebug-launch-gdbserver"> - <title>Launch Gdbserver on the Target</title> + <title>Launch gdbserver on the Target</title> <para> - Make sure Gdbserver is installed on the target. + Make sure gdbserver is installed on the target. If it is not, install the package <filename>gdbserver</filename>, which needs the <filename>libthread-db1</filename> package. @@ -10296,15 +10918,15 @@ <para> Here is an example, that when entered from the host, - connects to the target and launches Gdbserver in order to + connects to the target and launches gdbserver in order to "debug" a binary named <filename>helloworld</filename>: <literallayout class='monospaced'> $ gdbserver localhost:2345 /usr/bin/helloworld </literallayout> - Gdbserver should now be listening on port 2345 for debugging + gdbserver should now be listening on port 2345 for debugging commands coming from a remote GDB process that is running on the host computer. - Communication between Gdbserver and the host GDB are done + Communication between gdbserver and the host GDB are done using TCP. To use other communication protocols, please refer to the <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>. @@ -10876,10 +11498,11 @@ <para> Before you employ <filename>DL_DIR</filename> or the - archiver class, you need to decide how you choose to - provide source. - The source archiver class can generate tarballs and SRPMs - and can create them with various levels of compliance in mind. + <filename>archiver</filename> class, you need to decide how + you choose to provide source. + The source <filename>archiver</filename> class can generate + tarballs and SRPMs and can create them with various levels of + compliance in mind. </para> <para> @@ -10974,9 +11597,9 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink> and <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink> - add a copy of the license when the image is built but do not - offer a path for adding licenses for newly installed packages - to an image. + add a copy of the license when the image is built but do + not offer a path for adding licenses for newly installed + packages to an image. <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink> adds a separate package and an upgrade path for adding licenses to an image.</para> @@ -10984,7 +11607,8 @@ </para> <para> - As the source archiver has already archived the original + As the source <filename>archiver</filename> class has already + archived the original unmodified source that contains the license files, you would have already met the requirements for inclusion of the license information with source as defined by the GPL @@ -10996,7 +11620,7 @@ <title>Providing Compilation Scripts and Source Code Modifications</title> <para> - At this point, we have addressed all we need to address + At this point, we have addressed all we need to prior to generating the image. The next two requirements are addressed during the final packaging of the release. @@ -11015,7 +11639,7 @@ and a distro layer, and those those layers are used to patch, compile, package, or modify (in any way) any open source software included in your released images, you - might be required to to release those layers under section 3 of + might be required to release those layers under section 3 of GPLv2 or section 1 of GPLv3. One way of doing that is with a clean checkout of the version of the Yocto Project and layers used diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml index caa066e828..49148abead 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-intro.xml @@ -158,6 +158,7 @@ Toaster, which is a web interface to the Yocto Project's <link linkend='build-system-term'>OpenEmbedded Build System</link>. </para></listitem> +<!-- <listitem><para><emphasis> <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> Eclipse IDE Yocto Plug-in</ulink>:</emphasis> @@ -165,6 +166,13 @@ demonstrates how an application developer uses Yocto Plug-in features within the Eclipse IDE. </para></listitem> +--> + <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-latest-yp-eclipse-plug-in'>Eclipse IDE Yocto Plug-in</ulink>:</emphasis> + Instructions that demonstrate how an application developer + uses the Eclipse Yocto Project Plug-in feature within + the Eclipse IDE. + </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis> A list of commonly asked questions and their answers. diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml index 75c992f16b..ad32ac6291 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml @@ -1394,83 +1394,182 @@ can be reviewed and merged by the appropriate maintainer. </para> - <para> - Before submitting any change, be sure to find out who you should be - notifying. - Several methods exist through which you find out who you should be copying - or notifying: - <itemizedlist> - <listitem><para><emphasis>Maintenance File:</emphasis> - Examine the <filename>maintainers.inc</filename> file, which is - located in the - <link linkend='source-directory'>Source Directory</link> - at <filename>meta-poky/conf/distro/include</filename>, to - see who is responsible for code. - </para></listitem> - <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis> - For BSP maintainers of supported BSPs, you can examine - individual BSP <filename>README</filename> files. - In addition, some layers (such as the <filename>meta-intel</filename> layer), - include a <filename>MAINTAINERS</filename> file which contains - a list of all supported BSP maintainers for that layer. - </para></listitem> - <listitem><para><emphasis>Search by File:</emphasis> - Using <link linkend='git'>Git</link>, you can enter the - following command to bring up a short list of all commits - against a specific file: - <literallayout class='monospaced'> - git shortlog -- <replaceable>filename</replaceable> - </literallayout> - Just provide the name of the file for which you are interested. - The information returned is not ordered by history but does - include a list of all committers grouped by name. - From the list, you can see who is responsible for the bulk of - the changes against the file. - </para></listitem> - </itemizedlist> - </para> + <section id='submit-change-overview'> + <title>Overview</title> - <para> - For a list of the Yocto Project and related mailing lists, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in - the Yocto Project Reference Manual. - </para> + <para> + The Yocto Project uses a mailing list and patch-based workflow + that is similar to the Linux kernel but contains important + differences. + In general, a mailing list exists through which you can submit + patches. + The specific mailing list you need to use depends on the + location of the code you are changing. + Each component (e.g. layer) should have a + <filename>README</filename> file that indicates where to send + the changes and which process to follow. + </para> - <para> - Here is some guidance on which mailing list to use for what type of change: - <itemizedlist> - <listitem><para>For changes to the core - <link linkend='metadata'>Metadata</link>, send your patch to the - <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list. - For example, a change to anything under the <filename>meta</filename> or - <filename>scripts</filename> directories - should be sent to this mailing list.</para></listitem> - <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename> - directory), send your patch to the - <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> - <listitem><para>For changes to <filename>meta-poky</filename>, send your patch to the - <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> - <listitem><para>For changes to other layers hosted on - <filename>yoctoproject.org</filename> (unless the - layer's documentation specifies otherwise), tools, and Yocto Project - documentation, use the - <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem> - <listitem><para>For additional recipes that do not fit into the core Metadata, - you should determine which layer the recipe should go into and submit the - change in the manner recommended by the documentation (e.g. README) supplied - with the layer. If in doubt, please ask on the - <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or - <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink> - mailing lists.</para></listitem> - </itemizedlist> - </para> + <para> + You can send the patch to the mailing list using whichever approach + you feel comfortable with to generate the patch. + Once sent, the patch is usually reviewed by the community at large. + If somebody has concerns with the patch, they will usually voice + their concern over the mailing list. + If a patch does not receive any negative reviews, the maintainer of + the affected layer typically takes the patch, tests it, and then + based on successful testing, merges the patch. + </para> - <para> - When you send a patch, be sure to include a "Signed-off-by:" - line in the same style as required by the Linux kernel. - Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1 - as follows: - <literallayout class='monospaced'> + <para> + Specific to OpenEmbedded-Core, two commonly used testing trees + exist: + <itemizedlist> + <listitem><para> + <emphasis>"ross/mut" branch:</emphasis> + The "mut" (master-under-test) tree + exists in the <filename>poky-contrib</filename> repository + in the + <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>. + </para></listitem> + <listitem><para> + <emphasis>"master-next" branch:</emphasis> + This branch is part of the main + "poky" repository in the Yocto Project source repositories. + </para></listitem> + </itemizedlist> + Maintainers use these branches to test submissions prior to merging + patches. + Thus, you can get an idea of the status of a patch based on + whether the patch has been merged into one of these branches. + </para> + + <para> + This system is imperfect and patches can sometimes get lost in the + flow. + Asking about the status of a patch is reasonable if the patch + has been idle for a while with no feedback. + The Yocto Project does have plans to use + <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> + to track the status of patches and also to automatically preview + patches. + </para> + + <para> + The following sections provide general instructions for both + pushing changes upstream and for submitting changes as patches. + </para> + </section> + + <section id='submit-change-submissions-to-poky'> + <title>Submissions to Poky</title> + + <para> + The "poky" repository, which is the Yocto Project's reference build + environment, is a hybrid repository that contains several + individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto, + documentation, and so forth) built using the combo-layer tool. + The upstream location used for submitting changes varies by + component: + <itemizedlist> + <listitem><para> + <emphasis>Core Metadata:</emphasis> + Send your patch to the + <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink> + mailing list. For example, a change to anything under + the <filename>meta</filename> or + <filename>scripts</filename> directories should be sent + to this mailing list. + </para></listitem> + <listitem><para> + <emphasis>BitBake:</emphasis> + For changes to BitBake (i.e. anything under the + <filename>bitbake</filename> directory), send your patch + to the + <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink> + mailing list. + </para></listitem> + <listitem><para> + <emphasis>"meta-yocto-bsp" and "meta-poky" trees:</emphasis> + These trees are + part of the "meta-yocto" repository in the Yocto Project + source repositories. + Use the + <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink> + mailing list. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='submit-change-submissions-to-other-layers'> + <title>Submissions to Other Layers</title> + + <para> + For changes to other layers hosted in the Yocto Project source + repositories (i.e. <filename>yoctoproject.org</filename>), tools, + and the Yocto Project documentation, use the + <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink> + general mailing list. + <note> + Sometimes a layer's documentation specifies to use a + particular mailing list. + If so, use that list. + </note> + For additional recipes that do not fit into the core Metadata, you + should determine which layer the recipe should go into and submit + the change in the manner recommended by the documentation (e.g. + the <filename>README</filename> file) supplied with the layer. + If in doubt, please ask on the Yocto general mailing list or on + the openembedded-devel mailing list. + </para> + </section> + + <section id='submit-change-patch-submission-details'> + <title>Patch Submission Details</title> + + <para> + When submitting any change, you can check who you should be + notifying. + Use either of these methods to find out: + <itemizedlist> + <listitem><para> + <emphasis>Maintenance File:</emphasis> + Examine the <filename>maintainers.inc</filename> file, which is + located in the + <link linkend='source-directory'>Source Directory</link> + at <filename>meta-poky/conf/distro/include</filename>, to + see who is responsible for code. + </para></listitem> + <listitem><para> + <emphasis>Search by File:</emphasis> + Using <link linkend='git'>Git</link>, you can enter the + following command to bring up a short list of all commits + against a specific file: + <literallayout class='monospaced'> + git shortlog -- <replaceable>filename</replaceable> + </literallayout> + Just provide the name of the file for which you are interested. + The information returned is not ordered by history but does + include a list of all committers grouped by name. + From the list, you can see who is responsible for the bulk of + the changes against the file. + </para></listitem> + </itemizedlist> + </para> + + <para> + For a list of the Yocto Project and related mailing lists, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" + section in the Yocto Project Reference Manual. + </para> + + <para> + When you send a patch, be sure to include a "Signed-off-by:" + line in the same style as required by the Linux kernel. + Adding this line signifies that you, the submitter, have agreed + to the Developer's Certificate of Origin 1.1 as follows: + <literallayout class='monospaced'> Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: @@ -1496,68 +1595,76 @@ personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. - </literallayout> - </para> + </literallayout> + </para> - <para> - In a collaborative environment, it is necessary to have some sort of standard - or method through which you submit changes. - Otherwise, things could get quite chaotic. - One general practice to follow is to make small, controlled changes. - Keeping changes small and isolated aids review, makes merging/rebasing easier - and keeps the change history clean when anyone needs to refer to it in future. - </para> + <para> + In a collaborative environment, it is necessary to have some sort + of standard or method through which you submit changes. + Otherwise, things could get quite chaotic. + One general practice to follow is to make small, controlled changes. + Keeping changes small and isolated aids review, makes + merging/rebasing easier and keeps the change history clean should + anyone need to refer to it in future. + </para> - <para> - When you make a commit, you must follow certain standards established by the - OpenEmbedded and Yocto Project development teams. - For each commit, you must provide a single-line summary of the change and you - should almost always provide a more detailed description of what you did (i.e. - the body of the commit message). - The only exceptions for not providing a detailed description would be if your - change is a simple, self-explanatory change that needs no further description - beyond the summary. - Here are the guidelines for composing a commit message: - <itemizedlist> - <listitem><para>Provide a single-line, short summary of the change. - This summary is typically viewable in the "shortlist" of changes. - Thus, providing something short and descriptive that gives the reader - a summary of the change is useful when viewing a list of many commits. - This short description should be prefixed by the recipe name (if changing a recipe), or - else the short form path to the file being changed. - </para></listitem> - <listitem><para>For the body of the commit message, provide detailed information - that describes what you changed, why you made the change, and the approach - you used. It may also be helpful if you mention how you tested the change. - Provide as much detail as you can in the body of the commit message. - </para></listitem> - <listitem><para> - If the change addresses a specific bug or issue that is - associated with a bug-tracking ID, include a reference to that - ID in your detailed description. - For example, the Yocto Project uses a specific convention for - bug references - any commit that addresses a specific bug should - use the following form for the detailed description: - <literallayout class='monospaced'> + <para> + When you make a commit, you must follow certain standards + established by the OpenEmbedded and Yocto Project development teams. + For each commit, you must provide a single-line summary of the + change and you should almost always provide a more detailed + description of what you did (i.e. the body of the commit message). + The only exceptions for not providing a detailed description would + be if your change is a simple, self-explanatory change that needs + no further description beyond the summary. + Here are the guidelines for composing a commit message: + <itemizedlist> + <listitem><para> + Provide a single-line, short summary of the change. + This summary is typically viewable in the "shortlist" of + changes. + Thus, providing something short and descriptive that + gives the reader a summary of the change is useful when + viewing a list of many commits. + You should prefix this short description with the recipe + name (if changing a recipe), or else with the short form + path to the file being changed. + </para></listitem> + <listitem><para> + For the body of the commit message, provide detailed + information that describes what you changed, why you made + the change, and the approach you used. + It might also be helpful if you mention how you tested + the change. + Provide as much detail as you can in the body of the + commit message. + </para></listitem> + <listitem><para> + If the change addresses a specific bug or issue that is + associated with a bug-tracking ID, include a reference + to that ID in your detailed description. + For example, the Yocto Project uses a specific convention + for bug references - any commit that addresses a specific + bug should use the following form for the detailed + description. + Be sure to use the actual bug-tracking ID from + Bugzilla for + <replaceable>bug-id</replaceable>: + <literallayout class='monospaced'> Fixes [YOCTO #<replaceable>bug-id</replaceable>] <replaceable>detailed description of change</replaceable> - </literallayout></para></listitem> - Where <replaceable>bug-id</replaceable> is replaced with the - specific bug ID from the Yocto Project Bugzilla instance. - </itemizedlist> - </para> - - <para> - You can find more guidance on creating well-formed commit messages at this OpenEmbedded - wiki page: - <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. - </para> + </literallayout> + </para></listitem> + </itemizedlist> + </para> - <para> - The next two sections describe general instructions for both pushing - changes upstream and for submitting changes as patches. - </para> + <para> + You can find more guidance on creating well-formed commit messages + at this OpenEmbedded wiki page: + <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>. + </para> + </section> <section id='pushing-a-change-upstream'> <title>Using Scripts to Push a Change Upstream and Request a Pull</title> diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml index b59f54b085..b8527f670a 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml @@ -278,7 +278,7 @@ applications using the Eclipse Integrated Development Environment (IDE), you will need this plug-in. See the - "<ulink url='&YOCTO_DOCS_SDK_URL;#setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</ulink>" + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-latest-yp-eclipse-plug-in'>Using Eclipse</ulink>" section in the Yocto Project Software Development Kit (SDK) Developer's Guide for more information.</para></listitem> </itemizedlist> @@ -328,6 +328,96 @@ </para> </section> +<section id='flashing-images-using-bmaptool'> + <title>Flashing Images Using <filename>bmaptool</filename></title> + + <para> + An easy way to flash an image to a bootable device is to use + <filename>bmaptool</filename>, which is integrated into the + OpenEmbedded build system. + </para> + + <para> + Following, is an example that shows how to flash a Wic image. + <note> + You can use <filename>bmaptool</filename> to flash any + type of image. + </note> + Use these steps to flash an image using + <filename>bmaptool</filename>: + <note> + Unless you are able to install the + <filename>bmap-tools</filename> package as mentioned in the note + in the second bullet of step 3 further down, you will need to build + <filename>bmaptool</filename> before using it. + Build the tool using the following command: + <literallayout class='monospaced'> + $ bitbake bmap-tools-native + </literallayout> + </note> + <orderedlist> + <listitem><para> + Add the following to your <filename>local.conf</filename> + file: + <literallayout class='monospaced'> + IMAGE_FSTYPES += "wic wic.bmap" + </literallayout> + </para></listitem> + <listitem><para> + Either have your image ready (pre-built) or take the step + build the image: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + Flash the image to the media by using + <filename>bmaptool</filename> depending on your particular + setup: + <itemizedlist> + <listitem><para> + If you have write access to the media, + use this command form: + <literallayout class='monospaced'> + $ oe-run-native bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + If you do not have write access to + the media, use the following + commands: + <literallayout class='monospaced'> + $ sudo bash + $ PATH=tmp/sysroots/x86_64-linux/usr/bin/ bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable> + </literallayout> + <note> + If you are using Ubuntu or Debian distributions, + you can install the + <filename>bmap-tools</filename> package using the + following command and then use the tool + without specifying + <filename>PATH</filename> even from the + root account: + <literallayout class='monospaced'> + $ sudo apt-get install bmap-tools + </literallayout> + </note> + </para></listitem> + </itemizedlist> + </para></listitem> + </orderedlist> + </para> + + <para> + For help on the <filename>bmaptool</filename> command, use either of + the following commands: + <literallayout class='monospaced'> + $ bmaptool --help + $ oe-run-native bmaptool --help + </literallayout> + </para> +</section> + <section id='using-pre-built-binaries-and-qemu'> <title>Using Pre-Built Binaries and QEMU</title> diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml index 2ce1652fc4..26ee974e42 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml @@ -92,14 +92,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -116,12 +131,32 @@ Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Development + Manual associated with this Yocto Project release + (version &YOCTO_DOC_VERSION;), + see the Yocto Project Development Manual from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Development Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/dev-manual/dev-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> </bookinfo> diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml index 9e15f178a6..a5ccfdc300 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml @@ -83,13 +83,14 @@ The linux-yocto style recipes can optionally define the following variables: <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink> + KERNEL_FEATURES + LINUX_KERNEL_TYPE </literallayout> </para> <para> - <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> + defines the kernel type to be used in assembling the configuration. If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>, it defaults to "standard". @@ -134,7 +135,9 @@ </para> <para> - You can use the <filename>KERNEL_FEATURES</filename> variable + You can use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable to include features (configuration fragments, patches, or both) that are not already included by the <filename>KMACHINE</filename> and <filename>LINUX_KERNEL_TYPE</filename> variable combination. @@ -167,175 +170,6 @@ </para> </section> -<section id='kernel-metadata-location'> - <title>Kernel Metadata Location</title> - - <para> - Kernel Metadata always exists outside of the kernel tree either - defined in a kernel recipe (recipe-space) or outside of the recipe. - Where you choose to define the Metadata depends on what you want - to do and how you intend to work. - Regardless of where you define the kernel Metadata, the syntax used - applies equally. - </para> - - <para> - If you are unfamiliar with the Linux kernel and only wish - to apply a configuration and possibly a couple of patches provided to - you by others, the recipe-space method is recommended. - This method is also a good approach if you are working with Linux kernel - sources you do not control or if you just do not want to maintain a - Linux kernel Git repository on your own. - For partial information on how you can define kernel Metadata in - the recipe-space, see the - "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" - section. - </para> - - <para> - Conversely, if you are actively developing a kernel and are already - maintaining a Linux kernel Git repository of your own, you might find - it more convenient to work with kernel Metadata kept outside the - recipe-space. - Working with Metadata in this area can make iterative development of - the Linux kernel more efficient outside of the BitBake environment. - </para> - - <section id='recipe-space-metadata'> - <title>Recipe-Space Metadata</title> - - <para> - When stored in recipe-space, the kernel Metadata files reside in a - directory hierarchy below - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>. - For a linux-yocto recipe or for a Linux kernel recipe derived - by copying and modifying - <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename> - to a recipe in your layer, <filename>FILESEXTRAPATHS</filename> - is typically set to - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>. - See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" - section for more information. - </para> - - <para> - Here is an example that shows a trivial tree of kernel Metadata - stored in recipe-space within a BSP layer: - <literallayout class='monospaced'> - meta-<replaceable>my_bsp_layer</replaceable>/ - `-- recipes-kernel - `-- linux - `-- linux-yocto - |-- bsp-standard.scc - |-- bsp.cfg - `-- standard.cfg - </literallayout> - </para> - - <para> - When the Metadata is stored in recipe-space, you must take - steps to ensure BitBake has the necessary information to decide - what files to fetch and when they need to be fetched again. - It is only necessary to specify the <filename>.scc</filename> - files on the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. - BitBake parses them and fetches any files referenced in the - <filename>.scc</filename> files by the <filename>include</filename>, - <filename>patch</filename>, or <filename>kconf</filename> commands. - Because of this, it is necessary to bump the recipe - <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> - value when changing the content of files not explicitly listed - in the <filename>SRC_URI</filename>. - </para> - </section> - - <section id='metadata-outside-the-recipe-space'> - <title>Metadata Outside the Recipe-Space</title> - - <para> - When stored outside of the recipe-space, the kernel Metadata - files reside in a separate repository. - The OpenEmbedded build system adds the Metadata to the build as - a "ktype=meta" repository through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable. - As an example, consider the following <filename>SRC_URI</filename> - statement from the <filename>linux-yocto_4.4.bb</filename> - kernel recipe: - <literallayout class='monospaced'> - SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \ - git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}" - </literallayout> - <filename>${KMETA}</filename>, in this context, is simply used to - name the directory into which the Git fetcher places the Metadata. - This behavior is no different than any multi-repository - <filename>SRC_URI</filename> statement used in a recipe. - </para> - - <para> - You can keep kernel Metadata in a "kernel-cache", which is a - directory containing configuration fragments. - As with any Metadata kept outside the recipe-space, you simply - need to use the <filename>SRC_URI</filename> statement with the - "type=kmeta" attribute. - Doing so makes the kernel Metadata available during the - configuration phase. - </para> - -<!-- - - - <para> - Following is an example that shows how a trivial tree of Metadata - is stored in a custom Linux kernel Git repository: - <literallayout class='monospaced'> - meta/ - `‐‐ cfg - `‐‐ kernel-cache - |‐‐ bsp-standard.scc - |‐‐ bsp.cfg - `‐‐ standard.cfg - </literallayout> - </para> - - <para> - To use a branch different from where the sources reside, - specify the branch in the <filename>KMETA</filename> variable - in your Linux kernel recipe. - Here is an example: - <literallayout class='monospaced'> - KMETA = "meta" - </literallayout> - To use the same branch as the sources, set - <filename>KMETA</filename> to an empty string: - <literallayout class='monospaced'> - KMETA = "" - </literallayout> - If you are working with your own sources and want to create an - orphan <filename>meta</filename> branch, use these commands - from within your Linux kernel Git repository: - <literallayout class='monospaced'> - $ git checkout ‐‐orphan meta - $ git rm -rf . - $ git commit ‐‐allow-empty -m "Create orphan meta branch" - </literallayout> - </para> ---> - - <para> - If you modify the Metadata, you must not forget to update the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> - statements in the kernel's recipe. - In particular, you need to update the - <filename>SRCREV_meta</filename> variable to match the commit in - the <filename>KMETA</filename> branch you wish to use. - Changing the data in these branches and not updating the - <filename>SRCREV</filename> statements to match will cause the - build to fetch an older commit. - </para> - </section> -</section> - <section id='kernel-metadata-syntax'> <title>Kernel Metadata Syntax</title> @@ -690,193 +524,426 @@ <title>BSP Descriptions</title> <para> - BSP descriptions combine kernel types with hardware-specific - features. - The hardware-specific portion is typically defined - independently, and then aggregated with each supported kernel - type. - Consider this simple BSP description that supports the - <replaceable>mybsp</replaceable> machine: - <literallayout class='monospaced'> - <replaceable>mybsp</replaceable>.scc: - define KMACHINE <replaceable>mybsp</replaceable> - define KTYPE standard - define KARCH i386 - - kconf <replaceable>mybsp</replaceable>.cfg - </literallayout> - Every BSP description should define the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, - and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> - variables. - These variables allow the OpenEmbedded build system to identify - the description as meeting the criteria set by the recipe being - built. - This simple example supports the "mybsp" machine for the "standard" - kernel and the "i386" architecture. + BSP descriptions (i.e. <filename>*.scc</filename> files) + combine kernel types with hardware-specific features. + The hardware-specific Metadata is typically defined + independently in the BSP layer, and then aggregated with each + supported kernel type. + <note> + For BSPs supported by the Yocto Project, the BSP description + files are located in the <filename>bsp</filename> directory + of the <filename>yocto-kernel-cache</filename> repository + organized under the "Yocto Linux Kernel" heading in the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>. + </note> </para> <para> - Be aware that a hard link between the - <filename>KTYPE</filename> variable and a kernel type - description file does not exist. - Thus, if you do not have kernel types defined in your kernel - Metadata, you only need to ensure that the kernel recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> - variable and the <filename>KTYPE</filename> variable in the - BSP description file match. - <note> - Future versions of the tooling make the specification of - <filename>KTYPE</filename> in the BSP optional. - </note> + This section provides a BSP description structural overview along + with aggregation concepts as well as a detailed example using + a BSP supported by the Yocto Project (i.e. Minnow Board). </para> + <section id='bsp-description-file-overview'> + <title>Overview</title> + + <para> + For simplicity, consider the following top-level BSP + description file. + Top-level BSP descriptions files employ both a structure + and naming convention for consistency. + The naming convention for the file is as follows: + <literallayout class='monospaced'> + <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc + </literallayout> + Here are some example top-level BSP filenames for the + Minnow Board BSP, which is supported by the Yocto Project: + <literallayout class='monospaced'> + minnow-standard.scc + minnow-preempt-rt.scc + minnow-tiny.scc + </literallayout> + Each file uses the BSP name followed by the kernel type. + </para> + + <para> + is simple BSP description file whose name has the + form + <replaceable>mybsp</replaceable><filename>-standard</filename> + and supports the <replaceable>mybsp</replaceable> machine using + a standard kernel: + <literallayout class='monospaced'> + define KMACHINE <replaceable>mybsp</replaceable> + define KTYPE standard + define KARCH i386 + + include ktypes/standard + + include <replaceable>mybsp</replaceable>.scc + + kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg + </literallayout> + Every top-level BSP description file should define the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>, + and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink> + variables. + These variables allow the OpenEmbedded build system to identify + the description as meeting the criteria set by the recipe being + built. + This simple example supports the "mybsp" machine for the "standard" + kernel and the "i386" architecture. + </para> + + <para> + Be aware that a hard link between the + <filename>KTYPE</filename> variable and a kernel type description + file does not exist. + Thus, if you do not have kernel types defined in your kernel + Metadata, you only need to ensure that the kernel recipe's + <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink> + variable and the <filename>KTYPE</filename> variable in the + BSP description file match. + <note> + Future versions of the tooling make the specification of + <filename>KTYPE</filename> in the BSP optional. + </note> + </para> + + <para> + To separate your kernel policy from your hardware configuration, + you include a kernel type (<filename>ktype</filename>), such as + "standard". + In the previous example, this is done using the following: + <literallayout class='monospaced'> + include ktypes/standard + </literallayout> + In the previous example, <filename>ktypes/standard.scc</filename> + aggregates all the configuration fragments, patches, and + features that make up your standard kernel policy. + See the "<link linkend='kernel-types'>Kernel Types</link>" section + for more information. + </para> + + <para> + To aggregate common configurations and features specific to the + kernel for <replaceable>mybsp</replaceable>, use the following: + <literallayout class='monospaced'> + include <replaceable>mybsp</replaceable>.scc + </literallayout> + For information on how to break a complete + <filename>.config</filename> file into the various + configuration fragments, see the + "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" + section. + </para> + + <para> + Finally, if you have any configurations specific to the + hardware that are not in a <filename>*.scc</filename> file, + you can include them as follows: + <literallayout class='monospaced'> + kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg + </literallayout> + </para> + </section> + + <section id='bsp-description-file-example-minnow'> + <title>Example</title> + + <para> + Many real-world examples are more complex. + Like any other <filename>.scc</filename> file, BSP + descriptions can aggregate features. + Consider the Minnow BSP definition from the + <filename>linux-yocto-4.4</filename> in the + Yocto Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> + (i.e. + <filename>yocto-kernel-cache/bsp/minnow</filename>): + <literallayout class='monospaced'> + minnow.scc: + include cfg/x86.scc + include features/eg20t/eg20t.scc + include cfg/dmaengine.scc + include features/power/intel.scc + include cfg/efi.scc + include features/usb/ehci-hcd.scc + include features/usb/ohci-hcd.scc + include features/usb/usb-gadgets.scc + include features/usb/touchscreen-composite.scc + include cfg/timer/hpet.scc + include features/leds/leds.scc + include features/spi/spidev.scc + include features/i2c/i2cdev.scc + include features/mei/mei-txe.scc + + # Earlyprintk and port debug requires 8250 + kconf hardware cfg/8250.cfg + + kconf hardware minnow.cfg + kconf hardware minnow-dev.cfg + </literallayout> + </para> + + <para> + The <filename>minnow.scc</filename> description file includes + a hardware configuration fragment + (<filename>minnow.cfg</filename>) specific to the Minnow + BSP as well as several more general configuration + fragments and features enabling hardware found on the + machine. + This <filename>minnow.scc</filename> description file is then + included in each of the three + "minnow" description files for the supported kernel types + (i.e. "standard", "preempt-rt", and "tiny"). + Consider the "minnow" description for the "standard" kernel + type: + <literallayout class='monospaced'> + minnow-standard.scc: + define KMACHINE minnow + define KTYPE standard + define KARCH i386 + + include ktypes/standard + + include minnow.scc + + # Extra minnow configs above the minimal defined in minnow.scc + include cfg/efi-ext.scc + include features/media/media-all.scc + include features/sound/snd_hda_intel.scc + + # The following should really be in standard.scc + # USB live-image support + include cfg/usb-mass-storage.scc + include cfg/boot-live.scc + + # Basic profiling + include features/latencytop/latencytop.scc + include features/profiling/profiling.scc + + # Requested drivers that don't have an existing scc + kconf hardware minnow-drivers-extra.cfg + </literallayout> + The <filename>include</filename> command midway through the file + includes the <filename>minnow.scc</filename> description that + defines all enabled hardware for the BSP that is common to + all kernel types. + Using this command significantly reduces duplication. + </para> + + <para> + Now consider the "minnow" description for the "tiny" kernel + type: + <literallayout class='monospaced'> + minnow-tiny.scc: + define KMACHINE minnow + define KTYPE tiny + define KARCH i386 + + include ktypes/tiny + + include minnow.scc + </literallayout> + As you might expect, the "tiny" description includes quite a + bit less. + In fact, it includes only the minimal policy defined by the + "tiny" kernel type and the hardware-specific configuration + required for booting the machine along with the most basic + functionality of the system as defined in the base "minnow" + description file. + </para> + + <para> + Notice again the three critical variables: + <filename>KMACHINE</filename>, <filename>KTYPE</filename>, + and <filename>KARCH</filename>. + Of these variables, only the <filename>KTYPE</filename> has changed. + It is now set to "tiny". + </para> + </section> + </section> +</section> + +<section id='kernel-metadata-location'> + <title>Kernel Metadata Location</title> + + <para> + Kernel Metadata always exists outside of the kernel tree either + defined in a kernel recipe (recipe-space) or outside of the recipe. + Where you choose to define the Metadata depends on what you want + to do and how you intend to work. + Regardless of where you define the kernel Metadata, the syntax used + applies equally. + </para> + + <para> + If you are unfamiliar with the Linux kernel and only wish + to apply a configuration and possibly a couple of patches provided to + you by others, the recipe-space method is recommended. + This method is also a good approach if you are working with Linux kernel + sources you do not control or if you just do not want to maintain a + Linux kernel Git repository on your own. + For partial information on how you can define kernel Metadata in + the recipe-space, see the + "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" + section. + </para> + + <para> + Conversely, if you are actively developing a kernel and are already + maintaining a Linux kernel Git repository of your own, you might find + it more convenient to work with kernel Metadata kept outside the + recipe-space. + Working with Metadata in this area can make iterative development of + the Linux kernel more efficient outside of the BitBake environment. + </para> + + <section id='recipe-space-metadata'> + <title>Recipe-Space Metadata</title> + <para> - If you did want to separate your kernel policy from your - hardware configuration, you could do so by specifying a kernel - type, such as "standard" and including that description file - in the BSP description file. - See the "<link linkend='kernel-types'>Kernel Types</link>" section - for more information. + When stored in recipe-space, the kernel Metadata files reside in a + directory hierarchy below + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>. + For a linux-yocto recipe or for a Linux kernel recipe derived + by copying and modifying + <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename> + to a recipe in your layer, <filename>FILESEXTRAPATHS</filename> + is typically set to + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>. + See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>" + section for more information. </para> <para> - You might also have multiple hardware configurations that you - aggregate into a single hardware description file that you - could include in the BSP description file, rather than referencing - a single <filename>.cfg</filename> file. - Consider the following: + Here is an example that shows a trivial tree of kernel Metadata + stored in recipe-space within a BSP layer: <literallayout class='monospaced'> - <replaceable>mybsp</replaceable>.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - - include standard.scc - include <replaceable>mybsp</replaceable>-hw.scc + meta-<replaceable>my_bsp_layer</replaceable>/ + `-- recipes-kernel + `-- linux + `-- linux-yocto + |-- bsp-standard.scc + |-- bsp.cfg + `-- standard.cfg </literallayout> </para> <para> - In the above example, <filename>standard.scc</filename> - aggregates all the configuration fragments, patches, and - features that make up your standard kernel policy whereas - <replaceable>mybsp</replaceable><filename>-hw.scc</filename> - aggregates all those necessary - to support the hardware available on the - <replaceable>mybsp</replaceable> machine. - For information on how to break a complete - <filename>.config</filename> file into the various - configuration fragments, see the - "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" - section. + When the Metadata is stored in recipe-space, you must take + steps to ensure BitBake has the necessary information to decide + what files to fetch and when they need to be fetched again. + It is only necessary to specify the <filename>.scc</filename> + files on the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. + BitBake parses them and fetches any files referenced in the + <filename>.scc</filename> files by the <filename>include</filename>, + <filename>patch</filename>, or <filename>kconf</filename> commands. + Because of this, it is necessary to bump the recipe + <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> + value when changing the content of files not explicitly listed + in the <filename>SRC_URI</filename>. </para> <para> - Many real-world examples are more complex. - Like any other <filename>.scc</filename> file, BSP - descriptions can aggregate features. - Consider the Minnow BSP definition from the - <filename>linux-yocto-3.19</filename> - Git repository: + If the BSP description is in recipe space, you cannot simply list + the <filename>*.scc</filename> in the <filename>SRC_URI</filename> + statement. + You need to use the following form from your kernel append file: <literallayout class='monospaced'> - minnow.scc: - include cfg/x86.scc - include features/eg20t/eg20t.scc - include cfg/dmaengine.scc - include features/power/intel.scc - include cfg/efi.scc - include features/usb/ehci-hcd.scc - include features/usb/ohci-hcd.scc - include features/usb/usb-gadgets.scc - include features/usb/touchscreen-composite.scc - include cfg/timer/hpet.scc - include cfg/timer/rtc.scc - include features/leds/leds.scc - include features/spi/spidev.scc - include features/i2c/i2cdev.scc - - # Earlyprintk and port debug requires 8250 - kconf hardware cfg/8250.cfg - - kconf hardware minnow.cfg - kconf hardware minnow-dev.cfg + SRC_URI_append_<replaceable>myplatform</replaceable> = " \ + file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \ + " </literallayout> </para> + </section> + + <section id='metadata-outside-the-recipe-space'> + <title>Metadata Outside the Recipe-Space</title> <para> - The <filename>minnow.scc</filename> description file includes - a hardware configuration fragment - (<filename>minnow.cfg</filename>) specific to the Minnow - BSP as well as several more general configuration - fragments and features enabling hardware found on the - machine. - This description file is then included in each of the three - "minnow" description files for the supported kernel types - (i.e. "standard", "preempt-rt", and "tiny"). - Consider the "minnow" description for the "standard" kernel - type: + When stored outside of the recipe-space, the kernel Metadata + files reside in a separate repository. + The OpenEmbedded build system adds the Metadata to the build as + a "ktype=meta" repository through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable. + As an example, consider the following <filename>SRC_URI</filename> + statement from the <filename>linux-yocto_4.4.bb</filename> + kernel recipe: <literallayout class='monospaced'> - minnow-standard.scc: - define KMACHINE minnow - define KTYPE standard - define KARCH i386 - - include ktypes/standard - - include minnow.scc + SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \ + git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}" + </literallayout> + <filename>${KMETA}</filename>, in this context, is simply used to + name the directory into which the Git fetcher places the Metadata. + This behavior is no different than any multi-repository + <filename>SRC_URI</filename> statement used in a recipe (e.g. + see the previous section). + </para> - # Extra minnow configs above the minimal defined in minnow.scc - include cfg/efi-ext.scc - include features/media/media-all.scc - include features/sound/snd_hda_intel.scc + <para> + You can keep kernel Metadata in a "kernel-cache", which is a + directory containing configuration fragments. + As with any Metadata kept outside the recipe-space, you simply + need to use the <filename>SRC_URI</filename> statement with the + "type=kmeta" attribute. + Doing so makes the kernel Metadata available during the + configuration phase. + </para> - # The following should really be in standard.scc - # USB live-image support - include cfg/usb-mass-storage.scc - include cfg/boot-live.scc +<!-- - # Basic profiling - include features/latencytop/latencytop.scc - include features/profiling/profiling.scc - # Requested drivers that don't have an existing scc - kconf hardware minnow-drivers-extra.cfg + <para> + Following is an example that shows how a trivial tree of Metadata + is stored in a custom Linux kernel Git repository: + <literallayout class='monospaced'> + meta/ + `‐‐ cfg + `‐‐ kernel-cache + |‐‐ bsp-standard.scc + |‐‐ bsp.cfg + `‐‐ standard.cfg </literallayout> - The <filename>include</filename> command midway through the file - includes the <filename>minnow.scc</filename> description that - defines all hardware enablements for the BSP that is common to all - kernel types. - Using this command significantly reduces duplication. </para> <para> - Now consider the "minnow" description for the "tiny" kernel type: + To use a branch different from where the sources reside, + specify the branch in the <filename>KMETA</filename> variable + in your Linux kernel recipe. + Here is an example: <literallayout class='monospaced'> - minnow-tiny.scc: - define KMACHINE minnow - define KTYPE tiny - define KARCH i386 - - include ktypes/tiny - - include minnow.scc + KMETA = "meta" + </literallayout> + To use the same branch as the sources, set + <filename>KMETA</filename> to an empty string: + <literallayout class='monospaced'> + KMETA = "" + </literallayout> + If you are working with your own sources and want to create an + orphan <filename>meta</filename> branch, use these commands + from within your Linux kernel Git repository: + <literallayout class='monospaced'> + $ git checkout ‐‐orphan meta + $ git rm -rf . + $ git commit ‐‐allow-empty -m "Create orphan meta branch" </literallayout> - As you might expect, the "tiny" description includes quite a - bit less. - In fact, it includes only the minimal policy defined by the - "tiny" kernel type and the hardware-specific configuration required - for booting the machine along with the most basic functionality of - the system as defined in the base "minnow" description file. </para> +--> <para> - Notice again the three critical variables: - <filename>KMACHINE</filename>, <filename>KTYPE</filename>, - and <filename>KARCH</filename>. - Of these variables, only the <filename>KTYPE</filename> has changed. - It is now set to "tiny". + If you modify the Metadata, you must not forget to update the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> + statements in the kernel's recipe. + In particular, you need to update the + <filename>SRCREV_meta</filename> variable to match the commit in + the <filename>KMETA</filename> branch you wish to use. + Changing the data in these branches and not updating the + <filename>SRCREV</filename> statements to match will cause the + build to fetch an older commit. </para> </section> </section> diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml index a9aafd3c21..aa40fc852a 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml @@ -31,15 +31,19 @@ (<filename>.bbappend</filename>) and provides a convenient mechanism to create your own recipe files (<filename>.bb</filename>). - For details on how to create and work with layers, see the following - sections in the Yocto Project Development Manual: - <itemizedlist> - <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for - general information on layers and how to create layers.</para></listitem> - <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for - specific instructions on setting up a layer for kernel - development.</para></listitem> - </itemizedlist> + For details on how to create and work with layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Manual. + <note><title>Tip</title> + The Yocto Project comes with many tools that simplify + tasks you need to perform. + One such tool is the <filename>yocto-layer create</filename> + script, which simplifies creating a new layer. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>" + section in the Yocto Project Development Manual for more + information. + </note> </para> </section> @@ -84,11 +88,11 @@ You also name it accordingly based on the linux-yocto recipe you are using. For example, if you are modifying the - <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename> + <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename> recipe, the append file will typically be located as follows within your custom layer: <literallayout class='monospaced'> - <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend </literallayout> The append file should initially extend the <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> @@ -114,6 +118,151 @@ <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. </note> </para> + + <para> + As an example, consider the following append file + used by the BSPs in <filename>meta-yocto-bsp</filename>: + <literallayout class='monospaced'> + meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend + </literallayout> + The following listing shows the file. + Be aware that the actual commit ID strings in this + example listing might be different than the actual strings + in the file from the <filename>meta-yocto-bsp</filename> + layer upstream. + <literallayout class='monospaced'> + KBRANCH_genericx86 = "standard/base" + KBRANCH_genericx86-64 = "standard/base" + + KMACHINE_genericx86 ?= "common-pc" + KMACHINE_genericx86-64 ?= "common-pc-64" + KBRANCH_edgerouter = "standard/edgerouter" + KBRANCH_beaglebone = "standard/beaglebone" + KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" + + SRCREV_machine_genericx86 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2" + SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2" + SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c" + SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c" + SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3" + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone = "beaglebone" + COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" + + LINUX_VERSION_genericx86 = "4.4.41" + LINUX_VERSION_genericx86-64 = "4.4.41" + LINUX_VERSION_edgerouter = "4.4.53" + LINUX_VERSION_beaglebone = "4.4.53" + LINUX_VERSION_mpc8315e-rdb = "4.4.53" + </literallayout> + This append file contains statements used to support + several BSPs that ship with the Yocto Project. + The file defines machines using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> + variable and uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + variable to ensure the machine name used by the OpenEmbedded + build system maps to the machine name used by the Linux Yocto + kernel. + The file also uses the optional + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable to ensure the build process uses the + appropriate kernel branch. + </para> + + <para> + Although this particular example does not use it, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable could be used to enable features specific to + the kernel. + The append file points to specific commits in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + Git repository and the <filename>meta</filename> Git repository + branches to identify the exact kernel needed to build the + BSP. + </para> + + <para> + One thing missing in this particular BSP, which you will + typically need when developing a BSP, is the kernel configuration + file (<filename>.config</filename>) for your BSP. + When developing a BSP, you probably have a kernel configuration + file or a set of kernel configuration files that, when taken + together, define the kernel configuration for your BSP. + You can accomplish this definition by putting the configurations + in a file or a set of files inside a directory located at the + same level as your kernel's append file and having the same + name as the kernel's main recipe file. + With all these conditions met, simply reference those files in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement in the append file. + </para> + + <para> + For example, suppose you had some configuration options + in a file called <filename>network_configs.cfg</filename>. + You can place that file inside a directory named + <filename>linux-yocto</filename> and then add + a <filename>SRC_URI</filename> statement such as the + following to the append file. + When the OpenEmbedded build system builds the kernel, the + configuration options are picked up and applied. + <literallayout class='monospaced'> + SRC_URI += "file://network_configs.cfg" + </literallayout> + </para> + + <para> + To group related configurations into multiple files, you + perform a similar procedure. + Here is an example that groups separate configurations + specifically for Ethernet and graphics into their own + files and adds the configurations by using a + <filename>SRC_URI</filename> statement like the following + in your append file: + <literallayout class='monospaced'> + SRC_URI += "file://myconfig.cfg \ + file://eth.cfg \ + file://gfx.cfg" + </literallayout> + </para> + + <para> + Another variable you can use in your kernel recipe append + file is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable. + When you use this statement, you are extending the locations + used by the OpenEmbedded system to look for files and + patches as the recipe is processed. + </para> + + <note> + <para> + Other methods exist to accomplish grouping and defining configuration options. + For example, if you are working with a local clone of the kernel repository, + you could checkout the kernel's <filename>meta</filename> branch, make your changes, + and then push the changes to the local bare clone of the kernel. + The result is that you directly add configuration options to the + <filename>meta</filename> branch for your BSP. + The configuration options will likely end up in that location anyway if the BSP gets + added to the Yocto Project. + </para> + + <para> + In general, however, the Yocto Project maintainers take care of moving the + <filename>SRC_URI</filename>-specified + configuration options to the kernel's <filename>meta</filename> branch. + Not only is it easier for BSP developers to not have to worry about putting those + configurations in the branch, but having the maintainers do it allows them to apply + 'global' knowledge about the kinds of common configuration options multiple BSPs in + the tree are typically using. + This allows for promotion of common configurations into common features. + </para> + </note> </section> <section id='applying-patches'> diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml index 2b99ad2dde..9e0517d4af 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-faq.xml @@ -72,7 +72,7 @@ <filename>RDEPENDS_kernel-base</filename> to include or not include "kernel-image".</para> <para>See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>" + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" section in the Yocto Project Development Manual for information on how to use an append file to override metadata. </para> diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml index b96acd6f0c..28a3364084 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml @@ -77,14 +77,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -98,12 +113,33 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Linux + Kernel Development Manual associated with this Yocto + Project release (version &YOCTO_DOC_VERSION;), + see the Yocto Project Linux Kernel Development + Manual from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Linux Kernel Development Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/kernel-dev/kernel-dev.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> </bookinfo> diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment.png b/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment.png Binary files differindex 82b7a55a35..35969038c9 100644 --- a/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment.png +++ b/import-layers/yocto-poky/documentation/mega-manual/figures/yocto-environment.png diff --git a/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml b/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml index 157feac311..d06f851374 100644 --- a/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml +++ b/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml @@ -61,14 +61,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -82,12 +97,32 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_MM_URL;'>Yocto Project Mega-Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project + Mega-Manual associated with this Yocto Project release + (version &YOCTO_DOC_VERSION;), + see the Yocto Project Mega-Manual from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Mega-Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/mega-manual/mega-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> @@ -200,6 +235,9 @@ xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/technical-details.xml"/> <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-release-process.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/migration.xml"/> <xi:include diff --git a/import-layers/yocto-poky/documentation/poky.ent b/import-layers/yocto-poky/documentation/poky.ent index 364020792a..14d67e5746 100644 --- a/import-layers/yocto-poky/documentation/poky.ent +++ b/import-layers/yocto-poky/documentation/poky.ent @@ -1,12 +1,12 @@ -<!ENTITY DISTRO "2.2.2"> -<!ENTITY DISTRO_COMPRESSED "222"> -<!ENTITY DISTRO_NAME_NO_CAP "morty"> -<!ENTITY DISTRO_NAME "Morty"> -<!ENTITY YOCTO_DOC_VERSION "2.2.2"> -<!ENTITY POKYVERSION "17.0.1"> -<!ENTITY POKYVERSION_COMPRESSED "1702"> +<!ENTITY DISTRO "2.3.4"> +<!ENTITY DISTRO_COMPRESSED "234"> +<!ENTITY DISTRO_NAME_NO_CAP "pyro"> +<!ENTITY DISTRO_NAME "Pyro"> +<!ENTITY YOCTO_DOC_VERSION "2.3.4"> +<!ENTITY POKYVERSION "18.0.4"> +<!ENTITY POKYVERSION_COMPRESSED "1804"> <!ENTITY YOCTO_POKY "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;"> -<!ENTITY COPYRIGHT_YEAR "2010-2017"> +<!ENTITY COPYRIGHT_YEAR "2010-2018"> <!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org"> <!ENTITY YOCTO_HOME_URL "http://www.yoctoproject.org"> <!ENTITY YOCTO_LISTS_URL "http://lists.yoctoproject.org"> @@ -61,15 +61,18 @@ <!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env"> <!ENTITY OE_INIT_FILE "oe-init-build-env"> <!ENTITY UBUNTU_HOST_PACKAGES_ESSENTIAL "gawk wget git-core diffstat unzip texinfo gcc-multilib \ - build-essential chrpath socat cpio python python3 python3-pip python3-pexpect"> + build-essential chrpath socat cpio python python3 python3-pip python3-pexpect \ + xz-utils debianutils iputils-ping"> <!ENTITY 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 \ - findutils which file cpio python python3-pip python3-pexpect"> + python3-pexpect findutils which file cpio python python3-pip xz"> <!ENTITY 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"> -<!ENTITY CENTOS_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \ + python3-pexpect xz which"> +<!ENTITY CENTOS_HOST_PACKAGES_ESSENTIAL "-y epel-release + $ sudo yum makecache + $ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat \ - perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python3-pip python3-pexpect"> - + perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python34-pip xz \ + which"> diff --git a/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml b/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml index a88934f6e6..b668fd47ad 100644 --- a/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml +++ b/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml @@ -77,14 +77,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -101,12 +116,33 @@ Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Profiling + and Tracing Manual associated with this Yocto Project + release (version &YOCTO_DOC_VERSION;), + see the Yocto Project Profiling and Tracing Manual + from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Profiling and Tracing Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/profile-manual/profile-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> </bookinfo> diff --git a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml index b73e59ca7e..923ed21da3 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml @@ -867,6 +867,19 @@ <para> This step in the build process consists of three tasks: <itemizedlist> + <listitem><para> + <emphasis><link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>:</emphasis> + This task sets up the two sysroots in + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename> + (i.e. <filename>recipe-sysroot</filename> and + <filename>recipe-sysroot-native</filename>) so that + the sysroots contain the contents of the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + tasks of the recipes on which the recipe + containing the tasks depends. + A sysroot exists for both the target and for the native + binaries, which run on the host system. + </para></listitem> <listitem><para><emphasis><filename>do_configure</filename>:</emphasis> This task configures the source by enabling and disabling any build-time and configuration options for @@ -1054,7 +1067,7 @@ <para> Package installation is under control of the package manager - (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or + (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or not package management is enabled for the target. At the end of the process, if package management is not enabled for the target, the package manager's data files @@ -1392,17 +1405,6 @@ relationship the function needs to be passed. The function returns a True or False value. </para> - - <para> - Once the setscene process completes, the OpenEmbedded build - system has a list of tasks that it believes it can "accelerate" - and therefore does not need to run. - There is a final function call to the function specified by the - <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> - variable that is able to require the tasks to be run that - that the OpenEmbedded build system initially was going to - skip. - </para> </section> </section> @@ -1521,23 +1523,26 @@ the environment before using the tools. </para> - <note> - <para> - The Yocto Project supports several methods by which you can - set up this cross-development environment. - These methods include downloading pre-built SDK installers - or building and installing your own SDK installer. - </para> - - <para> - For background information on cross-development toolchains - in the Yocto Project development environment, see the - "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" - section. - For information on setting up a cross-development - environment, see the - <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. - </para> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + The Yocto Project supports several methods by which you can + set up this cross-development environment. + These methods include downloading pre-built SDK installers + or building and installing your own SDK installer. + </para></listitem> + <listitem><para> + For background information on cross-development toolchains + in the Yocto Project development environment, see the + "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" + section. + </para></listitem> + <listitem><para> + For information on setting up a cross-development + environment, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + </para></listitem> + </itemizedlist> </note> <para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml index ddf6a860eb..eec6cb34f1 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml @@ -296,7 +296,7 @@ Yocto Project documentation manuals: <literallayout class='monospaced'> $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc + docbook-dtds docbook-utils fop libxslt dblatex xmlto </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run @@ -333,7 +333,7 @@ Packages needed if you are going to build out the Yocto Project documentation manuals: <literallayout class='monospaced'> - $ sudo zypper install make fop xsltproc dblatex xmlto + $ sudo zypper install make dblatex xmlto </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run @@ -351,25 +351,33 @@ <para> The following list shows the required packages by function given a supported CentOS Linux distribution: - <note> - For CentOS 6.x, some of the versions of the components - provided by the distribution are too old (e.g. Git, Python, - and tar). - It is recommended that you install the buildtools in order - to provide versions that will work with the OpenEmbedded - build system. - For information on how to install the buildtools tarball, - see the - "<link linkend='required-git-tar-and-python-versions'>Required Git, Tar, and Python Versions</link>" - section. - </note> <itemizedlist> <listitem><para><emphasis>Essentials:</emphasis> Packages needed to build an image for a headless system: <literallayout class='monospaced'> - $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; - </literallayout></para></listitem> + $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Extra Packages for Enterprise Linux + (i.e. <filename>epel-release</filename>) + is a collection of packages from Fedora + built on RHEL/CentOS for easy installation + of packages not included in enterprise + Linux by default. + You need to install these packages + separately. + </para></listitem> + <listitem><para> + The <filename>makecache</filename> command + consumes additional Metadata from + <filename>epel-release</filename>. + </para></listitem> + </itemizedlist> + </note> + </para></listitem> <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis> Packages recommended if the host system has graphics support or if you are going to use the Eclipse @@ -382,7 +390,7 @@ Yocto Project documentation manuals: <literallayout class='monospaced'> $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc + docbook-dtds docbook-utils fop libxslt dblatex xmlto </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run diff --git a/import-layers/yocto-poky/documentation/ref-manual/migration.xml b/import-layers/yocto-poky/documentation/ref-manual/migration.xml index 2bdb542ec1..7ca929c140 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/migration.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/migration.xml @@ -3689,7 +3689,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> needed to change signature. Consequently, a new variable named - <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> + <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> has been added allowing multiple versions of BitBake to work with suitably written metadata, which includes OpenEmbedded-Core and Poky. @@ -3955,6 +3955,768 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. </section> </section> +<section id='moving-to-the-yocto-project-2.3-release'> + <title>Moving to the Yocto Project 2.3 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.3 Release from the prior release. + </para> + + <section id='migration-2.3-recipe-specific-sysroots'> + <title>Recipe-specific Sysroots</title> + + <para> + The OpenEmbedded build system now uses one sysroot per + recipe to resolve long-standing issues with configuration + script auto-detection of undeclared dependencies. + Consequently, you might find that some of your previously + written custom recipes are missing declared dependencies, + particularly those dependencies that are incidentally built + earlier in a typical build process and thus are already likely + to be present in the shared sysroot in previous releases. + </para> + + <para> + Consider the following: + <itemizedlist> + <listitem><para> + <emphasis>Declare Build-Time Dependencies:</emphasis> + Because of this new feature, you must explicitly + declare all build-time dependencies for your recipe. + If you do not declare these dependencies, they are not + populated into the sysroot for the recipe. + </para></listitem> + <listitem><para> + <emphasis>Specify Pre-Installation and Post-Installation + Native Tool Dependencies:</emphasis> + You must specifically specify any special native tool + dependencies of <filename>pkg_preinst</filename> and + <filename>pkg_postinst</filename> scripts by using the + <link linkend='var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></link> + variable. + Specifying these dependencies ensures that these tools + are available if these scripts need to be run on the + build host during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task.</para> + + <para>As an example, see the <filename>dbus</filename> + recipe. + You will see that this recipe has a + <filename>pkg_postinst</filename> that calls + <filename>systemctl</filename> if "systemd" is in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + In the example, + <filename>systemd-systemctl-native</filename> is added to + <filename>PACKAGE_WRITE_DEPS</filename>, which is also + conditional on "systemd" being in + <filename>DISTRO_FEATURES</filename>. + </para></listitem> + <listitem><para> + <emphasis>Examine Recipes that Use + <filename>SSTATEPOSTINSTFUNCS</filename>:</emphasis> + You need to examine any recipe that uses + <filename>SSTATEPOSTINSTFUNCS</filename> and determine + steps to take.</para> + + <para>Functions added to + <filename>SSTATEPOSTINSTFUNCS</filename> are still + called as they were in previous Yocto Project releases. + However, since a separate sysroot is now being populated + for every recipe and if existing functions being called + through <filename>SSTATEPOSTINSTFUNCS</filename> are + doing relocation, then you will need to change these + to use a post-installation script that is installed by a + function added to + <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>. + </para> + + <para>For an example, see the + <filename>pixbufcache</filename> class in + <filename>meta/classes/</filename> in the Yocto Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>. + <note> + The <filename>SSTATEPOSTINSTFUNCS</filename> variable + itself is now deprecated in favor of the + <filename>do_populate_sysroot[postfuncs]</filename> + task. + Consequently, if you do still have any function or + functions that need to be called after the sysroot + component is created for a recipe, then you would be + well advised to take steps to use a post installation + script as described previously. + Taking these steps prepares your code for when + <filename>SSTATEPOSTINSTFUNCS</filename> is + removed in a future Yocto Project release. + </note> + </para></listitem> + <listitem><para> + <emphasis>Specify the Sysroot when Using Certain + External Scripts:</emphasis> + Because the shared sysroot is now gone, the scripts + <filename>oe-find-native-sysroot</filename> and + <filename>oe-run-native</filename> have been changed such + that you need to specify which recipe's + <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link> + is used. + </para></listitem> + </itemizedlist> + <note> + You can find more information on how recipe-specific sysroots + work in the + "<link linkend='ref-classes-staging'><filename>staging.bbclass</filename></link>" + section. + </note> + </para> + </section> + + <section id='migration-2.3-path-variable'> + <title><filename>PATH</filename> Variable</title> + + <para> + Within the environment used to run build tasks, the environment + variable <filename>PATH</filename> is now sanitized such that + the normal native binary paths + (<filename>/bin</filename>, <filename>/sbin</filename>, + <filename>/usr/bin</filename> and so forth) are + removed and a directory containing symbolic links linking only + to the binaries from the host mentioned in the + <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link> + and + <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link> + variables is added to <filename>PATH</filename>. + </para> + + <para> + Consequently, any native binaries provided by the host that you + need to call needs to be in one of these two variables at + the configuration level. + </para> + + <para> + Alternatively, you can add a native recipe (i.e. + <filename>-native</filename>) that provides the + binary to the recipe's + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + value. + <note> + <filename>PATH</filename> is not sanitized in the same way + within <filename>devshell</filename>. + If it were, you would have difficulty running host tools for + development and debugging within the shell. + </note> + </para> + </section> + + <section id='migration-2.3-scripts'> + <title>Changes to Scripts</title> + + <para> + The following changes to scripts took place: + <itemizedlist> + <listitem><para> + <emphasis><filename>oe-find-native-sysroot</filename>:</emphasis> + The usage for the + <filename>oe-find-native-sysroot</filename> script has + changed to the following: + <literallayout class='monospaced'> + $ . oe-find-native-sysroot <replaceable>recipe</replaceable> + </literallayout> + You must now supply a recipe for + <replaceable>recipe</replaceable> as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the script with the command. + </para></listitem> + <listitem><para> + <emphasis><filename>oe-run-native</filename>:</emphasis> + The usage for the + <filename>oe-run-native</filename> script has changed + to the following: + <literallayout class='monospaced'> + $ oe-run-native <replaceable>native_recipe</replaceable> <replaceable>tool</replaceable> + </literallayout> + You must supply the name of the native recipe and the tool + you want to run as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the native recipe with the command. + </para></listitem> + <listitem><para> + <emphasis><filename>cleanup-workdir</filename>:</emphasis> + The <filename>cleanup-workdir</filename> script has been + removed because the script was found to be deleting + files it should not have, which lead to broken build + trees. + Rather than trying to delete portions of + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + and getting it wrong, it is recommended that you + delete <filename>TMPDIR</filename> and have it restored + from shared state (sstate) on subsequent builds. + </para></listitem> + <listitem><para> + <emphasis><filename>wipe-sysroot</filename>:</emphasis> + The <filename>wipe-sysroot</filename> script has been + removed as it is no longer needed with recipe-specific + sysroots. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-functions'> + <title>Changes to Functions</title> + + <para> + The previously deprecated + <filename>bb.data.getVar()</filename>, + <filename>bb.data.setVar()</filename>, and + related functions have been removed in favor of + <filename>d.getVar()</filename>, + <filename>d.setVar()</filename>, and so forth. + </para> + + <para> + You need to fix any references to these old functions. + </para> + </section> + + <section id='migration-2.3-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes took place for BitBake: + <itemizedlist> + <listitem><para> + <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis> + BitBake's graphical dependency explorer UI + <filename>depexp</filename> was replaced by + <filename>taskexp</filename> ("Task Explorer"), which + provides a graphical way of exploring the + <filename>task-depends.dot</filename> file. + The data presented by Task Explorer is much more + accurate than the data that was presented by + <filename>depexp</filename>. + Being able to visualize the data is an often requested + feature as standard <filename>*.dot</filename> file + viewers cannot usual cope with the size of + the <filename>task-depends.dot</filename> file. + </para></listitem> + <listitem><para> + <emphasis>BitBake "-g" Output Changes:</emphasis> + The <filename>package-depends.dot</filename> and + <filename>pn-depends.dot</filename> files as previously + generated using the <filename>bitbake -g</filename> command + have been removed. + A <filename>recipe-depends.dot</filename> file + is now generated as a collapsed version of + <filename>task-depends.dot</filename> instead. + </para> + + <para>The reason for this change is because + <filename>package-depends.dot</filename> and + <filename>pn-depends.dot</filename> largely date back + to a time before task-based execution and do not take + into account task-level dependencies between recipes, + which could be misleading. + </para></listitem> + <listitem><para> + <emphasis>Mirror Variable Splitting Changes:</emphasis> + Mirror variables including + <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>, + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>, + and + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + can now separate values entirely with spaces. + Consequently, you no longer need "\\n". + BitBake looks for pairs of values, which simplifies usage. + There should be no change required to existing mirror + variable values themselves. + </para></listitem> + <listitem><para> + <emphasis>The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter:</emphasis> + The SVN fetcher now takes an "ssh" parameter instead of an + "rsh" parameter. + This new optional parameter is used when the "protocol" + parameter is set to "svn+ssh". + You can only use the new parameter to specify the + <filename>ssh</filename> program used by SVN. + The SVN fetcher passes the new parameter through the + <filename>SVN_SSH</filename> environment variable during + the + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task.</para> + + <para>See the + "<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>" + section in the Yocto Project BitBake User Manual for + additional information. + </para></listitem> + <listitem><para> + <emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename> + and <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + Removed:</emphasis> + Because the mechanism they were part of is no longer + necessary with recipe-specific sysroots, the + <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> and + <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + variables have been removed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-absolute-symlinks'> + <title>Absolute Symbolic Links</title> + + <para> + Absolute symbolic links (symlinks) within staged files are no + longer permitted and now trigger an error. + Any explicit creation of symlinks can use the + <filename>lnr</filename> script, which is a replacement for + <filename>ln -r</filename>. + </para> + + <para> + If the build scripts in the software that the recipe is building + are creating a number of absolute symlinks that need to be + corrected, you can inherit + <filename>relative_symlinks</filename> within the recipe to turn + those absolute symlinks into relative symlinks. + </para> + </section> + + <section id='migration-2.3-gplv2-and-gplv3-moves'> + <title>GPLv2 Versions of GPLv3 Recipes Moved</title> + + <para> + Older GPLv2 versions of GPLv3 recipes have moved to a + separate <filename>meta-gplv2</filename> layer. + </para> + + <para> + If you use + <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link> + to exclude GPLv3 or set + <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link> + to substitute a GPLv2 version of a GPLv3 recipe, then you must add + the <filename>meta-gplv2</filename> layer to your configuration. + <note> + You can find <filename>meta-gplv2</filename> layer in the + OpenEmbedded layer index at + <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>. + </note> + </para> + + <para> + These relocated GPLv2 recipes do not receive the same level of + maintenance as other core recipes. + The recipes do not get security fixes and upstream no longer + maintains them. + In fact, the upstream community is actively hostile towards people + that use the old versions of the recipes. + Moving these recipes into a separate layer both makes the different + needs of the recipes clearer and clearly identifies the number of + these recipes. + <note> + The long-term solution might be to move to BSD-licensed + replacements of the GPLv3 components for those that need to + exclude GPLv3-licensed components from the target system. + This solution will be investigated for future Yocto + Project releases. + </note> + </para> + </section> + + <section id='migration-2.3-package-management-changes'> + <title>Package Management Changes</title> + + <para> + The following package management changes took place: + <itemizedlist> + <listitem><para> + Smart package manager is replaced by DNF package manager. + Smart has become unmaintained upstream, is not ported + to Python 3.x. + Consequently, Smart needed to be replaced. + DNF is the only feasible candidate.</para> + <para>The change in functionality is that the on-target + runtime package management from remote package feeds is + now done with a different tool that has a + different set of command-line options. + If you have scripts that call the + tool directly, or use its API, they need to be fixed.</para> + <para>For more information, see the + <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF Documentation</ulink>. + </para></listitem> + <listitem><para> + Rpm 5.x is replaced with Rpm 4.x. + This is done for two major reasons: + <itemizedlist> + <listitem><para> + DNF is API-incompatible with Rpm 5.x and porting + it and maintaining the port is non-trivial. + </para></listitem> + <listitem><para> + Rpm 5.x itself has limited maintenance upstream, + and the Yocto Project is one of the very few + remaining users. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Berkeley DB 6.x is removed and Berkeley DB 5.x becomes + the default: + <itemizedlist> + <listitem><para> + Version 6.x of Berkeley DB has largely been + rejected by the open source community due to its + AGPLv3 license. + As a result, most mainstream open source projects + that require DB are still developed and tested with + DB 5.x. + </para></listitem> + <listitem><para> + In OE-core, the only thing that was requiring + DB 6.x was Rpm 5.x. + Thus, no reason exists to continue carrying DB 6.x + in OE-core. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <filename>createrepo</filename> is replaced with + <filename>createrepo_c</filename>.</para> + <para><filename>createrepo_c</filename> is the current + incarnation of the tool that generates remote repository + metadata. + It is written in C as compared to + <filename>createrepo</filename>, which is written in + Python. + <filename>createrepo_c</filename> is faster and is + maintained. + </para></listitem> + <listitem><para> + Architecture-independent RPM packages are "noarch" + instead of "all".</para> + <para>This change was made because too many places in + DNF/RPM4 stack already make that assumption. + Only the filenames and the architecture tag has changed. + Nothing else has changed in OE-core system, particularly + in the + <link linkend='ref-classes-allarch'><filename>allarch.bbclass</filename></link> + class. + </para></listitem> + <listitem><para> + Signing of remote package feeds using + <filename>PACKAGE_FEED_SIGN</filename> + is not currently supported. + This issue will be fully addressed in a future + Yocto Project release. + See <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>defect 11209</ulink> + for more information on a solution to package feed + signing with RPM in the Yocto Project 2.3 release. + </para></listitem> + <listitem><para> + OPKG now uses the libsolv backend for resolving package + dependencies by default. + This is vastly superior to OPKG's internal ad-hoc solver + that was previously used. + This change does have a small impact on disk (around + 500 KB) and memory footprint. + <note> + For further details on this change, see the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/? +id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. + </note> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <emphasis><filename>linux-yocto 4.8:</filename></emphasis> + Version 4.8 has been removed. + Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 + are now present. + </para></listitem> + <listitem><para> + <emphasis><filename>python-smartpm:</filename></emphasis> + Functionally replaced by <filename>dnf</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>createrepo:</filename></emphasis> + Replaced by the <filename>createrepo-c</filename> recipe. + </para></listitem> + <listitem><para> + <emphasis><filename>rpmresolve:</filename></emphasis> + No longer needed with the move to RPM 4 as RPM itself is + used instead. + </para></listitem> + <listitem><para> + <emphasis><filename>gstreamer:</filename></emphasis> + Removed the GStreamer Git version recipes as they have + been stale. + <filename>1.10.</filename><replaceable>x</replaceable> + recipes are still present. + </para></listitem> + <listitem><para> + <emphasis><filename>alsa-conf-base:</filename></emphasis> + Merged into <filename>alsa-conf</filename> since + <filename>libasound</filename> depended on both. + Essentially, no way existed to install only one of these. + </para></listitem> + <listitem><para> + <emphasis><filename>tremor:</filename></emphasis> + Moved to <filename>meta-multimedia</filename>. + Fixed-integer Vorbis decoding is not + needed by current hardware. + Thus, GStreamer's ivorbis plugin has been disabled + by default eliminating the need for the + <filename>tremor</filename> recipe in OE-Core. + </para></listitem> + <listitem><para> + <emphasis><filename>gummiboot:</filename></emphasis> + Replaced by <filename>systemd-boot</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-wic-changes'> + <title>Wic Changes</title> + + <para> + The following changes have been made to Wic: + <note> + For more information on Wic, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images'>Creating Partitioned Images</ulink>" + section in the Yocto Project Development Manual. + </note> + <itemizedlist> + <listitem><para> + <emphasis>Default Output Directory Changed:</emphasis> + Wic's default output directory is now the current directory + by default instead of the unusual + <filename>/var/tmp/wic</filename>.</para> + + <para>The "-o" and "--outdir" options remain unchanged + and are used to specify your preferred output directory + if you do not want to use the default directory. + </para></listitem> + <listitem><para> + <emphasis>fsimage Plug-in Removed:</emphasis> + The Wic fsimage plug-in has been removed as it duplicates + functionality of the rawcopy plug-in. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-qa-changes'> + <title>QA Changes</title> + + <para> + The following QA checks have changed: + <itemizedlist> + <listitem><para> + <emphasis><filename>unsafe-references-in-binaries</filename>:</emphasis> + The <filename>unsafe-references-in-binaries</filename> + QA check, which was disabled by default, has now been + removed. + This check was intended to detect binaries in + <filename>/bin</filename> that link to libraries in + <filename>/usr/lib</filename> and have the case where + the user has <filename>/usr</filename> on a separate + filesystem to <filename>/</filename>.</para> + + <para>The removed QA check was buggy. + Additionally, <filename>/usr</filename> residing on a + separate partition from <filename>/</filename> is now + a rare configuration. + Consequently, + <filename>unsafe-references-in-binaries</filename> was + removed. + </para></listitem> + <listitem><para> + <emphasis><filename>file-rdeps</filename>:</emphasis> + The <filename>file-rdeps</filename> QA check is now an + error by default instead of a warning. + Because it is an error instead of a warning, you need to + address missing runtime dependencies.</para> + + <para>For additional information, see the + <link linkend='ref-classes-insane'><filename>insane</filename></link> + class and the + "<link linkend='qa-errors-and-warnings'>Errors and Warnings</link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + In this release, a number of recipes have been changed to + ignore the <filename>largefile</filename> + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + item, enabling large file support unconditionally. + This feature has always been enabled by default. + Disabling the feature has not been widely tested. + <note> + Future releases of the Yocto Project will remove + entirely the ability to disable the + <filename>largefile</filename> feature, + which would make it unconditionally enabled everywhere. + </note> + </para></listitem> + <listitem><para> + If the + <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link> + value contains the value of the + <link linkend='var-DATE'><filename>DATE</filename></link> + variable, which is the default between Poky releases, + the <filename>DATE</filename> value is explicitly excluded + from <filename>/etc/issue</filename> and + <filename>/etc/issue.net</filename>, which is displayed at + the login prompt, in order to avoid conflicts with + Multilib enabled. + Regardless, the <filename>DATE</filename> value is + inaccurate if the <filename>base-files</filename> + recipe is restored from shared state (sstate) rather + than rebuilt.</para> + + <para>If you need the build date recorded in + <filename>/etc/issue*</filename> or anywhere else in your + image, a better method is to define a post-processing + function to do it and have the function called from + <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>. + Doing so ensures the value is always up-to-date with the + created image. + </para></listitem> + <listitem><para> + Dropbear's <filename>init</filename> script now disables + DSA host keys by default. + This change is in line with the systemd service + file, which supports RSA keys only, and with recent + versions of OpenSSH, which deprecates DSA host keys. + </para></listitem> + <listitem><para> + The + <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> + class now correctly uses tabs as separators between all + columns in <filename>installed-package-sizes.txt</filename> + in order to aid import into other tools. + </para></listitem> + <listitem><para> + The <filename>USE_LDCONFIG</filename> variable has been + replaced with the "ldconfig" + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + feature. + Distributions that previously set: + <literallayout class='monospaced'> + USE_LDCONFIG = "0" + </literallayout> + should now instead use the following: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" + </literallayout> + </para></listitem> + <listitem><para> + The default value of + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + now includes all versions of AGPL licenses in addition + to GPL and LGPL. + <note> + The default list is not intended to be guaranteed + as a complete safe list. + You should seek legal advice based on what you are + distributing if you are unsure. + </note> + </para></listitem> + <listitem><para> + Kernel module packages are now suffixed with the kernel + version in order to allow module packages from multiple + kernel versions to co-exist on a target system. + If you wish to return to the previous naming scheme + that does not include the version suffix, use the + following: + <literallayout class='monospaced'> + KERNEL_MODULE_PACKAGE_SUFFIX to "" + </literallayout> + </para></listitem> + <listitem><para> + Removal of <filename>libtool</filename> + <filename>*.la</filename> files is now enabled by default. + The <filename>*.la</filename> files are not actually + needed on Linux and relocating them is an unnecessary + burden.</para> + + <para>If you need to preserve these + <filename>.la</filename> files (e.g. in a custom + distribution), you must change + <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link> + such that "remove-libtool" is not included in the value. + </para></listitem> + <listitem><para> + Extensible SDKs built for GCC 5+ now refuse to install on a + distribution where the host GCC version is 4.8 or 4.9. + This change resulted from the fact that the installation + is known to fail due to the way the + <filename>uninative</filename> shared state (sstate) + package is built. + See the + <link linkend='ref-classes-uninative'><filename>uninative</filename></link> + class for additional information. + </para></listitem> + <listitem><para> + All native and nativesdk recipes now use a separate + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value instead of sharing the value used by recipes for the + target, in order to avoid unnecessary rebuilds.</para> + + <para>The <filename>DISTRO_FEATURES</filename> for + <filename>native</filename> recipes is + <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link> + added to an intersection of + <filename>DISTRO_FEATURES</filename> and + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>. + </para> + + <para>For nativesdk recipes, the + corresponding variables are + <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link> + and + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>. + </para></listitem> + <listitem><para> + The <filename>FILESDIR</filename> + variable, which was previously deprecated and rarely used, + has now been removed. + You should change any recipes that set + <filename>FILESDIR</filename> to set + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> + instead. + </para></listitem> + <listitem><para> + The <filename>MULTIMACH_HOST_SYS</filename> + variable has been removed as it is no longer needed + with recipe-specific sysroots. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml index 1de1148264..2f36e16eaf 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml @@ -414,7 +414,7 @@ Options: -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug logging for the specified logging domains -P, --profile Profile the command and save reports. - -u UI, --ui=UI The user interface to use (e.g. knotty and depexp). + -u UI, --ui=UI The user interface to use (e.g. knotty and taskexp). -t SERVERTYPE, --servertype=SERVERTYPE Choose which server to use, process or xmlrpc. --revisions-changed Set the exit code depending on whether upstream diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml index f7b1126d7c..c88162b3ba 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -1301,19 +1301,27 @@ <title><filename>image-live.bbclass</filename></title> <para> - The <filename>image-live</filename> class supports building "live" - images. + This class controls building "live" (i.e. HDDIMG and ISO) images. + Live images contain syslinux for legacy booting, as well as the + bootloader specified by + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + if + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> + contains "efi". </para> <para> Normally, you do not use this class directly. Instead, you add "live" to <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. + You can selectively build just one of these types through the + <link linkend='var-NOISO'><filename>NOISO</filename></link> + and + <link linkend='var-NOHDD'><filename>NOHDD</filename></link> variables. For example, if you were building an ISO image, you would add "live" to <filename>IMAGE_FSTYPES</filename>, set the - <link linkend='var-NOISO'><filename>NOISO</filename></link> variable to - "0" and the build system would use the <filename>image-live</filename> - class to build the ISO image. + <filename>NOISO</filename> variable to "0" and the build system would + use the <filename>image-live</filename> class to build the ISO image. </para> </section> @@ -1755,6 +1763,9 @@ <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link> message for more information regarding runtime performance issues. </para></listitem> +<!-- +This check was removed for YP 2.3 release + <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis> Reports when a binary installed in <filename>${base_libdir}</filename>, @@ -1776,6 +1787,7 @@ <filename>/usr</filename>. </note> </para></listitem> +--> <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis> Reports when a script file installed in <filename>${base_libdir}</filename>, @@ -2216,6 +2228,14 @@ functionality specific to the respective native or target case.</para></listitem> </itemizedlist> + <note><title>Warning</title> + When creating a recipe, you must follow this naming convention: + <literallayout class='monospaced'> + native-<replaceable>myrecipe</replaceable>.bb + </literallayout> + Not doing so can lead to subtle problems because code exists + that depends on the naming convention. + </note> </para> <para> @@ -2258,6 +2278,14 @@ functionality specific to the respective SDK machine or target case.</para></listitem> </itemizedlist> + <note><title>Warning</title> + When creating a recipe, you must follow this naming convention: + <literallayout class='monospaced'> + nativesdk-<replaceable>myrecipe</replaceable>.bb + </literallayout> + Not doing so can lead to subtle problems because code exists + that depends on the naming convention. + </note> </para> <para> @@ -2374,7 +2402,7 @@ <para> If you take the optional step to set up a repository (package feed) - on the development host that can be used by Smart, you can + on the development host that can be used by DNF, you can install packages from the feed while you are running the image on the target (i.e. runtime installation of packages). For more information, see the @@ -3190,13 +3218,144 @@ <title><filename>staging.bbclass</filename></title> <para> - The <filename>staging</filename> class provides the - <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> - task, which stages files into the sysroot to make them available to - other recipes at build time. - The class is enabled by default because it is inherited by the - <link linkend='ref-classes-base'><filename>base</filename></link> - class. + The <filename>staging</filename> class installs files into individual + recipe work directories for sysroots. + The class contains the following key tasks: + <itemizedlist> + <listitem><para> + The + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task, which is responsible for handing the files that end up + in the recipe sysroots. + </para></listitem> + <listitem><para> + The + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + task (a "partner" task to the + <filename>populate_sysroot</filename> task), which installs + the files into the individual recipe work directories (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + </para></listitem> + </itemizedlist> + </para> + + <para> + The code in the <filename>staging</filename> class is complex and + basically works in two stages: + <itemizedlist> + <listitem><para> + <emphasis>Stage One:</emphasis> + The first stage addresses recipes that have files they want + to share with other recipes that have dependencies on the + originating recipe. + Normally these dependencies are installed through the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task into + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>. + The <filename>do_populate_sysroot</filename> task copies + a subset of these files into + <filename>${SYSROOT_DESTDIR}</filename>. + This subset of files is controlled by the + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>, + <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>, + and + <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link> + variables. + <note> + Additionally, a recipe can customize the files further by + declaring a processing function in the + <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link> + variable. + </note> + </para> + + <para> + A shared state (sstate) object is built from these files + and the files are placed into a subdirectory of + <link linkend='structure-build-tmp-sysroots-components'><filename>tmp/sysroots-components/</filename></link>. + The files are scanned for hardcoded paths to the original + installation location. + If the location is found in text files, the hardcoded + locations are replaced by tokens and a list of the files + needing such replacements is created. + These adjustments are referred to as "FIXMEs". + The list of files that are scanned for paths is controlled by + the + <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link> + variable. + </para></listitem> + <listitem><para> + <emphasis>Stage Two:</emphasis> + The second stage addresses recipes that want to use something + from another recipe and declare a dependency on that recipe + through the + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + variable. + The recipe will have a + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + task and when + this task executes, it creates the + <filename>recipe-sysroot</filename> and + <filename>recipe-sysroot-native</filename> in the recipe + work directory (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + The OpenEmbedded build system creates hard links to copies of the + relevant files from <filename>sysroots-components</filename> + into the recipe work directory. + <note> + If hard links are not possible, the build system uses + actual copies. + </note> + The build system then addresses any "FIXMEs" to paths as + defined from the list created in the first stage. + </para> + + <para> + Finally, any files in <filename>${bindir}</filename> + within the sysroot that have the prefix + "<filename>postinst-</filename>" are executed. + <note> + Although such sysroot post installation scripts are not + recommended for general use, the files do allow some issues + such as user creation and module indexes to be addressed. + </note> + </para> + + <para> + Because recipes can have other dependencies outside of + <filename>DEPENDS</filename> (e.g. + <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>), + the sysroot creation function + <filename>extend_recipe_sysroot</filename> is also added as + a pre-function for those tasks whose dependencies are not + through <filename>DEPENDS</filename> but operate similarly. + </para> + + <para> + When installing dependencies into the sysroot, the code + traverses the dependency graph and processes dependencies + in exactly the same way as the dependencies would or would not + be when installed from sstate. + This processing means, for example, a native tool would have + its native dependencies added but a target library would not + have its dependencies traversed or installed. + The same sstate dependency code is used so that + builds should be identical regardless of whether sstate + was used or not. + For a closer look, see the + <filename>setscene_depvalid()</filename> function in the + <link linkend='ref-classes-sstate'><filename>sstate</filename></link> + class. + </para> + + <para> + The build system is careful to maintain manifests of the files + it installs so that any given dependency can be installed as + needed. + The sstate hash of the installed item is also stored so that + if it changes, the build system can reinstall it. + </para></listitem> + </itemizedlist> </para> </section> @@ -3532,6 +3691,14 @@ For an example, see the <filename>meta/conf/distro/include/yocto-uninative.inc</filename>. </para> + + <para> + The <filename>uninative</filename> class is also used unconditionally + by the extensible SDK. + When building the extensible SDK, + <filename>uninative-tarball</filename> is built and the resulting + tarball is included within the SDK. + </para> </section> <section id='ref-classes-update-alternatives'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml index 1764f0196f..99d5a52a0f 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml @@ -215,6 +215,17 @@ The <filename>.bbappend</filename> file is created to point to the external source tree. </para> + + <note> + If your recipe has runtime dependencies defined, you must be sure + that these packages exist on the target hardware before attempting + to run your application. + If dependent packages (e.g. libraries) do not exist on the target, + your application, when run, will fail to find those functions. + For more information, see the + "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>" + section. + </note> </section> <section id='devtool-extracting-the-source-for-an-existing-recipe'> @@ -501,6 +512,40 @@ </para> </note> </para> + + <para> + Some conditions exist that could prevent a deployed application + from behaving as expected. + When both of the following conditions exist, your application has + the potential to not behave correctly when run on the target: + <itemizedlist> + <listitem><para> + You are deploying a new application to the target and + the recipe you used to build the application had + correctly defined runtime dependencies. + </para></listitem> + <listitem><para> + The target does not physically have the packages on which + the application depends installed. + </para></listitem> + </itemizedlist> + If both of these conditions exist, your application will not + behave as expected. + The reason for this misbehavior is because the + <filename>devtool deploy-target</filename> command does not deploy + the packages (e.g. libraries) on which your new application + depends. + The assumption is that the packages are already on the target. + Consequently, when a runtime call is made in the application + for a dependent function (e.g. a library call), the function + cannot be found. + </para> + + <para> + To be sure you have all the dependencies local to the target, you + need to be sure that the packages are pre-deployed (installed) + on the target before attempting to run your application. + </para> </section> <section id='devtool-removing-your-software-from-the-target-machine'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml index 282a517191..7e1c5ef2f1 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml @@ -195,6 +195,10 @@ <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be loaded during boot). </para></listitem> + <listitem><para><emphasis>ldconfig:</emphasis> + Include support for ldconfig and + <filename>ld.so.conf</filename> on the target. + </para></listitem> <listitem><para><emphasis>nfs:</emphasis> Include NFS client support (for mounting NFS exports on device). </para></listitem> @@ -297,6 +301,12 @@ Enables logging postinstall script runs to the <filename>/var/log/postinstall.log</filename> file on first boot of the image on the target system. + <note> + To make the <filename>/var/log</filename> directory + on the target persistent, use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></ulink> + variable by setting it to "no". + </note> </para></listitem> <listitem><para><emphasis>ptest-pkgs:</emphasis> Installs ptest packages for all ptest-enabled recipes. diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml index 69b58f6ab4..f2209686f0 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml @@ -54,9 +54,6 @@ <listitem><para><filename>core-image-clutter</filename>: An image with support for the Open GL-based toolkit Clutter, which enables development of rich and animated graphical user interfaces.</para></listitem> - <listitem><para><filename>core-image-directfb</filename>: - An image that uses <filename>directfb</filename> instead of X11. - </para></listitem> <listitem><para><filename>core-image-full-cmdline</filename>: A console-only image with more full-featured Linux system functionality installed.</para></listitem> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml index 47f64769c0..752b210152 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml @@ -108,14 +108,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -129,12 +144,32 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Reference + Manual associated with this Yocto Project release + (version &YOCTO_DOC_VERSION;), + see the Yocto Project Reference Manual from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Reference Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/ref-manual/ref-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> </bookinfo> @@ -147,6 +182,8 @@ <xi:include href="technical-details.xml"/> + <xi:include href="ref-release-process.xml"/> + <xi:include href="migration.xml"/> <xi:include href="ref-structure.xml"/> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml index 86456bd429..515106ae68 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml @@ -1170,45 +1170,6 @@ can be found then it should be implemented. I can't find one at the moment. </listitem> </itemizedlist> </para> - -<!-- -Here are some messages that might be documented in the future. -Right now we are not documenting them because the QA checks are not -enabled by default: - - <para> - <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> - Desktop file issue: <error> [desktop] - </literallayout> - NEED A DESCRIPTION AND SOLUTION - </para></listitem> - </itemizedlist> - </para> - - <para> - <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> - <packagename>: <file>, installed in the base_prefix, requires a shared library under exec_prefix (<exec_prefix&t;g) [unsafe-references-in-binaries] - </literallayout> - NEED A DESCRIPTION AND SOLUTION - </para></listitem> - </itemizedlist> - </para> - - <para> - <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> - <packagename>: Found a reference to <exec_prefix>/ in <path> - Shell scripts in base_bindir and base_sbindir should not reference anything in exec_prefix [unsafe-references-in-scripts] - </literallayout> - NEED A DESCRIPTION AND SOLUTION - </para></listitem> - </itemizedlist> - </para> ---> </section> <section id='configuring-and-disabling-qa-checks'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml new file mode 100644 index 0000000000..fe3ba0933e --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml @@ -0,0 +1,254 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='ref-release-process'> +<title>Yocto Project Releases and the Stable Release Process</title> + +<para> + The Yocto Project release process is predictable and consists of both + major and minor (point) releases. + This brief chapter provides information on how releases are named, their + life cycle, and their stability. +</para> + +<section id='major-and-minor-release-cadence'> + <title>Major and Minor Release Cadence</title> + + <para> + The Yocto Project delivers major releases (e.g. &DISTRO;) using a six + month cadence roughly timed each April and October of the year. + Following are examples of some major YP releases with their codenames + also shown. + See the + "<link linkend='major-release-codenames'>Major Release Codenames</link>" + section for information on codenames used with major releases. + <literallayout class='monospaced'> + 2.2 (Morty) + 2.1 (Krogoth) + 2.0 (Jethro) + </literallayout> + While the cadence is never perfect, this timescale facilitates + regular releases that have strong QA cycles while not overwhelming + users with too many new releases. + The cadence is predictable and avoids many major holidays in various + geographies. + </para> + + <para> + The Yocto project delivers minor (point) releases on an unscheduled + basis and are usually driven by the accumulation of enough significant + fixes or enhancements to the associated major release. + Following are some example past point releases: + <literallayout class='monospaced'> + 2.1.1 + 2.1.2 + 2.2.1 + </literallayout> + The point release indicates a point in the major release branch where + a full QA cycle and release process validates the content of the new + branch. + <note> + Realize that there can be patches merged onto the stable release + branches as and when they become available. + </note> + </para> +</section> + +<section id='major-release-codenames'> + <title>Major Release Codenames</title> + + <para> + Each major release receives a codename that identifies the release in + the + <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>. + The concept is that branches of + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + with the same codename are likely to be compatible and thus + work together. + <note> + Codenames are associated with major releases because a Yocto + Project release number (e.g. &DISTRO;) could conflict with + a given layer or company versioning scheme. + Codenames are unique, interesting, and easily identifiable. + </note> + Releases are given a nominal release version as well but the codename + is used in repositories for this reason. + You can find information on Yocto Project releases and codenames at + <ulink url='https://wiki.yoctoproject.org/wiki/Releases'></ulink>. + </para> +</section> + +<section id='stable-release-process'> + <title>Stable Release Process</title> + + <para> + Once released, the release enters the stable release process at which + time a person is assigned as the maintainer for that stable release. + This maintainer monitors activity for the release by investigating + and handling nominated patches and backport activity. + Only fixes and enhancements that have first been applied on the + "master" branch (i.e. the current, in-development branch) are + considered for backporting to a stable release. + <note> + The current Yocto Project policy regarding backporting is to + consider bug fixes and security fixes only. + Policy dictates that features are not backported to a stable + release. + This policy means generic recipe version upgrades are unlikely to + be accepted for backporting. + The exception to this policy occurs when a strong reason exists + such as the fix happens to also be the preferred upstream approach. + </note> + </para> + + <para> + Stable release branches have strong maintenance for about a year after + their initial release. + Should significant issues be found for any release regardless of its + age, fixes could be backported to older releases. + For issues that are not backported given an older release, + Community LTS trees and branches exist where + community members share patches for older releases. + However, these types of patches do not go through the same release + process as do point releases. + You can find more information about stable branch maintenance at + <ulink url='https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance'></ulink>. + </para> +</section> + +<section id='testing-and-quality-assurance'> + <title>Testing and Quality Assurance</title> + + <para> + Part of the Yocto Project development and release process is quality + assurance through the execution of test strategies. + Test strategies provide the Yocto Project team a way to ensure a + release is validated. + Additionally, because the test strategies are visible to you as a + developer, you can validate your projects. + This section overviews the available test infrastructure used in the + Yocto Project. + For information on how to run available tests on your projects, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" + section in the Yocto Project Development Manual. + </para> + + <para> + The QA/testing infrastructure is woven into the project to the point + where core developers take some of it for granted. + The infrastructure consists of the following pieces: + <itemizedlist> + <listitem><para> + <filename>bitbake-selftest</filename>: + A standalone command that runs unit tests on key pieces of + BitBake and its fetchers. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-sanity'><filename>sanity.bbclass</filename></link>: + This automatically included class checks the build environment + for missing tools (e.g. <filename>gcc</filename>) or common + misconfigurations such as + <link linkend='var-MACHINE'><filename>MACHINE</filename></link> + set incorrectly. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>: + This class checks the generated output from builds for sanity. + For example, if building for an ARM target, did the build + produce ARM binaries. + If, for example, the build produced PPC binaries then there + is a problem. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>: + This class performs runtime testing of images after they are + built. + The tests are usually used with + <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU</ulink> + to boot the images and check the combined runtime result + boot operation and functions. + However, the test can also use the IP address of a machine to + test. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'><filename>ptest</filename></ulink>: + Runs tests against packages produced during the build for a + given piece of software. + The test allows the packages to be be run within a target + image. + </para></listitem> + <listitem><para> + <filename>oe-selftest</filename>: + Tests combination BitBake invocations. + These tests operate outside the OpenEmbedded build system + itself. + The <filename>oe-selftest</filename> can run all tests by + default or can run selected tests or test suites. + <note> + Running <filename>oe-selftest</filename> requires + host packages beyond the "Essential" grouping. + See the + "<link linkend='required-packages-for-the-host-development-system'>Required Packages for the Host Development System</link>" + section for more information. + </note> + </para></listitem> + </itemizedlist> + </para> + + <para> + Originally, much of this testing was done manually. + However, significant effort has been made to automate the tests so + that more people can use them and the Yocto Project development team + can run them faster and more efficiently. + </para> + + <para> + The Yocto Project's main Autobuilder + (<filename>autobuilder.yoctoproject.org</filename>) publicly tests + each Yocto Project release's code in the OE-Core, Poky, and BitBake + repositories. + The testing occurs for both the current state of the + "master" branch and also for submitted patches. + Testing for submitted patches usually occurs in the + "ross/mut" branch in the <filename>poky-contrib</filename> repository + (i.e. the master-under-test branch) or in the "master-next" branch + in the <filename>poky</filename> repository. + <note> + You can find all these branches in the Yocto Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>. + </note> + Testing within these public branches ensures in a publicly visible way + that all of the main supposed architectures and recipes in OE-Core + successfully build and behave properly. + </para> + + <para> + Various features such as <filename>multilib</filename>, sub + architectures (e.g. <filename>x32</filename>, + <filename>poky-tiny</filename>, <filename>musl</filename>, + <filename>no-x11</filename> and and so forth), + <filename>bitbake-selftest</filename>, and + <filename>oe-selftest</filename> are tested as part of + the QA process of a release. + Complete testing and validation for a release takes the Autobuilder + workers several hours. + <note> + The Autobuilder workers are non-homogeneous, which means regular + testing across a variety of Linux distributions occurs. + The Autobuilder is limited to only testing QEMU-based setups and + not real hardware. + </note> + </para> + + <para> + Finally, in addition to the Autobuilder's tests, the Yocto Project + QA team also performs testing on a variety of platforms, which includes + actual hardware, to ensure expected results. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml index 541a47e556..9b2701cc31 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml @@ -797,15 +797,47 @@ </para> </section> + <section id='structure-build-tmp-sysroots-components'> + <title><filename>build/tmp/sysroots-components/</filename></title> + + <para> + This directory is the location of the sysroot contents that the + task + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + links or copies into the recipe-specific sysroot for each + recipe listed in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. + Population of this directory is handled through shared state, while + the path is specified by the <filename>COMPONENTS_DIR</filename> + variable. Apart from a few unusual circumstances, handling of the + <filename>sysroots-components</filename> directory should be + automatic, and recipes should not directly reference + <filename>build/tmp/sysroots-components</filename>. + </para> + </section> + <section id='structure-build-tmp-sysroots'> <title><filename>build/tmp/sysroots/</filename></title> <para> - This directory contains shared header files and libraries as well as other shared - data. - Packages that need to share output with other packages do so within this directory. - The directory is subdivided by architecture so multiple builds can run within - the one Build Directory. + Previous versions of the OpenEmbedded build system used to + create a global shared sysroot per machine along with a native + sysroot. + Beginning with the &DISTRO; version of the Yocto Project, + sysroots exist in recipe-specific + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + directories. + Thus, the <filename>build/tmp/sysroots/</filename> directory + is unused. + <note> + The <filename>build/tmp/sysroots/</filename> directory + can still be populated using the + <filename>bitbake build-sysroots</filename> command and can + be used for compatibility in some cases. + However, in general it is not recommended to populate + this directory. + Individual recipe-specific sysroots should be used. + </note> </para> </section> @@ -894,6 +926,101 @@ </para> </section> + <section id='structure-build-tmp-work-tunearch-recipename-version'> + <title><filename>build/tmp/work/<replaceable>tunearch</replaceable>/<replaceable>recipename</replaceable>/<replaceable>version</replaceable>/</filename></title> + + <para> + The recipe work directory - <filename>${WORKDIR}</filename>. + </para> + + <para> + As described earlier in the + "<link linkend='structure-build-tmp-sysroots'><filename>build/tmp/sysroots/</filename></link>" + section, beginning with the &DISTRO; release of the Yocto + Project, the OpenEmbedded build system builds each recipe in its + own work directory (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + The path to the work directory is constructed using the + architecture of the given build (e.g. + <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>, + <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>, + or "allarch"), the recipe name, and the version of the recipe (i.e. + <link linkend='var-PE'><filename>PE</filename></link><filename>:</filename><link linkend='var-PV'><filename>PV</filename></link><filename>-</filename><link linkend='var-PR'><filename>PR</filename></link>). + </para> + + <para> + A number of key subdirectories exist within each recipe + work directory: + <itemizedlist> + <listitem><para> + <filename>${WORKDIR}/temp</filename>: + Contains the log files of each task executed for this + recipe, the "run" files for each executed task, which + contain the code run, and a + <filename>log.task_order</filename> file, which lists the + order in which tasks were executed. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/image</filename>: + Contains the output of the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task, which corresponds to the + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> + variable in that task. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/pseudo</filename>: + Contains the pseudo database and log for any tasks executed + under pseudo for the recipe. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/sysroot-destdir</filename>: + Contains the output of the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/package</filename>: + Contains the output of the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task before the output is split into individual packages. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/packages-split</filename>: + Contains the output of the <filename>do_package</filename> + task after the output has been split into individual + packages. + Subdirectories exist for each individual package created + by the recipe. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/recipe-sysroot</filename>: + A directory populated with the target dependencies of the + recipe. + This directory looks like the target filesystem and + contains libraries that the recipe might need to link + against (e.g. the C library). + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/recipe-sysroot-native</filename>: + A directory populated with the native dependencies of the + recipe. + This directory contains the tools the recipe needs to build + (e.g. the compiler, Autoconf, libtool, and so forth). + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/build</filename>: + This subdirectory applies only to recipes that support + builds where the source is separate from the + build artifacts. + The OpenEmbedded build system uses this directory as a + separate build directory (i.e. + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>). + </para></listitem> + </itemizedlist> + </para> + </section> + <section id='structure-build-work-shared'> <title><filename>build/tmp/work-shared/</filename></title> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml index e9859c1fa9..87ddb98278 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml @@ -490,6 +490,21 @@ </para> </section> + <section id='ref-tasks-prepare_recipe_sysroot'> + <title><filename>do_prepare_recipe_sysroot</filename></title> + + <para> + Installs the files into the individual recipe specific sysroots + (i.e. + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename> + based upon the dependencies specified by + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. + See the + "<link linkend='ref-classes-staging'><filename>staging</filename></link>" + class for more information. + </para> + </section> + <section id='ref-tasks-rm_work'> <title><filename>do_rm_work</filename></title> @@ -853,7 +868,10 @@ <title><filename>do_compile_kernelmodules</filename></title> <para> - Compiles loadable modules for the Linux kernel. + Runs the step that builds the kernel modules (if needed). + Building a kernel consists of two steps: 1) the kernel + (<filename>vmlinux</filename>) is built, and 2) the modules + are built (i.e. <filename>make modules</filename>). </para> </section> @@ -861,9 +879,21 @@ <title><filename>do_diffconfig</filename></title> <para> - Compares the old and new config files after running the - <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link> - task for the kernel. + When invoked by the user, this task creates a file containing the + differences between the original config as produced by + <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link> + task and the changes made by the user with other methods + (i.e. using + (<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>). + Once the file of differences is created, it can be used to create + a config fragment that only contains the differences. + You can invoke this task from the command line as follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c diffconfig + </literallayout> + For more information, see the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" + section in the Yocto Project Linux Kernel Development Manual. </para> </section> @@ -871,7 +901,12 @@ <title><filename>do_kernel_checkout</filename></title> <para> - Checks out source/meta branches for a linux-yocto style kernel. + Converts the newly unpacked kernel source into a form with which + the OpenEmbedded build system can work. + Because the kernel source can be fetched in several different ways, + the <filename>do_kernel_checkout</filename> task makes sure that + subsequent tasks are given a clean working tree copy of the kernel + with the correct branches checked out. </para> </section> @@ -879,7 +914,21 @@ <title><filename>do_kernel_configcheck</filename></title> <para> - Validates the kernel configuration for a linux-yocto style kernel. + Validates the configuration produced by the + <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link> + task. + The <filename>do_kernel_configcheck</filename> task produces + warnings when a requested configuration does not appear in the + final <filename>.config</filename> file or when you override a + policy configuration in a hardware configuration fragment. + You can run this task explicitly and view the output by using + the following command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + For more information, see the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" + section in the Yocto Project Linux Kernel Development Manual. </para> </section> @@ -887,17 +936,41 @@ <title><filename>do_kernel_configme</filename></title> <para> - Assembles the kernel configuration for a linux-yocto style kernel. + After the kernel is patched by the + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task, the <filename>do_kernel_configme</filename> task assembles + and merges all the kernel config fragments into a merged + configuration that can then be passed to the kernel configuration + phase proper. + This is also the time during which user-specified defconfigs + are applied if present, and where configuration modes such as + <filename>--allnoconfig</filename> are applied. </para> </section> - <section id='ref-tasks-kernel_link_vmlinux'> - <title><filename>do_kernel_link_vmlinux</filename></title> + <section id='ref-tasks-kernel_menuconfig'> + <title><filename>do_kernel_menuconfig</filename></title> <para> - Creates a symbolic link in - <filename>arch/$arch/boot</filename> for vmlinux kernel - images. + Invoked by the user to manipulate the + <filename>.config</filename> file used to build a linux-yocto + recipe. + This task starts the Linux kernel configuration tool, which you + then use to modify the kernel configuration. + <note> + You can also invoke this tool from the command line as + follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c menuconfig + </literallayout> + </note> + See the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" + section in the Yocto Project Linux Kernel Development Manual + for more information on this configuration tool. + You can also reference the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>" + section in the Yocto Project Development Manual. </para> </section> @@ -905,8 +978,16 @@ <title><filename>do_kernel_metadata</filename></title> <para> - Collects kernel metadata for a - <filename>linux-yocto</filename> style kernel. + Collects all the features required for a given kernel build, + whether the features come from + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + or from Git repositories. + After collection, the <filename>do_kernel_metadata</filename> task + processes the features into a series of config fragments and + patches, which can then be applied by subsequent tasks such as + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + and + <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>. </para> </section> @@ -925,7 +1006,17 @@ <title><filename>do_savedefconfig</filename></title> <para> - Creates a minimal Linux kernel configuration file. + When invoked by the user, creates a defconfig file that can be + used instead of the default defconfig. + The saved defconfig contains the differences between the default + defconfig and the changes made by the user using other methods + (i.e. the + <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link> + task. + You can invoke the task using the following command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c savedefconfig + </literallayout> </para> </section> @@ -933,7 +1024,14 @@ <title><filename>do_shared_workdir</filename></title> <para> - Creates the shared working directory for the kernel. + After the kernel has been compiled but before the kernel modules + have been compiled, this task copies files required for module + builds and which are generated from the kernel build into the + shared work directory. + With these copies successfully copied, the + <link linkend='ref-tasks-compile_kernelmodules'><filename>do_compile_kernelmodules</filename></link> + task can successfully build the kernel modules in the next step + of the build. </para> </section> @@ -941,9 +1039,12 @@ <title><filename>do_sizecheck</filename></title> <para> - Checks the size of the kernel image against - <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link> - when set. + After the kernel has been built, this task checks the size of the + stripped kernel image against + <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link>. + If that variable was set and the size of the stripped kernel + exceeds that size, the kernel build produces a warning to that + effect. </para> </section> @@ -951,15 +1052,13 @@ <title><filename>do_strip</filename></title> <para> - Strips unneeded sections out of the Linux kernel image. - </para> - </section> - - <section id='ref-tasks-uboot_mkimage'> - <title><filename>do_uboot_mkimage</filename></title> - - <para> - Creates a uImage file from the kernel for the U-Boot bootloader. + If + <filename>KERNEL_IMAGE_STRIP_EXTRA_SECTIONS</filename> is defined, + this task strips the sections named in that variable from + <filename>vmlinux</filename>. + This stripping is typically used to remove nonessential sections + such as <filename>.comment</filename> sections from a + size-sensitive configuration. </para> </section> @@ -967,10 +1066,14 @@ <title><filename>do_validate_branches</filename></title> <para> - Ensures that the source, metadata (or both) branches are on the - locations specified by their - <link linkend='var-SRCREV'><filename>SRCREV</filename></link> - values for a linux-yocto style kernel. + After the kernel is unpacked but before it is patched, this task + makes sure that the machine and metadata branches as specified + by the <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + variables actually exist on the specified branches. + If these branches do not exist and + <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> + is not being used, the <filename>do_validate_branches</filename> + task fails during the build. </para> </section> </section> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml index 807e24251f..ad10139727 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml @@ -37,7 +37,7 @@ <link linkend='var-S'>S</link> <link linkend='var-T'>T</link> <link linkend='var-UBOOT_CONFIG'>U</link> -<!-- <link linkend='var-glossary-v'>V</link> --> + <link linkend='var-VOLATILE_LOG_DIR'>V</link> <link linkend='var-WARN_QA'>W</link> <link linkend='var-XSERVER'>X</link> <!-- <link linkend='var-glossary-y'>Y</link> --> @@ -484,6 +484,12 @@ in your recipe so that it does contain <filename>${SRCPV}</filename>. </para> + + <para> + For more information see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" + section in the Yocto Project Development Manual. + </para> </glossdef> </glossentry> @@ -2364,6 +2370,160 @@ </glossdef> </glossentry> + <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm> + <info> + COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of licenses to exclude from the + source archived by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + In other words, if a license in a recipe's + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + value is in the value of + <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its + source is not archived by the class. + <note> + The <filename>COPYLEFT_LICENSE_EXCLUDE</filename> + variable takes precedence over the + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + variable. + </note> + The default value, which is "CLOSED Proprietary", for + <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm> + <info> + COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of licenses to include in the + source archived by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + In other words, if a license in a recipe's + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + value is in the value of + <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its + source is archived by the class. + </para> + + <para> + The default value is set by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + The default value includes "GPL*", "LGPL*", and "AGPL*". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm> + <info> + COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of recipes to exclude in the source archived + by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + The <filename>COPYLEFT_PN_EXCLUDE</filename> variable + overrides the license inclusion and exclusion caused + through the + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + and + <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link> + variables, respectively. + </para> + + <para> + The default value, which is "" indicating to not explicitly + exclude any recipes by name, for + <filename>COPYLEFT_PN_EXCLUDE</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm> + <info> + COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of recipes to include in the source archived + by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + The <filename>COPYLEFT_PN_INCLUDE</filename> variable + overrides the license inclusion and exclusion caused + through the + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + and + <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link> + variables, respectively. + </para> + + <para> + The default value, which is "" indicating to not explicitly + include any recipes by name, for + <filename>COPYLEFT_PN_INCLUDE</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm> + <info> + COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of recipe types to include + in the source archived by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + Recipe types are <filename>target</filename>, + <filename>native</filename>, + <filename>nativesdk</filename>, + <filename>cross</filename>, + <filename>crosssdk</filename>, and + <filename>cross-canadian</filename>. + </para> + + <para> + The default value, which is "target*", for + <filename>COPYLEFT_RECIPE_TYPES</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm> <info> COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package." @@ -3463,6 +3623,47 @@ </glossdef> </glossentry> + <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm> + <info> + DISTRO_FEATURES_FILTER_NATIVE[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building native recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that if present in + the target + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value should be included in + <filename>DISTRO_FEATURES</filename> when building native + recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm> + <info> + DISTRO_FEATURES_FILTER_NATIVESDK[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building nativesdk recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that if present in the target + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value should be included in + <filename>DISTRO_FEATURES</filename> when building + nativesdk recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link> + variable. + </para> + </glossdef> + </glossentry> + <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm> <info> DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)." @@ -3480,6 +3681,42 @@ </glossdef> </glossentry> + <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm> + <info> + DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that should be included in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + when building native recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm> + <info> + DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that should be included in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + when building nativesdk recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link> + variable. + </para> + </glossdef> + </glossentry> + <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> <info> DISTRO_NAME[doc] = "The long name of the distribution." @@ -3643,7 +3880,9 @@ <para> See the <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> - class for more information. + and + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> + classes for more information. </para> </glossdef> </glossentry> @@ -4954,6 +5193,53 @@ </glossdef> </glossentry> + <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm> + <info> + HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list (filter) of tools on the build host + that should be allowed to be called from within build tasks. + Using this filter helps reduce the possibility of host + contamination. + If a tool specified in the value of + <filename>HOSTTOOLS</filename> is not found on the + build host, the OpenEmbedded build system produces + an error and the build is not started. + </para> + + <para> + For additional information, see + <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm> + <info> + HOSTTOOLS_NONFATAL[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list (filter) of tools on the build host + that should be allowed to be called from within build tasks. + Using this filter helps reduce the possibility of host + contamination. + Unlike + <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>, + the OpenEmbedded build system does not produce and error + if a tool specified in the value of + <filename>HOSTTOOLS_NONFATAL</filename> is not found on the + build host. + Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename> + to filter optional host tools. + </para> + </glossdef> + </glossentry> + <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm> <info> HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR." @@ -6030,14 +6316,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> <info> - INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files." + INHERIT[doc] = "Causes the named class or classes to be inherited globally." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Causes the named class to be inherited at - this point during parsing. - The variable is only valid in configuration files. + Causes the named class or classes to be inherited globally. + Anonymous functions in the class or classes + are not executed for the + base configuration and in each individual recipe. + The OpenEmbedded build system ignores changes to + <filename>INHERIT</filename> in individual recipes. + </para> + + <para> + For more information on <filename>INHERIT</filename>, see + the + "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>" + section in the Yocto Project Bitbake User Manual. </para> </glossdef> </glossentry> @@ -7145,21 +7441,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> <info> - LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, upon which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." + LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, on which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists the layers that this recipe depends upon, separated by spaces. - Optionally, you can specify a specific layer version for a dependency - by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" - to be compared against - <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename> - in this case). - An error will be produced if any dependency is missing or - the version numbers do not match exactly (if specified). - This variable is used in the <filename>conf/layer.conf</filename> file - and must be suffixed with the name of the specific layer (e.g. + Lists the layers, separated by spaces, on which this + recipe depends. + Optionally, you can specify a specific layer version for a + dependency by adding it to the end of the layer name. + Here is an example: + <literallayout class='monospaced'> + LAYERDEPENDS_mylayer = "anotherlayer (=3)" + </literallayout> + In this previous example, version 3 of "anotherlayer" + is compared against + <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>. + </para> + + <para> + An error is produced if any dependency is missing or + the version numbers (if specified) do not match exactly. + This variable is used in the + <filename>conf/layer.conf</filename> file and must be + suffixed with the name of the specific layer (e.g. <filename>LAYERDEPENDS_mylayer</filename>). </para> </glossdef> @@ -7180,6 +7485,39 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm> + <info> + LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists the layers, separated by spaces, recommended for + use with this layer. + </para> + + <para> + Optionally, you can specify a specific layer version for a + recommendation by adding the version to the end of the + layer name. + Here is an example: + <literallayout class='monospaced'> + LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" + </literallayout> + In this previous example, version 3 of "anotherlayer" is + compared against + <filename>LAYERVERSION_anotherlayer</filename>. + </para> + + <para> + This variable is used in the + <filename>conf/layer.conf</filename> file and must be + suffixed with the name of the specific layer (e.g. + <filename>LAYERRECOMMENDS_mylayer</filename>). + </para> + </glossdef> + </glossentry> + <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> <info> LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." @@ -8198,13 +8536,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> +<!-- <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm> <info> MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories." </info> <glossdef> <para role="glossdeffirst"> +--> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> +<!-- Serves the same purpose as <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, but for the "HOST" system, in situations that involve a @@ -8222,6 +8563,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> </glossdef> </glossentry> +--> <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> <info> @@ -8251,9 +8593,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable for an example. - <link linkend='var-MULTIMACH_HOST_SYS'><filename>MULTIMACH_HOST_SYS</filename></link> - is the corresponding variable for the host system in - situations that involve a "HOST" and a "TARGET" system. See the <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link> variable for more information. @@ -8332,7 +8671,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>local.conf</filename> file or you can attach it to a specific image recipe by using the recipe name override: <literallayout class='monospaced'> - NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" + NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1" </literallayout> </para> @@ -9163,6 +9502,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm> + <info> + PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of dependencies for post-installation and + pre-installation scripts on native/cross tools. + If your post-installation or pre-installation script can + execute at rootfs creation time rather than on the + target but depends on a native tool in order to execute, + you need to list the tools in + <filename>PACKAGE_WRITE_DEPENDS</filename>. + </para> + + <para> + For information on running post-installation scripts, see + the + "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>" + section in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> <info> PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis." @@ -9299,29 +9663,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" from the <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> setting. - This list of options helps other classes and - recipes take advantage of the - <filename>PACKAGECONFIG</filename> mechanism without - having to include options from - <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>. </para> <para> - To illustrate how to use - <filename>PACKAGECONFIG_CONFARGS</filename>, consider the - following example: - <literallayout class='monospaced'> - PACKAGECONFIG_CONFARGS = " \ - -prefix ${prefix} \ - -sysroot ${STAGING_DIR_NATIVE} \ - -no-gcc-sysroot - " - </literallayout> - In the previous example, - <filename>PACKAGECONFIG_CONFARGS</filename> is set with - three configuration options that can be passed using the - <filename>PACKAGECONFIG</filename> mechanism, thus - avoiding having to use <filename>EXTRA_OECONF</filename>. + Classes such as + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + and + <link linkend='ref-classes-cmake'><filename>cmake</filename></link> + use <filename>PACKAGECONFIG_CONFARGS</filename> to pass + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + options to <filename>configure</filename> and + <filename>cmake</filename>, respectively. + If you are using + <filename>PACKAGECONFIG</filename> but not a class that + handles the <filename>do_configure</filename> task, then + you need to use + <filename>PACKAGECONFIG_CONFARGS</filename> appropriately. </para> <para> @@ -12499,15 +12856,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" every time BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a full revision identifier and not just a tag. + <note> + For information on limitations when inheriting the + latest revision of software using + <filename>SRCREV</filename>, see the + <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> + variable description and the + "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" + section, which is in the Yocto Project Development Manual. + </note> </para> - <note> - For information on limitations when inheriting the latest - revision of software using <filename>SRCREV</filename>, - see the - <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> - variable description. - </note> </glossdef> </glossentry> @@ -12588,6 +12947,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm> + <info> + SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Controls the list of files the OpenEmbedded build system + scans for hardcoded installation paths. The variable uses a + space-separated list of filenames (not paths) with standard + wildcard characters allowed. + </para> + + <para> + During a build, the OpenEmbedded build system creates a + shared state (sstate) object during the first stage of + preparing the sysroots. That object is scanned for + hardcoded paths for original installation locations. + The list of files that are scanned for paths is controlled + by the <filename>SSTATE_SCAN_FILES</filename> variable. + Typically, recipes add files they want to be scanned to the + value of <filename>SSTATE_SCAN_FILES</filename> rather than + the variable being comprehensively set. The + <link linkend='ref-classes-sstate'><filename>sstate</filename></link> + class specifies the default list of files. + </para> + + <para> + For details on the process, see the + <link linkend='ref-classes-staging'><filename>staging</filename></link> + class. + </para> + </glossdef> + </glossentry> + <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm> <info> STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host." @@ -12801,12 +13195,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" they make use of host headers and libraries. </para> </note> - </para></listitem> - <listitem><para>For native SDK - recipes that build for the SDK - (<filename>nativesdk</filename>), the value is - "${STAGING_DIR}/${<link linkend='var-MULTIMACH_HOST_SYS'>MULTIMACH_HOST_SYS</link>}". - </para></listitem> + </para></listitem> </itemizedlist> </para> </glossdef> @@ -13185,6 +13574,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm> + <info> + SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files that will be populated into the sysroot are assembled during the do_populate_sysroot task." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the temporary directory under the work directory + (default + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destidir</filename>) + where the files + that will be populated into the sysroot are assembled + during the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + <literallayout class='monospaced'> + SYSROOT_DESTDIR ?= "console=ttyS0,115200" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm> <info> SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task." @@ -14197,8 +14608,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <note> The <filename>TEST_SERVER_IP</filename> variable is only used for a small number of tests such as - the "smart" test suite, which needs to download - packages from <filename>DEPLOY_DIR/rpm</filename>. + the "dnf" test suite, which needs to download + packages from + <filename>WORKDIR/oe-rootfs-repo</filename>. </note> </para> </glossdef> @@ -15544,8 +15956,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdiv> -<!-- <glossdiv id='var-glossary-v'><title>V</title>--> -<!-- </glossdiv>--> + <glossdiv id='var-glossary-v'><title>V</title> + + <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm> + <info> + VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the persistence of the target's + <filename>/var/log</filename> directory, which is used to + house postinstall target log files. + </para> + + <para> + By default, <filename>VOLATILE_LOG_DIR</filename> is set + to "yes", which means the file is not persistent. + You can override this setting by setting the + variable to "no" to make the log directory persistent. + </para> + </glossdef> + </glossentry> + + </glossdiv> <glossdiv id='var-glossary-w'><title>W</title> @@ -15568,6 +16002,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm> + <info> + WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic." + </info> + <glossdef> + <para role="glossdeffirst"> + When placed in the recipe that builds your image, this + variable lists build-time dependencies. + The <filename>WKS_FILE_DEPENDS</filename> variable is only + applicable when Wic images are active (i.e. when + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + contains entries related to Wic). + If your recipe does not create Wic images, the variable + has no effect. + </para> + + <para> + The <filename>WKS_FILE_DEPENDS</filename> variable is + similar to the + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + variable. + When you use the variable in your recipe that builds the + Wic image, dependencies you list in the + <filename>WIC_FILE_DEPENDS</filename> variable are added to + the <filename>DEPENDS</filename> variable. + </para> + + <para> + With the <filename>WKS_FILE_DEPENDS</filename> variable, + you have the possibility to specify a list of additional + dependencies (e.g. native tools, bootloaders, and so forth), + that are required to build Wic images. + Following is an example: + <literallayout class='monospaced'> + WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>" + </literallayout> + In the previous example, + <replaceable>some-native-tool</replaceable> would be + replaced with an actual native tool on which the build + would depend. + </para> + </glossdef> + </glossentry> + <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm> <info> WKS_FILE[doc] = "Specifies the name of the wic kickstart file." diff --git a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml index 9bb09fb948..1964a9a105 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml @@ -432,7 +432,7 @@ For information on how the OpenEmbedded build system works with packages and can track incrementing <filename>PR</filename> information, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision Number</ulink>" + "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" section. </note> @@ -1445,14 +1445,33 @@ <para> The <filename>LIC_FILES_CHKSUM</filename> - variable contains checksums of the license text in the source code for the recipe. - Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>: + variable contains checksums of the license text in the source + code for the recipe. + Following is an example of how to specify + <filename>LIC_FILES_CHKSUM</filename>: <literallayout class='monospaced'> LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ file://licfile2.txt;endline=50;md5=zzzz \ ..." </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + When using "beginline" and "endline", realize that + line numbering begins with one and not zero. + Also, the included lines are inclusive (i.e. lines + five through and including 29 in the previous + example for <filename>licfile1.txt</filename>). + </para></listitem> + <listitem><para> + When a license check fails, the selected license + text is included as part of the QA message. + Using this output, you can determine the exact + start and finish for the needed license text. + </para></listitem> + </itemizedlist> + </note> </para> <para> @@ -1474,7 +1493,8 @@ <para> The first line locates a file in - <filename>${S}/src/ls.c</filename>. + <filename>${S}/src/ls.c</filename> and isolates lines five + through 16 as license text. The second line refers to a file in <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. </para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml index f7345547c5..d08031617b 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml @@ -69,6 +69,39 @@ <literallayout class='monospaced'> $ bitbake <replaceable>target</replaceable> </literallayout> + <note> + <para> + If you experience a build error due to resources + temporarily being unavailable and it appears you + should not be having this issue, it might be due + to the combination of a 4.3+ Linux kernel and + <filename>systemd</filename> version 228+ + (i.e. see this + <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> + for information). + </para> + + <para> + To work around this issue, you can try either + of the following: + <itemizedlist> + <listitem><para> + Try the build again. + </para></listitem> + <listitem><para> + Modify the "DefaultTasksMax" + <filename>systemd</filename> parameter + by uncommenting it and setting it to + "infinity". + You can find this parameter in the + <filename>system.conf</filename> file + located in + <filename>/etc/systemd</filename> + on most systems. + </para></listitem> + </itemizedlist> + </para> + </note> </para> <para> @@ -392,14 +425,6 @@ are not listed. </para></listitem> <listitem><para> - <filename>pn-depends.dot</filename>: A graph showing - dependencies between build-time targets (recipes). - </para></listitem> - <listitem><para> - <filename>package-depends.dot</filename>: A graph showing - known dependencies between runtime targets. - </para></listitem> - <listitem><para> <filename>task-depends.dot</filename>: A graph showing dependencies between tasks. </para></listitem> @@ -455,7 +480,7 @@ You can use a different method to view dependency information by using the following command: <literallayout class='monospaced'> - $ bitbake -g -u depexp <replaceable>recipename</replaceable> + $ bitbake -g -u taskexp <replaceable>recipename</replaceable> </literallayout> This command displays a GUI window from which you can view build-time and runtime dependencies for the recipes involved in @@ -711,79 +736,6 @@ </para> </section> - <section id='checking-for-missing-build-time-dependencies'> - <title>Checking for Missing Build-Time Dependencies</title> - - <para> - A recipe might build successfully even though some of its - build-time dependencies are missing from - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. - Following are the two most common ways in which that can happen: - <itemizedlist> - <listitem><para> - The build-time dependency just happens to already exist in - the staging sysroot - (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>) - by the time the recipe is built. - This situation occurs when the build-time dependency is - built earlier during recipe processing. - </para></listitem> - <listitem><para> - The component built by the recipe conditionally enables - functionality depending on whether it can find the - build-time dependency in the staging sysroot. - If the build-time dependency is missing, the corresponding - functionality is disabled. - This condition is known as a "floating dependency". - </para></listitem> - </itemizedlist> - </para> - - <para> - Because dealing with the second case is more complex, focus will - be on the first case. - The - <link linkend='ref-classes-insane'><filename>build-deps</filename></link> - QA check checks that every library the component linked against is - declared as a build-time dependency. - If that is not the case, then the first situation described in the - previous list exists, and <filename>build-deps</filename> reports - a missing build-time dependency. - </para> - - <para> - Another, more manual, way to check a recipe for missing build-time - dependencies of the first type is to build with an empty staging - sysroot. - This method can also find missing build-time dependencies - that are not in the form of libraries, which the - <filename>build-deps</filename> QA check is unable to find. - </para> - - <para> - An easy way to empty the staging sysroots is to simply remove - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, - which is usually - <filename>${</filename><link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link><filename>}/tmp</filename>, - as it includes the staging sysroots. - Another, faster method to empty the staging sysroots is to use the - <filename>scripts/wipe-sysroot</filename> script, - which removes just the staging sysroots and keeps everything else - in <filename>TMPDIR</filename>. - <note> - The <filename>scripts/</filename> directory appears in - <filename>PATH</filename> after running the build environment - initialization script (i.e. - <link linkend='structure-core-script'><filename>oe-init-build-env</filename></link> - or - <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>), - which results in the ability to to run - <filename>wipe-sysroot</filename> immediately. - </note> - </para> - - </section> - <section id='usingpoky-debugging-bitbake'> <title>General BitBake Problems</title> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml index 521f682634..9957057e99 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml @@ -2,7 +2,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<appendix id='sdk-appendix-mars'> +<appendix id='sdk-appendix-latest-yp-eclipse-plug-in'> <title>Using Eclipse Mars</title> <para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml index 3156f77258..d0cbf9c85e 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -96,16 +96,16 @@ <listitem><para> By default, this toolchain does not build static binaries. If you want to use the toolchain to build these types of - libraries, you need to be sure your image has the + libraries, you need to be sure your SDK has the appropriate static development libraries. Use the - <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></ulink> variable inside your <filename>local.conf</filename> file - to install the appropriate library packages. - Following is an example using <filename>glibc</filename> + to install the appropriate library packages in the SDK. + Following is an example using <filename>libc</filename> static development libraries: <literallayout class='monospaced'> - IMAGE_INSTALL_append = " glibc-staticdev" + TOOLCHAIN_TARGET_TASK_append = " libc-staticdev" </literallayout> </para></listitem> <listitem><para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml index c322189689..5c28e34eb0 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml @@ -42,14 +42,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -63,12 +78,33 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Software + Development Kit (SDK) Developer's Guide associated with + this Yocto Project release (version &YOCTO_DOC_VERSION;), + see the Yocto Project Software Development Kit (SDK) + Developer's Guide from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Software Development Kit (SDK) Developer's Guide, see + <ulink url='&YOCTO_DOCS_URL;/latest/sdk-manual/sdk-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml index df24aef0fb..54bc4d739d 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml @@ -459,7 +459,7 @@ release with the Yocto Project. For information on how to use the Mars version of Eclipse with the Yocto Project, see - "<link linkend='sdk-appendix-mars'>Appendix C</link>. + "<link linkend='sdk-appendix-latest-yp-eclipse-plug-in'>Appendix C</link>. </note> </para> @@ -501,7 +501,7 @@ <listitem><para> <emphasis>Locate the Neon Download:</emphasis> Open a browser and go to - <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>. + <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</ulink>. </para></listitem> <listitem><para> <emphasis>Download the Tarball:</emphasis> diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml index 05efb1f3a1..c7a7fcd787 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml @@ -52,14 +52,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -73,12 +88,32 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Toaster + User Manual associated with this Yocto Project release + (version &YOCTO_DOC_VERSION;), + see the Yocto Project Toaster User Manual from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Toaster User Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/toaster-manual/toaster-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> diff --git a/import-layers/yocto-poky/documentation/tools/mega-manual.sed b/import-layers/yocto-poky/documentation/tools/mega-manual.sed index 8aea1ced8f..936b1095cb 100644 --- a/import-layers/yocto-poky/documentation/tools/mega-manual.sed +++ b/import-layers/yocto-poky/documentation/tools/mega-manual.sed @@ -2,32 +2,32 @@ # This style is for manual folders like "yocto-project-qs" and "poky-ref-manual". # This is the old way that did it. Can't do that now that we have "bitbake-user-manual" strings # in the mega-manual. -# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g # Processes all other manuals (<word>-<word> style) except for the BitBake User Manual because # it is not included in the mega-manual. # This style is for manual folders that use two word, which is the standard now (e.g. "ref-manual"). # This was the one-liner that worked before we introduced the BitBake User Manual, which is # not in the mega-manual. -# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/sdk-manual\/sdk-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/toaster-manual\/toaster-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/sdk-manual\/sdk-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/toaster-manual\/toaster-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g # Process cases where just an external manual is referenced without an id anchor -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Manual<\/a>/Yocto Project Development Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/sdk-manual\/sdk-manual.html\" target=\"_top\">Yocto Project Software Development Kit (SDK) Developer's Guide<\/a>/Yocto Project Software Development Kit (SDK) Developer's Guide/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/profile-manual\/profile-manual.html\" target=\"_top\">Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2.2\/toaster-manual\/toaster-manual.html\" target=\"_top\">Toaster User Manual<\/a>/Toaster User Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Manual<\/a>/Yocto Project Development Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/sdk-manual\/sdk-manual.html\" target=\"_top\">Yocto Project Software Development Kit (SDK) Developer's Guide<\/a>/Yocto Project Software Development Kit (SDK) Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/profile-manual\/profile-manual.html\" target=\"_top\">Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.3.4\/toaster-manual\/toaster-manual.html\" target=\"_top\">Toaster User Manual<\/a>/Toaster User Manual/g diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/figures/yocto-environment.png b/import-layers/yocto-poky/documentation/yocto-project-qs/figures/yocto-environment.png Binary files differindex 82b7a55a35..35969038c9 100644 --- a/import-layers/yocto-poky/documentation/yocto-project-qs/figures/yocto-environment.png +++ b/import-layers/yocto-poky/documentation/yocto-project-qs/figures/yocto-environment.png diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml b/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml index 950a4ff8be..b4b3f4bd0e 100644 --- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml @@ -16,11 +16,31 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink> - from the Yocto Project website. + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Quick + Start associated with this Yocto Project release + (version &YOCTO_DOC_VERSION;), + see the Yocto Project Quick Start from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Quick Start, see + <ulink url='&YOCTO_DOCS_URL;/latest/yocto-project-qs/yocto-project-qs.html'></ulink>. + </para></listitem> + </itemizedlist> </note> </legalnotice> @@ -44,7 +64,8 @@ tool, to construct complete Linux images. The BitBake and OE components are combined together to form a reference build host, historically known as - <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>. + <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> + (<emphasis>Pah</emphasis>-key). </para> <para> @@ -125,11 +146,8 @@ <mediaobject> <imageobject> <imagedata fileref="figures/yocto-environment.png" - format="PNG" align='center' scalefit='1' width="100%"/> + format="PNG" align='center' width="8in"/> </imageobject> - <caption> - <para>The Yocto Project Development Environment</para> - </caption> </mediaobject> <para> @@ -302,8 +320,7 @@ <itemizedlist> <listitem><para><emphasis>Ubuntu and Debian</emphasis> <literallayout class='monospaced'> - $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; \ - libsdl1.2-dev xterm + $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm </literallayout> </para></listitem> <listitem><para><emphasis>Fedora</emphasis> @@ -313,22 +330,31 @@ </para></listitem> <listitem><para><emphasis>OpenSUSE</emphasis> <literallayout class='monospaced'> - $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; \ - libSDL-devel xterm + $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm </literallayout> </para></listitem> <listitem><para><emphasis>CentOS</emphasis> <literallayout class='monospaced'> - $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; \ - SDL-devel xterm + $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm </literallayout> - <note> - CentOS 6.x users need to ensure that the required - versions of Git, tar and Python are available. - For details, See the - "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>" - section in the Yocto Project Reference Manual for - information. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Extra Packages for Enterprise Linux + (i.e. <filename>epel-release</filename>) + is a collection of packages from Fedora + built on RHEL/CentOS for easy installation + of packages not included in enterprise + Linux by default. + You need to install these packages + separately. + </para></listitem> + <listitem><para> + The <filename>makecache</filename> command + consumes additional Metadata from + <filename>epel-release</filename>. + </para></listitem> + </itemizedlist> </note> </para></listitem> </itemizedlist> @@ -357,11 +383,12 @@ <literallayout class='monospaced'> $ git clone git://git.yoctoproject.org/poky Cloning into 'poky'... - remote: Counting objects: 226790, done. - remote: Compressing objects: 100% (57465/57465), done. - remote: Total 226790 (delta 165212), reused 225887 (delta 164327) - Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done. - Resolving deltas: 100% (165212/165212), done. + remote: Counting objects: 361782, done. + remote: Compressing objects: 100% (87100/87100), done. + remote: Total 361782 (delta 268619), reused 361439 (delta 268277) + Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done. + Resolving deltas: 100% (268619/268619), done. + Checking connectivity... done. $ git checkout &DISTRO_NAME_NO_CAP; </literallayout> You can also get the Yocto Project Files by downloading @@ -569,14 +596,47 @@ <note> Depending on the number of processors and cores, the amount of RAM, the speed of your Internet connection - and other factors, the build process could take several - hours the first time you run it. + and other factors, the build process could take + several hours the first time you run it. Subsequent builds run much faster since parts of the build are cached. </note> <literallayout class='monospaced'> $ bitbake core-image-sato </literallayout> + <note> + <para> + If you experience a build error due to resources + temporarily being unavailable and it appears you + should not be having this issue, it might be due + to the combination of a 4.3+ Linux kernel and + <filename>systemd</filename> version 228+ + (i.e. see this + <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> + for information). + </para> + + <para> + To work around this issue, you can try either + of the following: + <itemizedlist> + <listitem><para> + Try the build again. + </para></listitem> + <listitem><para> + Modify the "DefaultTasksMax" + <filename>systemd</filename> parameter + by uncommenting it and setting it to + "infinity". + You can find this parameter in the + <filename>system.conf</filename> file + located in + <filename>/etc/systemd</filename> + on most systems. + </para></listitem> + </itemizedlist> + </para> + </note> For information on using the <filename>bitbake</filename> command, see the "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>" @@ -599,8 +659,8 @@ </para></listitem> <listitem><para><emphasis>Exit QEMU:</emphasis> Exit QEMU by either clicking on the shutdown icon or by - opening a terminal, typing - <filename>poweroff</filename>, and then pressing "Enter". + typing <filename>Ctrl-C</filename> in the QEMU + transcript window from which you evoked QEMU. </para></listitem> </orderedlist> </para> @@ -639,11 +699,11 @@ $ cd $HOME/poky $ git clone git://git.yoctoproject.org/meta-intel Cloning into 'meta-intel'... - remote: Counting objects: 11988, done. - remote: Compressing objects: 100% (3884/3884), done. - Receiving objects: 100% (11988/11988), 2.93 MiB | 2.51 MiB/s, done. - remote: Total 11988 (delta 6881), reused 11752 (delta 6645) - Resolving deltas: 100% (6881/6881), done. + remote: Counting objects: 14039, done. + remote: Compressing objects: 100% (4471/4471), done. + remote: Total 14039 (delta 8130), reused 13837 (delta 7947) + Receiving objects: 100% (14039/14039), 4.27 MiB | 3.98 MiB/s, done. + Resolving deltas: 100% (8130/8130), done. Checking connectivity... done. </literallayout> By default when you clone a Git repository, the @@ -727,6 +787,39 @@ <literallayout class='monospaced'> $ bitbake core-image-base </literallayout> + <note> + <para> + If you experience a build error due to resources + temporarily being unavailable and it appears you + should not be having this issue, it might be due + to the combination of a 4.3+ Linux kernel and + <filename>systemd</filename> version 228+ + (i.e. see this + <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> + for information). + </para> + + <para> + To work around this issue, you can try either + of the following: + <itemizedlist> + <listitem><para> + Try the build again. + </para></listitem> + <listitem><para> + Modify the "DefaultTasksMax" + <filename>systemd</filename> parameter + by uncommenting it and setting it to + "infinity". + You can find this parameter in the + <filename>system.conf</filename> file + located in + <filename>/etc/systemd</filename> + on most systems. + </para></listitem> + </itemizedlist> + </para> + </note> Once the build completes, the resulting console-only image is located in the Build Directory here: <literallayout class='monospaced'> |
