summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.rst1130
-rw-r--r--documentation/dev-manual/dev-manual-intro.rst2
-rw-r--r--documentation/dev-manual/dev-manual-qemu.rst43
-rw-r--r--documentation/dev-manual/dev-manual-start.rst79
4 files changed, 566 insertions, 688 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index e993a8ce40..dedc30d7d3 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -39,7 +39,7 @@ Follow these general steps to create your layer without using tools:
391. *Check Existing Layers:* Before creating a new layer, you should be 391. *Check Existing Layers:* Before creating a new layer, you should be
40 sure someone has not already created a layer containing the Metadata 40 sure someone has not already created a layer containing the Metadata
41 you need. You can see the `OpenEmbedded Metadata 41 you need. You can see the `OpenEmbedded Metadata
42 Index <http://layers.openembedded.org/layerindex/layers/>`__ for a 42 Index <https://layers.openembedded.org/layerindex/layers/>`__ for a
43 list of layers from the OpenEmbedded community that can be used in 43 list of layers from the OpenEmbedded community that can be used in
44 the Yocto Project. You could find a layer that is identical or close 44 the Yocto Project. You could find a layer that is identical or close
45 to what you need. 45 to what you need.
@@ -84,7 +84,7 @@ Follow these general steps to create your layer without using tools:
84 # We have a conf and classes directory, add to BBPATH 84 # We have a conf and classes directory, add to BBPATH
85 BBPATH .= ":${LAYERDIR}" 85 BBPATH .= ":${LAYERDIR}"
86 86
87 # We have recipes-\* directories, add to BBFILES 87 # We have recipes-* directories, add to BBFILES
88 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ 88 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
89 ${LAYERDIR}/recipes-*/*/*.bbappend" 89 ${LAYERDIR}/recipes-*/*/*.bbappend"
90 90
@@ -150,10 +150,8 @@ Follow these general steps to create your layer without using tools:
150 .. note:: 150 .. note::
151 151
152 For an explanation of layer hierarchy that is compliant with the 152 For an explanation of layer hierarchy that is compliant with the
153 Yocto Project, see the " 153 Yocto Project, see the ":ref:`bsp-guide/bsp:example filesystem layout`"
154 Example Filesystem Layout 154 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
155 " section in the Yocto Project Board Support Package (BSP)
156 Developer's Guide.
157 155
1585. *Optionally Test for Compatibility:* If you want permission to use 1565. *Optionally Test for Compatibility:* If you want permission to use
159 the Yocto Project Compatibility logo with your layer or application 157 the Yocto Project Compatibility logo with your layer or application
@@ -181,8 +179,8 @@ following list:
181 for each recipe that uses an include file. Or, if you are introducing 179 for each recipe that uses an include file. Or, if you are introducing
182 a new recipe that requires the included file, use the path relative 180 a new recipe that requires the included file, use the path relative
183 to the original layer directory to refer to the file. For example, 181 to the original layer directory to refer to the file. For example,
184 use ``require recipes-core/``\ package\ ``/``\ file\ ``.inc`` instead 182 use ``require recipes-core/``\ `package`\ ``/``\ `file`\ ``.inc`` instead
185 of ``require``\ file\ ``.inc``. If you're finding you have to overlay 183 of ``require`` `file`\ ``.inc``. If you're finding you have to overlay
186 the include file, it could indicate a deficiency in the include file 184 the include file, it could indicate a deficiency in the include file
187 in the layer to which it originally belongs. If this is the case, you 185 in the layer to which it originally belongs. If this is the case, you
188 should try to address that deficiency instead of overlaying the 186 should try to address that deficiency instead of overlaying the
@@ -214,8 +212,12 @@ following list:
214 ``foo``. 212 ``foo``.
215 213
216 To make sure your changes apply only when building machine "one", 214 To make sure your changes apply only when building machine "one",
217 use a machine override with the ``DEPENDS`` statement: DEPENDS_one 215 use a machine override with the ``DEPENDS`` statement:
218 = "foo" You should follow the same strategy when using ``_append`` 216 ::
217
218 DEPENDS_one = "foo"
219
220 You should follow the same strategy when using ``_append``
219 and ``_prepend`` operations: 221 and ``_prepend`` operations:
220 :: 222 ::
221 223
@@ -244,11 +246,8 @@ following list:
244 246
245 .. note:: 247 .. note::
246 248
247 Avoiding "+=" and "=+" and using machine-specific 249 Avoiding "+=" and "=+" and using machine-specific ``_append``
248 \_append 250 and ``_prepend`` operations is recommended as well.
249 and
250 \_prepend
251 operations is recommended as well.
252 251
253 - *Place Machine-Specific Files in Machine-Specific Locations:* When 252 - *Place Machine-Specific Files in Machine-Specific Locations:* When
254 you have a base recipe, such as ``base-files.bb``, that contains a 253 you have a base recipe, such as ``base-files.bb``, that contains a
@@ -256,11 +255,12 @@ following list:
256 file, you can use an append file to cause the build to use your 255 file, you can use an append file to cause the build to use your
257 own version of the file. For example, an append file in your layer 256 own version of the file. For example, an append file in your layer
258 at ``meta-one/recipes-core/base-files/base-files.bbappend`` could 257 at ``meta-one/recipes-core/base-files/base-files.bbappend`` could
259 extend :term:`FILESPATH` 258 extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:
260 using 259 ::
261 :term:`FILESEXTRAPATHS` 260
262 as follows: FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:" The 261 FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
263 build for machine "one" will pick up your machine-specific file as 262
263 The build for machine "one" will pick up your machine-specific file as
264 long as you have the file in 264 long as you have the file in
265 ``meta-one/recipes-core/base-files/base-files/``. However, if you 265 ``meta-one/recipes-core/base-files/base-files/``. However, if you
266 are building for a different machine and the ``bblayers.conf`` 266 are building for a different machine and the ``bblayers.conf``
@@ -311,9 +311,7 @@ Project Compatible Logo.
311 Only Yocto Project member organizations are permitted to use the 311 Only Yocto Project member organizations are permitted to use the
312 Yocto Project Compatible Logo. The logo is not available for general 312 Yocto Project Compatible Logo. The logo is not available for general
313 use. For information on how to become a Yocto Project member 313 use. For information on how to become a Yocto Project member
314 organization, see the 314 organization, see the :yocto_home:`Yocto Project Website <>`.
315 Yocto Project Website
316 .
317 315
318The Yocto Project Compatibility Program consists of a layer application 316The Yocto Project Compatibility Program consists of a layer application
319process that requests permission to use the Yocto Project Compatibility 317process that requests permission to use the Yocto Project Compatibility
@@ -482,7 +480,7 @@ have to manually merge changes as they occur.
482 480
483When you create an append file, you must use the same root name as the 481When you create an append file, you must use the same root name as the
484corresponding recipe file. For example, the append file 482corresponding recipe file. For example, the append file
485``someapp_DISTRO.bbappend`` must apply to ``someapp_DISTRO.bb``. This 483``someapp_3.1.bbappend`` must apply to ``someapp_3.1.bb``. This
486means the original recipe and append file names are version 484means the original recipe and append file names are version
487number-specific. If the corresponding recipe is renamed to update to a 485number-specific. If the corresponding recipe is renamed to update to a
488newer version, you must also rename and possibly update the 486newer version, you must also rename and possibly update the
@@ -500,6 +498,9 @@ the "meta" layer at ``meta/recipes-bsp/formfactor``:
500:: 498::
501 499
502 SUMMARY = "Device formfactor information" 500 SUMMARY = "Device formfactor information"
501 DESCRIPTION = "A formfactor configuration file provides information about the \
502 target hardware for which the image is being built and information that the \
503 build system cannot obtain from other sources such as the kernel."
503 SECTION = "base" 504 SECTION = "base"
504 LICENSE = "MIT" 505 LICENSE = "MIT"
505 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" 506 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
@@ -603,7 +604,7 @@ For help on the BitBake layer management tool, use the following
603command: 604command:
604:: 605::
605 606
606 $ bitbake-layers --help NOTE: Starting bitbake server... usage: 607 $ bitbake-layers --help
607 NOTE: Starting bitbake server... 608 NOTE: Starting bitbake server...
608 usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ... 609 usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ...
609 610
@@ -751,9 +752,13 @@ create a layer with the following:
751 752
752In its simplest form, you can use the following command form to create a 753In its simplest form, you can use the following command form to create a
753layer. The command creates a layer whose name corresponds to 754layer. The command creates a layer whose name corresponds to
754your_layer_name in the current directory: $ bitbake-layers create-layer 755"your_layer_name" in the current directory:
755your_layer_name As an example, the following command creates a layer 756::
756named ``meta-scottrif`` in your home directory: 757
758 $ bitbake-layers create-layer your_layer_name
759
760As an example, the following command creates a layer named ``meta-scottrif``
761in your home directory:
757:: 762::
758 763
759 $ cd /usr/home 764 $ cd /usr/home
@@ -762,12 +767,12 @@ named ``meta-scottrif`` in your home directory:
762 Add your new layer with 'bitbake-layers add-layer meta-scottrif' 767 Add your new layer with 'bitbake-layers add-layer meta-scottrif'
763 768
764If you want to set the priority of the layer to other than the default 769If you want to set the priority of the layer to other than the default
765value of "6", you can either use the ``DASHDASHpriority`` option or you 770value of "6", you can either use the ``--priority`` option or you
766can edit the 771can edit the
767:term:`BBFILE_PRIORITY` value 772:term:`BBFILE_PRIORITY` value
768in the ``conf/layer.conf`` after the script creates it. Furthermore, if 773in the ``conf/layer.conf`` after the script creates it. Furthermore, if
769you want to give the example recipe file some name other than the 774you want to give the example recipe file some name other than the
770default, you can use the ``DASHDASHexample-recipe-name`` option. 775default, you can use the ``--example-recipe-name`` option.
771 776
772The easiest way to see how the ``bitbake-layers create-layer`` command 777The easiest way to see how the ``bitbake-layers create-layer`` command
773works is to experiment with the script. You can also read the usage 778works is to experiment with the script. You can also read the usage
@@ -871,13 +876,16 @@ you want to avoid ordering issues. The reason for this is because doing
871so unconditionally appends to the variable and avoids ordering problems 876so unconditionally appends to the variable and avoids ordering problems
872due to the variable being set in image recipes and ``.bbclass`` files 877due to the variable being set in image recipes and ``.bbclass`` files
873with operators like ``?=``. Using ``_append`` ensures the operation 878with operators like ``?=``. Using ``_append`` ensures the operation
874takes affect. 879takes effect.
875 880
876As shown in its simplest use, ``IMAGE_INSTALL_append`` affects all 881As shown in its simplest use, ``IMAGE_INSTALL_append`` affects all
877images. It is possible to extend the syntax so that the variable applies 882images. It is possible to extend the syntax so that the variable applies
878to a specific image only. Here is an example: 883to a specific image only. Here is an example:
879IMAGE_INSTALL_append_pn-core-image-minimal = " strace" This example adds 884::
880``strace`` to the ``core-image-minimal`` image only. 885
886 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
887
888This example adds ``strace`` to the ``core-image-minimal`` image only.
881 889
882You can add packages using a similar approach through the 890You can add packages using a similar approach through the
883``CORE_IMAGE_EXTRA_INSTALL`` variable. If you use this variable, only 891``CORE_IMAGE_EXTRA_INSTALL`` variable. If you use this variable, only
@@ -937,10 +945,9 @@ configures the image you are working with to include
937 945
938.. note:: 946.. note::
939 947
940 See the " 948 See the ":ref:`ref-manual/ref-features:image features`" section in the Yocto
941 Images 949 Project Reference Manual for a complete list of image features that ship
942 " section in the Yocto Project Reference Manual for a complete list 950 with the Yocto Project.
943 of image features that ship with the Yocto Project.
944 951
945.. _usingpoky-extend-customimage-custombb: 952.. _usingpoky-extend-customimage-custombb:
946 953
@@ -988,12 +995,8 @@ package specified in the ``PACKAGES`` statement.
988 995
989.. note:: 996.. note::
990 997
991 The 998 The ``inherit packagegroup`` line should be located near the top of the
992 inherit packagegroup 999 recipe, certainly before the ``PACKAGES`` statement.
993 line should be located near the top of the recipe, certainly before
994 the
995 PACKAGES
996 statement.
997 1000
998For each package you specify in ``PACKAGES``, you can use ``RDEPENDS`` 1001For each package you specify in ``PACKAGES``, you can use ``RDEPENDS``
999and ``RRECOMMENDS`` entries to provide a list of packages the parent 1002and ``RRECOMMENDS`` entries to provide a list of packages the parent
@@ -1090,9 +1093,9 @@ how to create, write, and test a new recipe.
1090.. note:: 1093.. note::
1091 1094
1092 For information on variables that are useful for recipes and for 1095 For information on variables that are useful for recipes and for
1093 information about recipe naming issues, see the " 1096 information about recipe naming issues, see the
1094 Required 1097 ":ref:`ref-manual/ref-varlocality:recipes`" section of the Yocto Project
1095 " section of the Yocto Project Reference Manual. 1098 Reference Manual.
1096 1099
1097.. _new-recipe-overview: 1100.. _new-recipe-overview:
1098 1101
@@ -1124,9 +1127,8 @@ that can help you quickly get a start on a new recipe:
1124 1127
1125.. note:: 1128.. note::
1126 1129
1127 For information on recipe syntax, see the " 1130 For information on recipe syntax, see the
1128 Recipe Syntax 1131 ":ref:`dev-manual/dev-manual-common-tasks:recipe syntax`" section.
1129 " section.
1130 1132
1131.. _new-recipe-creating-the-base-recipe-using-devtool: 1133.. _new-recipe-creating-the-base-recipe-using-devtool:
1132 1134
@@ -1161,7 +1163,7 @@ license requirements, and checksums configured.
1161To run the tool, you just need to be in your 1163To run the tool, you just need to be in your
1162:term:`Build Directory` and have sourced the 1164:term:`Build Directory` and have sourced the
1163build environment setup script (i.e. 1165build environment setup script (i.e.
1164`:ref:`structure-core-script`). 1166:ref:`structure-core-script`).
1165To get help on the tool, use the following command: 1167To get help on the tool, use the following command:
1166:: 1168::
1167 1169
@@ -1187,29 +1189,29 @@ To get help on the tool, use the following command:
1187 appendsrcfile Create/update a bbappend to add or replace a source file 1189 appendsrcfile Create/update a bbappend to add or replace a source file
1188 Use recipetool <subcommand> --help to get help on a specific command 1190 Use recipetool <subcommand> --help to get help on a specific command
1189 1191
1190Running ``recipetool create -o`` OUTFILE creates the base recipe and 1192Running ``recipetool create -o OUTFILE`` creates the base recipe and
1191locates it properly in the layer that contains your source files. 1193locates it properly in the layer that contains your source files.
1192Following are some syntax examples: 1194Following are some syntax examples:
1193 1195
1194Use this syntax to generate a recipe based on source. Once generated, 1196 - Use this syntax to generate a recipe based on source. Once generated,
1195the recipe resides in the existing source code layer: 1197 the recipe resides in the existing source code layer:
1196:: 1198 ::
1197 1199
1198 recipetool create -o OUTFILE source 1200 recipetool create -o OUTFILE source
1199 1201
1200Use this syntax to generate a recipe using code that 1202 - Use this syntax to generate a recipe using code that
1201you extract from source. The extracted code is placed in its own layer 1203 you extract from source. The extracted code is placed in its own layer
1202defined by EXTERNALSRC. 1204 defined by ``EXTERNALSRC``.
1203:: 1205 ::
1204 1206
1205 recipetool create -o OUTFILE -x EXTERNALSRC source 1207 recipetool create -o OUTFILE -x EXTERNALSRC source
1206 1208
1207Use this syntax to generate a recipe based on source. The options 1209 - Use this syntax to generate a recipe based on source. The options
1208direct ``recipetool`` to generate debugging information. Once generated, 1210 direct ``recipetool`` to generate debugging information. Once generated,
1209the recipe resides in the existing source code layer: 1211 the recipe resides in the existing source code layer:
1210:: 1212 ::
1211 1213
1212 recipetool create -d -o OUTFILE source 1214 recipetool create -d -o OUTFILE source
1213 1215
1214.. _new-recipe-locating-and-using-a-similar-recipe: 1216.. _new-recipe-locating-and-using-a-similar-recipe:
1215 1217
@@ -1221,7 +1223,7 @@ whether someone else has already written one that meets (or comes close
1221to meeting) your needs. The Yocto Project and OpenEmbedded communities 1223to meeting) your needs. The Yocto Project and OpenEmbedded communities
1222maintain many recipes that might be candidates for what you are doing. 1224maintain many recipes that might be candidates for what you are doing.
1223You can find a good central index of these recipes in the `OpenEmbedded 1225You can find a good central index of these recipes in the `OpenEmbedded
1224Layer Index <http://layers.openembedded.org>`__. 1226Layer Index <https://layers.openembedded.org>`__.
1225 1227
1226Working from an existing recipe or a skeleton recipe is the best way to 1228Working from an existing recipe or a skeleton recipe is the best way to
1227get started. Here are some points on both methods: 1229get started. Here are some points on both methods:
@@ -1280,13 +1282,18 @@ the recipe.
1280 Layers <#understanding-and-creating-layers>`__" section. 1282 Layers <#understanding-and-creating-layers>`__" section.
1281 1283
1282- *Naming Your Recipe:* When you name your recipe, you need to follow 1284- *Naming Your Recipe:* When you name your recipe, you need to follow
1283 this naming convention: basename_version.bb Use lower-cased 1285 this naming convention:
1284 characters and do not include the reserved suffixes ``-native``,
1285 ``-cross``, ``-initial``, or ``-dev`` casually (i.e. do not use them
1286 as part of your recipe name unless the string applies). Here are some
1287 examples:
1288 :: 1286 ::
1289 1287
1288 basename_version.bb
1289
1290 Use lower-cased characters and do not include the reserved suffixes
1291 ``-native``, ``-cross``, ``-initial``, or ``-dev`` casually (i.e. do not use
1292 them as part of your recipe name unless the string applies). Here are some
1293 examples:
1294
1295 .. code-block:: none
1296
1290 cups_1.7.0.bb 1297 cups_1.7.0.bb
1291 gawk_4.0.2.bb 1298 gawk_4.0.2.bb
1292 irssi_0.8.16-rc1.bb 1299 irssi_0.8.16-rc1.bb
@@ -1320,34 +1327,28 @@ context in which it is being built. The quickest way to find this path
1320is to have BitBake return it by running the following: 1327is to have BitBake return it by running the following:
1321:: 1328::
1322 1329
1323 $ bitbake -e basename \| grep ^WORKDIR= 1330 $ bitbake -e basename | grep ^WORKDIR=
1324 1331
1325As an example, assume a Source Directory 1332As an example, assume a Source Directory
1326top-level folder named ``poky``, a default Build Directory at 1333top-level folder named ``poky``, a default Build Directory at
1327``poky/build``, and a ``qemux86-poky-linux`` machine target system. 1334``poky/build``, and a ``qemux86-poky-linux`` machine target system.
1328Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this 1335Furthermore, suppose your recipe is named ``foo_1.3.0.bb``. In this
1329case, the work directory the build system uses to build the package 1336case, the work directory the build system uses to build the package
1330would be as follows: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 1337would be as follows:
1338::
1339
1340 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1341
1331Inside this directory you can find sub-directories such as ``image``, 1342Inside this directory you can find sub-directories such as ``image``,
1332``packages-split``, and ``temp``. After the build, you can examine these 1343``packages-split``, and ``temp``. After the build, you can examine these
1333to determine how well the build went. 1344to determine how well the build went.
1334 1345
1335.. note:: 1346.. note::
1336 1347
1337 You can find log files for each task in the recipe's 1348 You can find log files for each task in the recipe's ``temp``
1338 temp 1349 directory (e.g. ``poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp``).
1339 directory (e.g. 1350 Log files are named ``log.taskname`` (e.g. ``log.do_configure``,
1340 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp 1351 ``log.do_fetch``, and ``log.do_compile``).
1341 ). Log files are named
1342 log.
1343 taskname
1344 (e.g.
1345 log.do_configure
1346 ,
1347 log.do_fetch
1348 , and
1349 log.do_compile
1350 ).
1351 1352
1352You can find more information about the build process in 1353You can find more information about the build process in
1353":doc:`../overview-manual/overview-manual-development-environment`" 1354":doc:`../overview-manual/overview-manual-development-environment`"
@@ -1391,7 +1392,7 @@ comes from a single tarball. Notice the use of the
1391:term:`PV` variable: 1392:term:`PV` variable:
1392:: 1393::
1393 1394
1394 SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \\ 1395 SRC_URI = "https://strace.io/files/${PV}/strace-${PV}.tar.xz \
1395 1396
1396Files mentioned in ``SRC_URI`` whose names end in a typical archive 1397Files mentioned in ``SRC_URI`` whose names end in a typical archive
1397extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so 1398extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so
@@ -1576,8 +1577,8 @@ variables:
1576 the checksums of the files to be sure the text has not changed. Any 1577 the checksums of the files to be sure the text has not changed. Any
1577 differences result in an error with the message containing the 1578 differences result in an error with the message containing the
1578 current checksum. For more explanation and examples of how to set the 1579 current checksum. For more explanation and examples of how to set the
1579 ``LIC_FILES_CHKSUM`` variable, see the "`Tracking License 1580 ``LIC_FILES_CHKSUM`` variable, see the
1580 Changes <#>`__" section. 1581 ":ref:`dev-manual/dev-manual-common-tasks:tracking license changes`" section.
1581 1582
1582 To determine the correct checksum string, you can list the 1583 To determine the correct checksum string, you can list the
1583 appropriate files in the ``LIC_FILES_CHKSUM`` variable with incorrect 1584 appropriate files in the ``LIC_FILES_CHKSUM`` variable with incorrect
@@ -1659,13 +1660,10 @@ a build configuration file.
1659 As of Yocto Project Release 1.7, some of the core recipes that 1660 As of Yocto Project Release 1.7, some of the core recipes that
1660 package binary configuration scripts now disable the scripts due to 1661 package binary configuration scripts now disable the scripts due to
1661 the scripts previously requiring error-prone path substitution. The 1662 the scripts previously requiring error-prone path substitution. The
1662 OpenEmbedded build system uses 1663 OpenEmbedded build system uses ``pkg-config`` now, which is much more
1663 pkg-config 1664 robust. You can find a list of the ``*-config`` scripts that are disabled
1664 now, which is much more robust. You can find a list of the 1665 in the ":ref:`migration-1.7-binary-configuration-scripts-disabled`" section
1665 \*-config 1666 in the Yocto Project Reference Manual.
1666 scripts that are disabled list in the "
1667 Binary Configuration Scripts Disabled
1668 " section in the Yocto Project Reference Manual.
1669 1667
1670A major part of build-time configuration is about checking for 1668A major part of build-time configuration is about checking for
1671build-time dependencies and possibly enabling optional functionality as 1669build-time dependencies and possibly enabling optional functionality as
@@ -1709,11 +1707,7 @@ your software is built:
1709 1707
1710 If you need to install one or more custom CMake toolchain files 1708 If you need to install one or more custom CMake toolchain files
1711 that are supplied by the application you are building, install the 1709 that are supplied by the application you are building, install the
1712 files to 1710 files to ``${D}${datadir}/cmake/Modules`` during ``do_install``.
1713 ${D}${datadir}/cmake/
1714 Modules during
1715 do_install
1716 .
1717 1711
1718- *Other:* If your source files do not have a ``configure.ac`` or 1712- *Other:* If your source files do not have a ``configure.ac`` or
1719 ``CMakeLists.txt`` file, then your software is built using some 1713 ``CMakeLists.txt`` file, then your software is built using some
@@ -1764,11 +1758,8 @@ with custom or machine-specific header information. If you customize
1764 1758
1765.. note:: 1759.. note::
1766 1760
1767 Never copy and customize the 1761 Never copy and customize the ``libc`` header file (i.e.
1768 libc 1762 ``meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc``).
1769 header file (i.e.
1770 meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc
1771 ).
1772 1763
1773The correct way to interface to a device or custom kernel is to use a 1764The correct way to interface to a device or custom kernel is to use a
1774separate package that provides the additional headers for the driver or 1765separate package that provides the additional headers for the driver or
@@ -1794,13 +1785,10 @@ previous list.
1794 1785
1795.. note:: 1786.. note::
1796 1787
1797 If for some reason your changes need to modify the behavior of the 1788 If for some reason your changes need to modify the behavior of the ``libc``,
1798 libc 1789 and subsequently all other applications on the system, use a ``.bbappend``
1799 , and subsequently all other applications on the system, use a 1790 to modify the ``linux-kernel-headers.inc`` file. However, take care to not
1800 .bbappend 1791 make the changes machine specific.
1801 to modify the
1802 linux-kernel-headers.inc
1803 file. However, take care to not make the changes machine specific.
1804 1792
1805Consider a case where your kernel is older and you need an older 1793Consider a case where your kernel is older and you need an older
1806``libc`` ABI. The headers installed by your recipe should still be a 1794``libc`` ABI. The headers installed by your recipe should still be a
@@ -1830,11 +1818,8 @@ Here are some common issues that cause failures.
1830 1818
1831 For cases where improper paths are detected for configuration files 1819 For cases where improper paths are detected for configuration files
1832 or for when libraries/headers cannot be found, be sure you are using 1820 or for when libraries/headers cannot be found, be sure you are using
1833 the more robust 1821 the more robust ``pkg-config``. See the note in section
1834 pkg-config 1822 ":ref:`new-recipe-configuring-the-recipe`" for additional information.
1835 . See the note in section "
1836 Configuring the Recipe
1837 " for additional information.
1838 1823
1839- *Parallel build failures:* These failures manifest themselves as 1824- *Parallel build failures:* These failures manifest themselves as
1840 intermittent errors, or errors reporting that a file or directory 1825 intermittent errors, or errors reporting that a file or directory
@@ -1912,7 +1897,7 @@ the software being built:
1912 ``do_install_append`` function using the install command as described 1897 ``do_install_append`` function using the install command as described
1913 in the "Manual" bulleted item later in this list. 1898 in the "Manual" bulleted item later in this list.
1914 1899
1915- Other (using ``make install``): You need to define a ``do_install`` 1900- *Other (using* ``make install``\ *)*: You need to define a ``do_install``
1916 function in your recipe. The function should call 1901 function in your recipe. The function should call
1917 ``oe_runmake install`` and will likely need to pass in the 1902 ``oe_runmake install`` and will likely need to pass in the
1918 destination directory as well. How you pass that path is dependent on 1903 destination directory as well. How you pass that path is dependent on
@@ -1931,7 +1916,7 @@ the software being built:
1931 install the built software into the directories. 1916 install the built software into the directories.
1932 1917
1933 You can find more information on ``install`` at 1918 You can find more information on ``install`` at
1934 http://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html. 1919 https://www.gnu.org/software/coreutils/manual/html_node/install-invocation.html.
1935 1920
1936For the scenarios that do not use Autotools or CMake, you need to track 1921For the scenarios that do not use Autotools or CMake, you need to track
1937the installation and diagnose and fix any issues until everything 1922the installation and diagnose and fix any issues until everything
@@ -1960,13 +1945,15 @@ installed correctly.
1960 conditions. If you experience intermittent failures during 1945 conditions. If you experience intermittent failures during
1961 ``do_install``, you might be able to work around them by disabling 1946 ``do_install``, you might be able to work around them by disabling
1962 parallel Makefile installs by adding the following to the recipe: 1947 parallel Makefile installs by adding the following to the recipe:
1963 PARALLEL_MAKEINST = "" See 1948 ::
1964 :term:`PARALLEL_MAKEINST` 1949
1965 for additional information. 1950 PARALLEL_MAKEINST = ""
1951
1952 See :term:`PARALLEL_MAKEINST` for additional information.
1966 1953
1967 - If you need to install one or more custom CMake toolchain files 1954 - If you need to install one or more custom CMake toolchain files
1968 that are supplied by the application you are building, install the 1955 that are supplied by the application you are building, install the
1969 files to ``${D}${datadir}/cmake/`` Modules during 1956 files to ``${D}${datadir}/cmake/Modules`` during
1970 :ref:`ref-tasks-install`. 1957 :ref:`ref-tasks-install`.
1971 1958
1972.. _new-recipe-enabling-system-services: 1959.. _new-recipe-enabling-system-services:
@@ -2014,7 +2001,7 @@ different ways:
2014- *systemd:* System Management Daemon (systemd) was designed to replace 2001- *systemd:* System Management Daemon (systemd) was designed to replace
2015 SysVinit and to provide enhanced management of services. For more 2002 SysVinit and to provide enhanced management of services. For more
2016 information on systemd, see the systemd homepage at 2003 information on systemd, see the systemd homepage at
2017 http://freedesktop.org/wiki/Software/systemd/. 2004 https://freedesktop.org/wiki/Software/systemd/.
2018 2005
2019 To enable a service using systemd, your recipe needs to inherit the 2006 To enable a service using systemd, your recipe needs to inherit the
2020 :ref:`systemd <ref-classes-systemd>` class. See 2007 :ref:`systemd <ref-classes-systemd>` class. See
@@ -2118,8 +2105,7 @@ recipe has two sysroots in its work directory, one for target files
2118.. note:: 2105.. note::
2119 2106
2120 You could find the term "staging" used within the Yocto project 2107 You could find the term "staging" used within the Yocto project
2121 regarding files populating sysroots (e.g. the 2108 regarding files populating sysroots (e.g. the :term:`STAGING_DIR`
2122 STAGING_DIR
2123 variable). 2109 variable).
2124 2110
2125Recipes should never populate the sysroot directly (i.e. write files 2111Recipes should never populate the sysroot directly (i.e. write files
@@ -2196,24 +2182,26 @@ file:
2196When you use a virtual provider, you do not have to "hard code" a recipe 2182When you use a virtual provider, you do not have to "hard code" a recipe
2197name as a build dependency. You can use the 2183name as a build dependency. You can use the
2198:term:`DEPENDS` variable to state the 2184:term:`DEPENDS` variable to state the
2199build is dependent on ``virtual/kernel`` for example: DEPENDS = 2185build is dependent on ``virtual/kernel`` for example:
2200"virtual/kernel" During the build, the OpenEmbedded build system picks 2186::
2187
2188 DEPENDS = "virtual/kernel"
2189
2190During the build, the OpenEmbedded build system picks
2201the correct recipe needed for the ``virtual/kernel`` dependency based on 2191the correct recipe needed for the ``virtual/kernel`` dependency based on
2202the ``PREFERRED_PROVIDER`` variable. If you want to use the small kernel 2192the ``PREFERRED_PROVIDER`` variable. If you want to use the small kernel
2203mentioned at the beginning of this section, configure your build as 2193mentioned at the beginning of this section, configure your build as
2204follows: PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small" 2194follows:
2195::
2196
2197 PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small"
2205 2198
2206.. note:: 2199.. note::
2207 2200
2208 Any recipe that 2201 Any recipe that ``PROVIDES`` a ``virtual/*`` item that is ultimately not
2209 PROVIDES 2202 selected through ``PREFERRED_PROVIDER`` does not get built. Preventing these
2210 a 2203 recipes from building is usually the desired behavior since this mechanism's
2211 virtual/\* 2204 purpose is to select between mutually exclusive alternative providers.
2212 item that is ultimately not selected through
2213 PREFERRED_PROVIDER
2214 does not get built. Preventing these recipes from building is usually
2215 the desired behavior since this mechanism's purpose is to select
2216 between mutually exclusive alternative providers.
2217 2205
2218The following lists specific examples of virtual providers: 2206The following lists specific examples of virtual providers:
2219 2207
@@ -2271,8 +2259,8 @@ Post-Installation Scripts
2271Post-installation scripts run immediately after installing a package on 2259Post-installation scripts run immediately after installing a package on
2272the target or during image creation when a package is included in an 2260the target or during image creation when a package is included in an
2273image. To add a post-installation script to a package, add a 2261image. To add a post-installation script to a package, add a
2274``pkg_postinst_``\ PACKAGENAME\ ``()`` function to the recipe file 2262``pkg_postinst_``\ `PACKAGENAME`\ ``()`` function to the recipe file
2275(``.bb``) and replace PACKAGENAME with the name of the package you want 2263(``.bb``) and replace `PACKAGENAME` with the name of the package you want
2276to attach to the ``postinst`` script. To apply the post-installation 2264to attach to the ``postinst`` script. To apply the post-installation
2277script to the main package for the recipe, which is usually what is 2265script to the main package for the recipe, which is usually what is
2278required, specify 2266required, specify
@@ -2280,7 +2268,11 @@ required, specify
2280PACKAGENAME. 2268PACKAGENAME.
2281 2269
2282A post-installation function has the following structure: 2270A post-installation function has the following structure:
2283pkg_postinst_PACKAGENAME() { # Commands to carry out } 2271::
2272
2273 pkg_postinst_PACKAGENAME() {
2274 # Commands to carry out
2275 }
2284 2276
2285The script defined in the post-installation function is called when the 2277The script defined in the post-installation function is called when the
2286root filesystem is created. If the script succeeds, the package is 2278root filesystem is created. If the script succeeds, the package is
@@ -2315,19 +2307,11 @@ script to first boot is undesirable and for read-only rootfs impossible.
2315.. note:: 2307.. note::
2316 2308
2317 Equivalent support for pre-install, pre-uninstall, and post-uninstall 2309 Equivalent support for pre-install, pre-uninstall, and post-uninstall
2318 scripts exist by way of 2310 scripts exist by way of ``pkg_preinst``, ``pkg_prerm``, and ``pkg_postrm``,
2319 pkg_preinst 2311 respectively. These scrips work in exactly the same way as does
2320 , 2312 ``pkg_postinst`` with the exception that they run at different times. Also,
2321 pkg_prerm 2313 because of when they run, they are not applicable to being run at image
2322 , and 2314 creation time like ``pkg_postinst``.
2323 pkg_postrm
2324 , respectively. These scrips work in exactly the same way as does
2325 pkg_postinst
2326 with the exception that they run at different times. Also, because of
2327 when they run, they are not applicable to being run at image creation
2328 time like
2329 pkg_postinst
2330 .
2331 2315
2332.. _new-recipe-testing: 2316.. _new-recipe-testing:
2333 2317
@@ -2424,9 +2408,9 @@ Following is one example: (``hello_2.3.bb``)
2424 inherit autotools gettext 2408 inherit autotools gettext
2425 2409
2426The variable ``LIC_FILES_CHKSUM`` is used to track source license 2410The variable ``LIC_FILES_CHKSUM`` is used to track source license
2427changes as described in the "`Tracking License 2411changes as described in the
2428Changes <#usingpoky-configuring-LIC_FILES_CHKSUM>`__" section in the 2412":ref:`dev-manual/dev-manual-common-tasks:tracking license changes`" section in
2429Yocto Project Overview and Concepts Manual. You can quickly create 2413the Yocto Project Overview and Concepts Manual. You can quickly create
2430Autotool-based recipes in a manner similar to the previous example. 2414Autotool-based recipes in a manner similar to the previous example.
2431 2415
2432.. _new-recipe-makefile-based-package: 2416.. _new-recipe-makefile-based-package:
@@ -2463,22 +2447,31 @@ In the following example, ``mtd-utils`` is a makefile-based package:
2463 LICENSE = "GPLv2+" 2447 LICENSE = "GPLv2+"
2464 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ 2448 LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
2465 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" 2449 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
2450
2466 # Use the latest version at 26 Oct, 2013 2451 # Use the latest version at 26 Oct, 2013
2467 SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b" 2452 SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b"
2468 SRC_URI = "git://git.infradead.org/mtd-utils.git \ 2453 SRC_URI = "git://git.infradead.org/mtd-utils.git \
2469 file://add-exclusion-to-mkfs-jffs2-git-2.patch \ 2454 file://add-exclusion-to-mkfs-jffs2-git-2.patch \
2470 " 2455 "
2456
2471 PV = "1.5.1+git${SRCPV}" 2457 PV = "1.5.1+git${SRCPV}"
2458
2472 S = "${WORKDIR}/git" 2459 S = "${WORKDIR}/git"
2460
2473 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" 2461 EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
2462
2474 do_install () { 2463 do_install () {
2475 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir} 2464 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir}
2476 } 2465 }
2466
2477 PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc" 2467 PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc"
2468
2478 FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool" 2469 FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool"
2479 FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*" 2470 FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*"
2480 FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image" 2471 FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image"
2472
2481 PARALLEL_MAKE = "" 2473 PARALLEL_MAKE = ""
2474
2482 BBCLASSEXTEND = "native" 2475 BBCLASSEXTEND = "native"
2483 2476
2484Splitting an Application into Multiple Packages 2477Splitting an Application into Multiple Packages
@@ -2494,12 +2487,15 @@ into separate packages:
2494:: 2487::
2495 2488
2496 require xorg-lib-common.inc 2489 require xorg-lib-common.inc
2490
2497 SUMMARY = "Xpm: X Pixmap extension library" 2491 SUMMARY = "Xpm: X Pixmap extension library"
2498 LICENSE = "BSD" 2492 LICENSE = "BSD"
2499 LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" 2493 LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7"
2500 DEPENDS += "libxext libsm libxt" 2494 DEPENDS += "libxext libsm libxt"
2501 PE = "1" 2495 PE = "1"
2496
2502 XORG_PN = "libXpm" 2497 XORG_PN = "libXpm"
2498
2503 PACKAGES =+ "sxpm cxpm" 2499 PACKAGES =+ "sxpm cxpm"
2504 FILES_cxpm = "${bindir}/cxpm" 2500 FILES_cxpm = "${bindir}/cxpm"
2505 FILES_sxpm = "${bindir}/sxpm" 2501 FILES_sxpm = "${bindir}/sxpm"
@@ -2610,8 +2606,7 @@ Following Recipe Style Guidelines
2610--------------------------------- 2606---------------------------------
2611 2607
2612When writing recipes, it is good to conform to existing style 2608When writing recipes, it is good to conform to existing style
2613guidelines. The `OpenEmbedded 2609guidelines. The :oe_home:`OpenEmbedded Styleguide </wiki/Styleguide>` wiki page
2614Styleguide <http://www.openembedded.org/wiki/Styleguide>`__ wiki page
2615provides rough guidelines for preferred recipe style. 2610provides rough guidelines for preferred recipe style.
2616 2611
2617It is common for existing recipes to deviate a bit from this style. 2612It is common for existing recipes to deviate a bit from this style.
@@ -2691,7 +2686,7 @@ syntax, you can reference the
2691:doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata` chapter 2686:doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata` chapter
2692in the BitBake User Manual. 2687in the BitBake User Manual.
2693 2688
2694- *Line Continuation (\):* Use the backward slash (``\``) character to 2689- *Line Continuation (\\):* Use the backward slash (``\``) character to
2695 split a statement over multiple lines. Place the slash character at 2690 split a statement over multiple lines. Place the slash character at
2696 the end of the line that is to be continued on the next line: 2691 the end of the line that is to be continued on the next line:
2697 :: 2692 ::
@@ -2741,8 +2736,12 @@ in the BitBake User Manual.
2741 2736
2742 Here is an example where ``VAR1`` is set to "New value" if it is 2737 Here is an example where ``VAR1`` is set to "New value" if it is
2743 currently empty. However, if ``VAR1`` has already been set, it 2738 currently empty. However, if ``VAR1`` has already been set, it
2744 remains unchanged: VAR1 ?= "New value" In this next example, ``VAR1`` 2739 remains unchanged:
2745 is left with the value "Original value": 2740 ::
2741
2742 VAR1 ?= "New value"
2743
2744 In this next example, ``VAR1`` is left with the value "Original value":
2746 :: 2745 ::
2747 2746
2748 VAR1 = "Original value" 2747 VAR1 = "Original value"
@@ -2834,7 +2833,7 @@ in the BitBake User Manual.
2834 specific to individual packages produced by a recipe, you should 2833 specific to individual packages produced by a recipe, you should
2835 always use an override that specifies the name of the package. 2834 always use an override that specifies the name of the package.
2836 2835
2837- *Indentation:* Use spaces for indentation rather than than tabs. For 2836- *Indentation:* Use spaces for indentation rather than tabs. For
2838 shell functions, both currently work. However, it is a policy 2837 shell functions, both currently work. However, it is a policy
2839 decision of the Yocto Project to use tabs in shell functions. Realize 2838 decision of the Yocto Project to use tabs in shell functions. Realize
2840 that some layers have a policy to use spaces for all indentation. 2839 that some layers have a policy to use spaces for all indentation.
@@ -2870,8 +2869,7 @@ that the Yocto Project already supports.
2870.. note:: 2869.. note::
2871 2870
2872 Although well within the capabilities of the Yocto Project, adding a 2871 Although well within the capabilities of the Yocto Project, adding a
2873 totally new architecture might require changes to 2872 totally new architecture might require changes to ``gcc``/``glibc``
2874 gcc/glibc
2875 and to the site information, which is beyond the scope of this 2873 and to the site information, which is beyond the scope of this
2876 manual. 2874 manual.
2877 2875
@@ -3026,9 +3024,8 @@ commit messages in the layer's tree for the changes made to recipes.
3026.. note:: 3024.. note::
3027 3025
3028 Conditions do exist when you should not use AUH to upgrade recipes 3026 Conditions do exist when you should not use AUH to upgrade recipes
3029 and you should instead use either 3027 and you should instead use either ``devtool upgrade`` or upgrade your
3030 devtool upgrade 3028 recipes manually:
3031 or upgrade your recipes manually:
3032 3029
3033 - When AUH cannot complete the upgrade sequence. This situation 3030 - When AUH cannot complete the upgrade sequence. This situation
3034 usually results because custom patches carried by the recipe 3031 usually results because custom patches carried by the recipe
@@ -3043,13 +3040,14 @@ The following steps describe how to set up the AUH utility:
3043 3040
30441. *Be Sure the Development Host is Set Up:* You need to be sure that 30411. *Be Sure the Development Host is Set Up:* You need to be sure that
3045 your development host is set up to use the Yocto Project. For 3042 your development host is set up to use the Yocto Project. For
3046 information on how to set up your host, see the "`Preparing the Build 3043 information on how to set up your host, see the
3047 Host <#dev-preparing-the-build-host>`__" section. 3044 ":ref:`dev-preparing-the-build-host`" section.
3048 3045
30492. *Make Sure Git is Configured:* The AUH utility requires Git to be 30462. *Make Sure Git is Configured:* The AUH utility requires Git to be
3050 configured because AUH uses Git to save upgrades. Thus, you must have 3047 configured because AUH uses Git to save upgrades. Thus, you must have
3051 Git user and email configured. The following command shows your 3048 Git user and email configured. The following command shows your
3052 configurations: 3049 configurations:
3050 ::
3053 3051
3054 $ git config --list 3052 $ git config --list
3055 3053
@@ -3083,11 +3081,11 @@ The following steps describe how to set up the AUH utility:
3083 :: 3081 ::
3084 3082
3085 $ cd ~/poky 3083 $ cd ~/poky
3086 $ source oe-init-build-env 3084 $ source oe-init-build-env your_AUH_build_directory
3087 3085
3088 your_AUH_build_directory Re-using an existing build directory and its 3086 Re-using an existing build directory and its configurations is not
3089 configurations is not recommended as existing settings could cause 3087 recommended as existing settings could cause AUH to fail or behave
3090 AUH to fail or behave undesirably. 3088 undesirably.
3091 3089
30925. *Make Configurations in Your Local Configuration File:* Several 30905. *Make Configurations in Your Local Configuration File:* Several
3093 settings need to exist in the ``local.conf`` file in the build 3091 settings need to exist in the ``local.conf`` file in the build
@@ -3111,14 +3109,15 @@ The following steps describe how to set up the AUH utility:
3111 - If you want to enable testing through the 3109 - If you want to enable testing through the
3112 :ref:`testimage <ref-classes-testimage*>` 3110 :ref:`testimage <ref-classes-testimage*>`
3113 class, which is optional, you need to have the following set in 3111 class, which is optional, you need to have the following set in
3114 your ``conf/local.conf`` file: INHERIT += "testimage" 3112 your ``conf/local.conf`` file:
3113 ::
3114
3115 INHERIT += "testimage"
3115 3116
3116 .. note:: 3117 .. note::
3117 3118
3118 If your distro does not enable by default ptest, which Poky 3119 If your distro does not enable by default ptest, which Poky
3119 does, you need the following in your 3120 does, you need the following in your ``local.conf`` file:
3120 local.conf
3121 file:
3122 :: 3121 ::
3123 3122
3124 DISTRO_FEATURES_append = " ptest" 3123 DISTRO_FEATURES_append = " ptest"
@@ -3133,9 +3132,8 @@ The following steps describe how to set up the AUH utility:
3133 3132
31347. *Create and Edit an AUH Configuration File:* You need to have the 31337. *Create and Edit an AUH Configuration File:* You need to have the
3135 ``upgrade-helper/upgrade-helper.conf`` configuration file in your 3134 ``upgrade-helper/upgrade-helper.conf`` configuration file in your
3136 build directory. You can find a sample configuration file in the `AUH 3135 build directory. You can find a sample configuration file in the
3137 source 3136 :yocto_git:`AUH source repository </cgit/cgit.cgi/auto-upgrade-helper/tree/>`.
3138 repository <http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/>`__.
3139 3137
3140 Read through the sample file and make configurations as needed. For 3138 Read through the sample file and make configurations as needed. For
3141 example, if you enabled build history in your ``local.conf`` as 3139 example, if you enabled build history in your ``local.conf`` as
@@ -3151,16 +3149,23 @@ The following steps describe how to set up the AUH utility:
3151This next set of examples describes how to use the AUH: 3149This next set of examples describes how to use the AUH:
3152 3150
3153- *Upgrading a Specific Recipe:* To upgrade a specific recipe, use the 3151- *Upgrading a Specific Recipe:* To upgrade a specific recipe, use the
3154 following form: $ upgrade-helper.py recipe_name For example, this 3152 following form:
3155 command upgrades the ``xmodmap`` recipe: 3153 ::
3154
3155 $ upgrade-helper.py recipe_name
3156
3157 For example, this command upgrades the ``xmodmap`` recipe:
3156 :: 3158 ::
3157 3159
3158 $ upgrade-helper.py xmodmap 3160 $ upgrade-helper.py xmodmap
3159 3161
3160- *Upgrading a Specific Recipe to a Particular Version:* To upgrade a 3162- *Upgrading a Specific Recipe to a Particular Version:* To upgrade a
3161 specific recipe to a particular version, use the following form: $ 3163 specific recipe to a particular version, use the following form:
3162 upgrade-helper.py recipe_name -t version For example, this command 3164 ::
3163 upgrades the ``xmodmap`` recipe to version 1.2.3: 3165
3166 $ upgrade-helper.py recipe_name -t version
3167
3168 For example, this command upgrades the ``xmodmap`` recipe to version 1.2.3:
3164 :: 3169 ::
3165 3170
3166 $ upgrade-helper.py xmodmap -t 1.2.3 3171 $ upgrade-helper.py xmodmap -t 1.2.3
@@ -3192,7 +3197,7 @@ the layer tree.
3192 3197
3193You can easily set up to run the AUH utility on a regular basis by using 3198You can easily set up to run the AUH utility on a regular basis by using
3194a cron job. See the 3199a cron job. See the
3195`weeklyjob.sh <http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh>`_ 3200:yocto_git:`weeklyjob.sh </cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh>`
3196file distributed with the utility for an example. 3201file distributed with the utility for an example.
3197 3202
3198.. _gs-using-devtool-upgrade: 3203.. _gs-using-devtool-upgrade:
@@ -3232,15 +3237,12 @@ patches contained by the recipe as needed.
3232 3237
3233.. note:: 3238.. note::
3234 3239
3235 AUH uses much of 3240 AUH uses much of ``devtool upgrade`` behind the scenes making AUH somewhat
3236 devtool upgrade 3241 of a "wrapper" application for ``devtool upgrade``.
3237 behind the scenes making AUH somewhat of a "wrapper" application for
3238 devtool upgrade
3239 .
3240 3242
3241A typical scenario involves having used Git to clone an upstream 3243A typical scenario involves having used Git to clone an upstream
3242repository that you use during build operations. Because you are (or 3244repository that you use during build operations. Because you have built the
3243have) built the recipe in the past, the layer is likely added to your 3245recipe in the past, the layer is likely added to your
3244configuration already. If for some reason, the layer is not added, you 3246configuration already. If for some reason, the layer is not added, you
3245could add it easily using the 3247could add it easily using the
3246":ref:`bitbake-layers <bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script>`" 3248":ref:`bitbake-layers <bsp-guide/bsp:creating a new bsp layer using the \`\`bitbake-layers\`\` script>`"
@@ -3272,11 +3274,8 @@ directory automatically upgrades the recipe for you:
3272 3274
3273.. note:: 3275.. note::
3274 3276
3275 Using the 3277 Using the ``-V`` option is not necessary. Omitting the version number causes
3276 -V 3278 ``devtool upgrade`` to upgrade the recipe to the most recent version.
3277 option is not necessary. Omitting the version number causes
3278 devtool upgrade
3279 to upgrade the recipe to the most recent version.
3280 3279
3281:: 3280::
3282 3281
@@ -3349,19 +3348,16 @@ source directory in a sub-directory named ``nano`` in this case.
3349Manually Upgrading a Recipe 3348Manually Upgrading a Recipe
3350--------------------------- 3349---------------------------
3351 3350
3352If for some reason you choose not to upgrade recipes using the `Auto 3351If for some reason you choose not to upgrade recipes using
3353Upgrade Helper (AUH) <#gs-using-the-auto-upgrade-helper>`__ or by using 3352:ref:`gs-using-the-auto-upgrade-helper` or by :ref:`gs-using-devtool-upgrade`,
3354```devtool upgrade`` <#gs-using-devtool-upgrade>`__, you can manually 3353you can manually edit the recipe files to upgrade the versions.
3355edit the recipe files to upgrade the versions.
3356 3354
3357.. note:: 3355.. note::
3358 3356
3359 Manually updating multiple recipes scales poorly and involves many 3357 Manually updating multiple recipes scales poorly and involves many
3360 steps. The recommendation to upgrade recipe versions is through AUH 3358 steps. The recommendation to upgrade recipe versions is through AUH
3361 or 3359 or ``devtool upgrade``, both of which automate some steps and provide
3362 devtool upgrade 3360 guidance for others needed for the manual process.
3363 , both of which automate some steps and provide guidance for others
3364 needed for the manual process.
3365 3361
3366To manually upgrade recipe versions, follow these general steps: 3362To manually upgrade recipe versions, follow these general steps:
3367 3363
@@ -3370,7 +3366,7 @@ To manually upgrade recipe versions, follow these general steps:
3370 changes appropriately. If the version is not part of the recipe name, 3366 changes appropriately. If the version is not part of the recipe name,
3371 change the value as it is set for ``PV`` within the recipe itself. 3367 change the value as it is set for ``PV`` within the recipe itself.
3372 3368
33732. Update ``SRCREV`` if Needed: If the source code your recipe builds 33692. *Update* ``SRCREV`` *if Needed*: If the source code your recipe builds
3374 is fetched from Git or some other version control system, update 3370 is fetched from Git or some other version control system, update
3375 :term:`SRCREV` to point to the 3371 :term:`SRCREV` to point to the
3376 commit hash that matches the new version. 3372 commit hash that matches the new version.
@@ -3446,10 +3442,8 @@ usually set ``S`` to ``${WORKDIR}/git``.
3446 3442
3447.. note:: 3443.. note::
3448 3444
3449 The 3445 The :term:`BP` represents the base recipe name, which consists of the name
3450 BP 3446 and version:
3451 represents the base recipe name, which consists of the name and
3452 version:
3453 :: 3447 ::
3454 3448
3455 BP = "${BPN}-${PV}" 3449 BP = "${BPN}-${PV}"
@@ -3458,8 +3452,11 @@ usually set ``S`` to ``${WORKDIR}/git``.
3458The path to the work directory for the recipe 3452The path to the work directory for the recipe
3459(:term:`WORKDIR`) is defined as 3453(:term:`WORKDIR`) is defined as
3460follows: 3454follows:
3461${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} The 3455::
3462actual directory depends on several things: 3456
3457 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
3458
3459The actual directory depends on several things:
3463 3460
3464- :term:`TMPDIR`: The top-level build 3461- :term:`TMPDIR`: The top-level build
3465 output directory. 3462 output directory.
@@ -3491,7 +3488,7 @@ build system uses to build the package would be as follows:
3491Using Quilt in Your Workflow 3488Using Quilt in Your Workflow
3492============================ 3489============================
3493 3490
3494`Quilt <http://savannah.nongnu.org/projects/quilt>`__ is a powerful tool 3491`Quilt <https://savannah.nongnu.org/projects/quilt>`__ is a powerful tool
3495that allows you to capture source code changes without having a clean 3492that allows you to capture source code changes without having a clean
3496source tree. This section outlines the typical workflow you can use to 3493source tree. This section outlines the typical workflow you can use to
3497modify source code, test changes, and then preserve the changes in the 3494modify source code, test changes, and then preserve the changes in the
@@ -3500,11 +3497,8 @@ form of a patch all using Quilt.
3500.. note:: 3497.. note::
3501 3498
3502 With regard to preserving changes to source files, if you clean a 3499 With regard to preserving changes to source files, if you clean a
3503 recipe or have 3500 recipe or have ``rm_work`` enabled, the
3504 rm_work 3501 :ref:`devtool workflow <sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow>`
3505 enabled, the
3506 devtool
3507 workflow
3508 as described in the Yocto Project Application Development and the 3502 as described in the Yocto Project Application Development and the
3509 Extensible Software Development Kit (eSDK) manual is a safer 3503 Extensible Software Development Kit (eSDK) manual is a safer
3510 development flow than the flow that uses Quilt. 3504 development flow than the flow that uses Quilt.
@@ -3526,7 +3520,7 @@ Follow these general steps:
35263. *Create a New Patch:* Before modifying source code, you need to 35203. *Create a New Patch:* Before modifying source code, you need to
3527 create a new patch. To create a new patch file, use ``quilt new`` as 3521 create a new patch. To create a new patch file, use ``quilt new`` as
3528 below: 3522 below:
3529 :; 3523 ::
3530 3524
3531 $ quilt new my_changes.patch 3525 $ quilt new my_changes.patch
3532 3526
@@ -3553,22 +3547,13 @@ Follow these general steps:
3553 3547
3554 .. note:: 3548 .. note::
3555 3549
3556 All the modifications you make to the temporary source code 3550 All the modifications you make to the temporary source code disappear
3557 disappear once you run the 3551 once you run the ``do_clean`` or ``do_cleanall`` tasks using BitBake
3558 do_clean 3552 (i.e. ``bitbake -c clean package`` and ``bitbake -c cleanall package``).
3559 or 3553 Modifications will also disappear if you use the ``rm_work`` feature as
3560 do_cleanall 3554 described in the
3561 tasks using BitBake (i.e. 3555 ":ref:`dev-manual/dev-manual-common-tasks:conserving disk space during builds`"
3562 bitbake -c clean 3556 section.
3563 package
3564 and
3565 bitbake -c cleanall
3566 package
3567 ). Modifications will also disappear if you use the
3568 rm_work
3569 feature as described in the "
3570 Conserving Disk Space During Builds
3571 " section.
3572 3557
35737. *Generate the Patch:* Once your changes work as expected, you need to 35587. *Generate the Patch:* Once your changes work as expected, you need to
3574 use Quilt to generate the final patch that contains all your 3559 use Quilt to generate the final patch that contains all your
@@ -3640,7 +3625,7 @@ Directory (:term:`S`).
3640To manually run a specific task using ``devshell``, run the 3625To manually run a specific task using ``devshell``, run the
3641corresponding ``run.*`` script in the 3626corresponding ``run.*`` script in the
3642``${``\ :term:`WORKDIR`\ ``}/temp`` 3627``${``\ :term:`WORKDIR`\ ``}/temp``
3643directory (e.g., ``run.do_configure.``\ pid). If a task's script does 3628directory (e.g., ``run.do_configure.``\ `pid`). If a task's script does
3644not exist, which would be the case if the task was skipped by way of the 3629not exist, which would be the case if the task was skipped by way of the
3645sstate cache, you can create the task by first running it outside of the 3630sstate cache, you can create the task by first running it outside of the
3646``devshell``: 3631``devshell``:
@@ -3775,8 +3760,7 @@ The following figure and list overviews the build process:
3775 :align: center 3760 :align: center
3776 3761
37771. *Set up Your Host Development System to Support Development Using the 37621. *Set up Your Host Development System to Support Development Using the
3778 Yocto Project*: See the "`Setting Up to Use the Yocto 3763 Yocto Project*: See the ":doc:`dev-manual-start`" section for options on how to get a
3779 Project <#dev-manual-start>`__" section for options on how to get a
3780 build host ready to use the Yocto Project. 3764 build host ready to use the Yocto Project.
3781 3765
37822. *Initialize the Build Environment:* Initialize the build environment 37662. *Initialize the Build Environment:* Initialize the build environment
@@ -3787,24 +3771,17 @@ The following figure and list overviews the build process:
3787 $ source oe-init-build-env [build_dir] 3771 $ source oe-init-build-env [build_dir]
3788 3772
3789 When you use the initialization script, the OpenEmbedded build system 3773 When you use the initialization script, the OpenEmbedded build system
3790 uses ``build`` as the default Build Directory in your current work 3774 uses ``build`` as the default :term:`Build Directory` in your current work
3791 directory. You can use a build_dir argument with the script to 3775 directory. You can use a `build_dir` argument with the script to
3792 specify a different build directory. 3776 specify a different build directory.
3793 3777
3794 .. note:: 3778 .. note::
3795 3779
3796 A common practice is to use a different Build Directory for 3780 A common practice is to use a different Build Directory for
3797 different targets. For example, 3781 different targets. For example, ``~/build/x86`` for a ``qemux86``
3798 ~/build/x86 3782 target, and ``~/build/arm`` for a ``qemuarm`` target.
3799 for a 3783
3800 qemux86 37843. *Make Sure Your* ``local.conf`` *File is Correct*: Ensure the
3801 target, and
3802 ~/build/arm
3803 for a
3804 qemuarm
3805 target.
3806
38073. Make Sure Your ``local.conf`` File is Correct: Ensure the
3808 ``conf/local.conf`` configuration file, which is found in the Build 3785 ``conf/local.conf`` configuration file, which is found in the Build
3809 Directory, is set up how you want it. This file defines many aspects 3786 Directory, is set up how you want it. This file defines many aspects
3810 of the build environment including the target machine architecture 3787 of the build environment including the target machine architecture
@@ -3821,9 +3798,7 @@ The following figure and list overviews the build process:
3821 3798
3822 .. note:: 3799 .. note::
3823 3800
3824 For information on BitBake, see the 3801 For information on BitBake, see the :doc:`bitbake:index`.
3825 BitBake User Manual
3826 .
3827 3802
3828 The target is the name of the recipe you want to build. Common 3803 The target is the name of the recipe you want to build. Common
3829 targets are the images in ``meta/recipes-core/images``, 3804 targets are the images in ``meta/recipes-core/images``,
@@ -3928,8 +3903,7 @@ Follow these steps to set up and execute multiple configuration builds:
3928 3903
3929 A "default" configuration already exists by definition. This 3904 A "default" configuration already exists by definition. This
3930 configuration is named: "" (i.e. empty string) and is defined by 3905 configuration is named: "" (i.e. empty string) and is defined by
3931 the variables coming from your 3906 the variables coming from your ``local.conf``
3932 local.conf
3933 file. Consequently, the previous example actually adds two 3907 file. Consequently, the previous example actually adds two
3934 additional configurations to your build: "arm" and "x86" along 3908 additional configurations to your build: "arm" and "x86" along
3935 with "". 3909 with "".
@@ -3953,11 +3927,10 @@ Follow these steps to set up and execute multiple configuration builds:
3953 3927
3954.. note:: 3928.. note::
3955 3929
3956 Support for multiple configuration builds in the Yocto Project DISTRO 3930 Support for multiple configuration builds in the Yocto Project &DISTRO;
3957 (DISTRO_NAME) Release does not include Shared State (sstate) 3931 (&DISTRO_NAME;) Release does not include Shared State (sstate)
3958 optimizations. Consequently, if a build uses the same object twice 3932 optimizations. Consequently, if a build uses the same object twice
3959 in, for example, two different 3933 in, for example, two different ``TMPDIR``
3960 TMPDIR
3961 directories, the build either loads from an existing sstate cache for 3934 directories, the build either loads from an existing sstate cache for
3962 that build at the start or builds the object fresh. 3935 that build at the start or builds the object fresh.
3963 3936
@@ -3990,7 +3963,7 @@ to be added to the recipe that builds the ``core-image-sato`` image:
3990 3963
3991 do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" 3964 do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs"
3992 3965
3993In this example, the from_multiconfig is "x86". The to_multiconfig is "arm". The 3966In this example, the `from_multiconfig` is "x86". The `to_multiconfig` is "arm". The
3994task on which the ``do_image`` task in the recipe depends is the 3967task on which the ``do_image`` task in the recipe depends is the
3995``do_rootfs`` task from the ``core-image-minimal`` recipe associated 3968``do_rootfs`` task from the ``core-image-minimal`` recipe associated
3996with the "arm" multiconfig. 3969with the "arm" multiconfig.
@@ -4074,16 +4047,10 @@ Follow these steps to create an initramfs image:
4074 4047
4075 If you choose to not bundle the initramfs image with the kernel 4048 If you choose to not bundle the initramfs image with the kernel
4076 image, you are essentially using an 4049 image, you are essentially using an
4077 Initial RAM Disk (initrd) 4050 `Initial RAM Disk (initrd) <https://en.wikipedia.org/wiki/Initrd>`__.
4078 . Creating an initrd is handled primarily through the 4051 Creating an initrd is handled primarily through the :term:`INITRD_IMAGE`,
4079 INITRD_IMAGE 4052 ``INITRD_LIVE``, and ``INITRD_IMAGE_LIVE`` variables. For more
4080 , 4053 information, see the :ref:`ref-classes-image-live` file.
4081 INITRD_LIVE
4082 , and
4083 INITRD_IMAGE_LIVE
4084 variables. For more information, see the
4085 image-live.bbclass
4086 file.
4087 4054
40883. *Optionally Add Items to the initramfs Image Through the initramfs 40553. *Optionally Add Items to the initramfs Image Through the initramfs
4089 Image Recipe:* If you add items to the initramfs image by way of its 4056 Image Recipe:* If you add items to the initramfs image by way of its
@@ -4182,15 +4149,10 @@ your own distribution that are likely modeled after ``poky-tiny``.
4182 4149
4183.. note:: 4150.. note::
4184 4151
4185 To use 4152 To use ``poky-tiny`` in your build, set the ``DISTRO`` variable in your
4186 poky-tiny 4153 ``local.conf`` file to "poky-tiny" as described in the
4187 in your build, set the 4154 ":ref:`dev-manual/dev-manual-common-tasks:creating your own distribution`"
4188 DISTRO 4155 section.
4189 variable in your
4190 local.conf
4191 file to "poky-tiny" as described in the "
4192 Creating Your Own Distribution
4193 " section.
4194 4156
4195Understanding some memory concepts will help you reduce the system size. 4157Understanding some memory concepts will help you reduce the system size.
4196Memory consists of static, dynamic, and temporary memory. Static memory 4158Memory consists of static, dynamic, and temporary memory. Static memory
@@ -4444,17 +4406,10 @@ your tunings to best consider build times and package feed maintenance.
4444 4406
4445 .. note:: 4407 .. note::
4446 4408
4447 If 4409 If :term:`DISTRO` settings change or fundamental configuration settings
4448 DISTRO 4410 such as the filesystem layout, you need to work with a clean ``TMPDIR``.
4449 settings change or fundamental configuration settings such as the 4411 Sharing ``TMPDIR`` under these circumstances might work but since it is
4450 filesystem layout, you need to work with a clean 4412 not guaranteed, you should use a clean ``TMPDIR``.
4451 TMPDIR
4452 . Sharing
4453 TMPDIR
4454 under these circumstances might work but since it is not
4455 guaranteed, you should use a clean
4456 TMPDIR
4457 .
4458 4413
4459- *Enable the Appropriate Package Architecture:* By default, the 4414- *Enable the Appropriate Package Architecture:* By default, the
4460 OpenEmbedded build system enables three levels of package 4415 OpenEmbedded build system enables three levels of package
@@ -4552,7 +4507,7 @@ your tunings to best consider build times and package feed maintenance.
4552 For such cases, you can use some tools to help you sort out the 4507 For such cases, you can use some tools to help you sort out the
4553 situation: 4508 situation:
4554 4509
4555 - *sstate-diff-machines.sh:* You can find this tool in the 4510 - ``state-diff-machines.sh``*:* You can find this tool in the
4556 ``scripts`` directory of the Source Repositories. See the comments 4511 ``scripts`` directory of the Source Repositories. See the comments
4557 in the script for information on how to use the tool. 4512 in the script for information on how to use the tool.
4558 4513
@@ -4603,8 +4558,7 @@ This next example shows how to accomplish the same thing by setting
4603.. note:: 4558.. note::
4604 4559
4605 In order for these settings to take effect, you must globally or 4560 In order for these settings to take effect, you must globally or
4606 locally inherit the 4561 locally inherit the :ref:`externalsrc <ref-classes-externalsrc>`
4607 externalsrc
4608 class. 4562 class.
4609 4563
4610By default, ``externalsrc.bbclass`` builds the source code in a 4564By default, ``externalsrc.bbclass`` builds the source code in a
@@ -4713,7 +4667,11 @@ directory:
4713 latest version of software by setting 4667 latest version of software by setting
4714 :term:`SRCREV` to 4668 :term:`SRCREV` to
4715 ``${``\ :term:`AUTOREV`\ ``}``: 4669 ``${``\ :term:`AUTOREV`\ ``}``:
4716 SRCREV = "${AUTOREV}" When a recipe sets ``SRCREV`` to 4670 ::
4671
4672 SRCREV = "${AUTOREV}"
4673
4674 When a recipe sets ``SRCREV`` to
4717 ``${AUTOREV}``, the build system accesses the network in an 4675 ``${AUTOREV}``, the build system accesses the network in an
4718 attempt to determine the latest version of software from the SCM. 4676 attempt to determine the latest version of software from the SCM.
4719 Typically, recipes that use ``AUTOREV`` are custom or modified 4677 Typically, recipes that use ``AUTOREV`` are custom or modified
@@ -4883,9 +4841,7 @@ library files.
4883.. note:: 4841.. note::
4884 4842
4885 Some previously released versions of the Yocto Project defined the 4843 Some previously released versions of the Yocto Project defined the
4886 static library files through 4844 static library files through ``${PN}-dev``.
4887 ${PN}-dev
4888 .
4889 4845
4890Following is part of the BitBake configuration file, where you can see 4846Following is part of the BitBake configuration file, where you can see
4891how the static library files are defined: 4847how the static library files are defined:
@@ -4934,7 +4890,7 @@ The build system offers the ability to build libraries with different
4934target optimizations or architecture formats and combine these together 4890target optimizations or architecture formats and combine these together
4935into one system image. You can link different binaries in the image 4891into one system image. You can link different binaries in the image
4936against the different libraries as needed for specific use cases. This 4892against the different libraries as needed for specific use cases. This
4937feature is called "Multilib." 4893feature is called "Multilib".
4938 4894
4939An example would be where you have most of a system compiled in 32-bit 4895An example would be where you have most of a system compiled in 32-bit
4940mode using 32-bit libraries, but you have something large, like a 4896mode using 32-bit libraries, but you have something large, like a
@@ -5099,13 +5055,14 @@ versioning. With properly versioned libraries, all you need to do to
5099individually specify the libraries is create separate, appropriately 5055individually specify the libraries is create separate, appropriately
5100named recipes where the :term:`PN` part of 5056named recipes where the :term:`PN` part of
5101the name includes a portion that differentiates each library version 5057the name includes a portion that differentiates each library version
5102(e.g.the major part of the version number). Thus, instead of having a 5058(e.g. the major part of the version number). Thus, instead of having a
5103single recipe that loads one version of a library (e.g. ``clutter``), 5059single recipe that loads one version of a library (e.g. ``clutter``),
5104you provide multiple recipes that result in different versions of the 5060you provide multiple recipes that result in different versions of the
5105libraries you want. As an example, the following two recipes would allow 5061libraries you want. As an example, the following two recipes would allow
5106the two separate versions of the ``clutter`` library to co-exist on the 5062the two separate versions of the ``clutter`` library to co-exist on the
5107same system: 5063same system:
5108:: 5064
5065.. code-block:: none
5109 5066
5110 clutter-1.6_1.6.20.bb 5067 clutter-1.6_1.6.20.bb
5111 clutter-1.8_1.8.4.bb 5068 clutter-1.8_1.8.4.bb
@@ -5236,11 +5193,8 @@ library package involves the following:
5236 5193
5237 .. note:: 5194 .. note::
5238 5195
5239 See recipes in the 5196 See recipes in the ``oe-core`` repository that use that
5240 oe-core 5197 ``GIR_EXTRA_LIBS_PATH`` variable as an example.
5241 repository that use that
5242 GIR_EXTRA_LIBS_PATH
5243 variable as an example.
5244 5198
52454. Look for any other errors, which probably mean that introspection 51994. Look for any other errors, which probably mean that introspection
5246 support in a package is not entirely standard, and thus breaks down 5200 support in a package is not entirely standard, and thus breaks down
@@ -5313,7 +5267,7 @@ working in an image:
5313 >>> GLib.get_host_name() 5267 >>> GLib.get_host_name()
5314 5268
53155. For something a little more advanced, enter the following see: 52695. For something a little more advanced, enter the following see:
5316 http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html 5270 https://python-gtk-3-tutorial.readthedocs.io/en/latest/introduction.html
5317 5271
5318Known Issues 5272Known Issues
5319------------ 5273------------
@@ -5360,7 +5314,7 @@ follows:
5360A good example of an external toolchain used with the Yocto Project is 5314A good example of an external toolchain used with the Yocto Project is
5361Mentor Graphics Sourcery G++ Toolchain. You can see information on how 5315Mentor Graphics Sourcery G++ Toolchain. You can see information on how
5362to use that particular layer in the ``README`` file at 5316to use that particular layer in the ``README`` file at
5363http://github.com/MentorEmbedded/meta-sourcery/. You can find 5317https://github.com/MentorEmbedded/meta-sourcery/. You can find
5364further information by reading about the 5318further information by reading about the
5365:term:`TCMODE` variable in the Yocto 5319:term:`TCMODE` variable in the Yocto
5366Project Reference Manual's variable glossary. 5320Project Reference Manual's variable glossary.
@@ -5390,11 +5344,9 @@ particular system.
5390 5344
5391.. note:: 5345.. note::
5392 5346
5393 For a kickstart file reference, see the " 5347 For a kickstart file reference, see the
5394 OpenEmbedded Kickstart ( 5348 ":ref:`ref-manual/ref-kickstart:openembedded kickstart (\`\`.wks\`\`) reference`"
5395 .wks 5349 Chapter in the Yocto Project Reference Manual.
5396 ) Reference
5397 " Chapter in the Yocto Project Reference Manual.
5398 5350
5399The ``wic`` command and the infrastructure it is based on is by 5351The ``wic`` command and the infrastructure it is based on is by
5400definition incomplete. The purpose of the command is to allow the 5352definition incomplete. The purpose of the command is to allow the
@@ -5463,7 +5415,10 @@ system needs to meet the following requirements:
5463 form generated by the OpenEmbedded build system. 5415 form generated by the OpenEmbedded build system.
5464 5416
5465- You must build several native tools, which are built to run on the 5417- You must build several native tools, which are built to run on the
5466 build system: $ bitbake parted-native dosfstools-native mtools-native 5418 build system:
5419 ::
5420
5421 $ bitbake parted-native dosfstools-native mtools-native
5467 5422
5468- Include "wic" as part of the 5423- Include "wic" as part of the
5469 :term:`IMAGE_FSTYPES` 5424 :term:`IMAGE_FSTYPES`
@@ -5721,8 +5676,7 @@ partition.
5721 5676
5722 If you use plugins that have build-time dependencies (e.g. native 5677 If you use plugins that have build-time dependencies (e.g. native
5723 tools, bootloaders, and so forth) when building a Wic image, you need 5678 tools, bootloaders, and so forth) when building a Wic image, you need
5724 to specify those dependencies using the 5679 to specify those dependencies using the :term:`WKS_FILE_DEPENDS`
5725 WKS_FILE_DEPENDS
5726 variable. 5680 variable.
5727 5681
5728Source plugins are subclasses defined in plugin files. As shipped, the 5682Source plugins are subclasses defined in plugin files. As shipped, the
@@ -5828,9 +5782,8 @@ The following list describes the methods implemented in the
5828 5782
5829 .. note:: 5783 .. note::
5830 5784
5831 get_bitbake_var() 5785 ``get_bitbake_var()`` allows you to access non-standard variables that
5832 allows you to access non-standard variables that you might want to 5786 you might want to use for this behavior.
5833 use for this behavior.
5834 5787
5835You can extend the source plugin mechanism. To add more hooks, create 5788You can extend the source plugin mechanism. To add more hooks, create
5836more source plugin methods within ``SourcePlugin`` and the corresponding 5789more source plugin methods within ``SourcePlugin`` and the corresponding
@@ -5906,12 +5859,10 @@ or ::
5906 5859
5907.. note:: 5860.. note::
5908 5861
5909 For more information on how to use the 5862 For more information on how to use the ``bmaptool``
5910 bmaptool 5863 to flash a device with an image, see the
5911 to flash a device with an image, see the " 5864 ":ref:`dev-manual/dev-manual-common-tasks:flashing images using \`\`bmaptool\`\``"
5912 Flashing Images Using 5865 section.
5913 bmaptool
5914 " section.
5915 5866
5916Using a Modified Kickstart File 5867Using a Modified Kickstart File
5917~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 5868~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -6039,9 +5990,7 @@ modify the kernel.
6039.. note:: 5990.. note::
6040 5991
6041 In order to use Wic to manipulate a Wic image as in this example, 5992 In order to use Wic to manipulate a Wic image as in this example,
6042 your development machine must have the 5993 your development machine must have the ``mtools`` package installed.
6043 mtools
6044 package installed.
6045 5994
6046The following example examines the contents of the Wic image, deletes 5995The following example examines the contents of the Wic image, deletes
6047the existing kernel, and then inserts a new kernel: 5996the existing kernel, and then inserts a new kernel:
@@ -6101,9 +6050,8 @@ the existing kernel, and then inserts a new kernel:
6101 .. note:: 6050 .. note::
6102 6051
6103 If you see the following error, you need to update or create a 6052 If you see the following error, you need to update or create a
6104 ~/.mtoolsrc 6053 ``~/.mtoolsrc`` file and be sure to have the line "mtools_skip_check=1"
6105 file and be sure to have the line "mtools_skip_check=1" in the 6054 in the file. Then, run the Wic command again:
6106 file. Then, run the Wic command again:
6107 :: 6055 ::
6108 6056
6109 ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 6057 ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0
@@ -6132,17 +6080,14 @@ the existing kernel, and then inserts a new kernel:
6132 ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz 6080 ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz
6133 6081
6134 Once the new kernel is added back into the image, you can use the 6082 Once the new kernel is added back into the image, you can use the
6135 ``dd`` command or ```bmaptool`` <#flashing-images-using-bmaptool>`__ 6083 ``dd`` command or :ref:`bmaptool
6084 <dev-manual/dev-manual-common-tasks:flashing images using \`\`bmaptool\`\`>`
6136 to flash your wic image onto an SD card or USB stick and test your 6085 to flash your wic image onto an SD card or USB stick and test your
6137 target. 6086 target.
6138 6087
6139 .. note:: 6088 .. note::
6140 6089
6141 Using 6090 Using ``bmaptool`` is generally 10 to 20 times faster than using ``dd``.
6142 bmaptool
6143 is generally 10 to 20 times faster than using
6144 dd
6145 .
6146 6091
6147Flashing Images Using ``bmaptool`` 6092Flashing Images Using ``bmaptool``
6148================================== 6093==================================
@@ -6159,11 +6104,16 @@ system image files much faster.
6159 - If you are using Ubuntu or Debian distributions, you can install 6104 - If you are using Ubuntu or Debian distributions, you can install
6160 the ``bmap-tools`` package using the following command and then 6105 the ``bmap-tools`` package using the following command and then
6161 use the tool without specifying ``PATH`` even from the root 6106 use the tool without specifying ``PATH`` even from the root
6162 account: $ sudo apt-get install bmap-tools 6107 account:
6108 ::
6109
6110 $ sudo apt-get install bmap-tools
6163 6111
6164 - If you are unable to install the ``bmap-tools`` package, you will 6112 - If you are unable to install the ``bmap-tools`` package, you will
6165 need to build Bmaptool before using it. Use the following command: 6113 need to build Bmaptool before using it. Use the following command:
6166 $ bitbake bmap-tools-native 6114 ::
6115
6116 $ bitbake bmap-tools-native
6167 6117
6168Following, is an example that shows how to flash a Wic image. Realize 6118Following, is an example that shows how to flash a Wic image. Realize
6169that while this example uses a Wic image, you can use Bmaptool to flash 6119that while this example uses a Wic image, you can use Bmaptool to flash
@@ -6347,8 +6297,7 @@ system to make your images more secure:
6347- Consider enabling a Mandatory Access Control (MAC) framework such as 6297- Consider enabling a Mandatory Access Control (MAC) framework such as
6348 SMACK or SELinux and tuning it appropriately for your device's usage. 6298 SMACK or SELinux and tuning it appropriately for your device's usage.
6349 You can find more information in the 6299 You can find more information in the
6350 `meta-selinux <http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/>`__ 6300 :yocto_git:`meta-selinux </cgit/cgit.cgi/meta-selinux/>` layer.
6351 layer.
6352 6301
6353Tools for Hardening Your Image 6302Tools for Hardening Your Image
6354------------------------------ 6303------------------------------
@@ -6388,11 +6337,8 @@ layer. The following steps provide some more detail:
6388 6337
6389 .. note:: 6338 .. note::
6390 6339
6391 The 6340 The :term:`DISTRO` variable in your ``local.conf`` file determines the
6392 DISTRO 6341 name of your distribution.
6393 variable in your
6394 local.conf
6395 file determines the name of your distribution.
6396 6342
6397 You can split out parts of your configuration file into include files 6343 You can split out parts of your configuration file into include files
6398 and then "require" them from within your distribution configuration 6344 and then "require" them from within your distribution configuration
@@ -6423,15 +6369,11 @@ layer. The following steps provide some more detail:
6423 6369
6424 If you want to base your distribution configuration file on the 6370 If you want to base your distribution configuration file on the
6425 very basic configuration from OE-Core, you can use 6371 very basic configuration from OE-Core, you can use
6426 conf/distro/defaultsetup.conf 6372 ``conf/distro/defaultsetup.conf`` as a reference and just include
6427 as a reference and just include variables that differ as compared 6373 variables that differ as compared to ``defaultsetup.conf``.
6428 to 6374 Alternatively, you can create a distribution configuration file
6429 defaultsetup.conf 6375 from scratch using the ``defaultsetup.conf`` file or configuration files
6430 . Alternatively, you can create a distribution configuration file 6376 from other distributions such as Poky or Angstrom as references.
6431 from scratch using the
6432 defaultsetup.conf
6433 file or configuration files from other distributions such as Poky
6434 or Angstrom as references.
6435 6377
6436- *Provide miscellaneous variables:* Be sure to define any other 6378- *Provide miscellaneous variables:* Be sure to define any other
6437 variables for which you want to create a default or enforce as part 6379 variables for which you want to create a default or enforce as part
@@ -6643,11 +6585,8 @@ the following:
6643 6585
6644 .. note:: 6586 .. note::
6645 6587
6646 Technically, a third component, the "epoch" (i.e. 6588 Technically, a third component, the "epoch" (i.e. :term:`PE`) is involved
6647 PE 6589 but this discussion for the most part ignores ``PE``.
6648 ) is involved but this discussion for the most part ignores
6649 PE
6650 .
6651 6590
6652 The version and revision are taken from the 6591 The version and revision are taken from the
6653 :term:`PV` and 6592 :term:`PV` and
@@ -6705,8 +6644,7 @@ revision field, which removes the human element.
6705.. note:: 6644.. note::
6706 6645
6707 For additional information on using a PR Service, you can see the 6646 For additional information on using a PR Service, you can see the
6708 PR Service 6647 :yocto_wiki:`PR Service </wiki/PR_Service>` wiki page.
6709 wiki page.
6710 6648
6711The Yocto Project uses variables in order of decreasing priority to 6649The Yocto Project uses variables in order of decreasing priority to
6712facilitate revision numbering (i.e. 6650facilitate revision numbering (i.e.
@@ -6827,7 +6765,7 @@ the ``PE`` variable (Package Epoch). The ``PE`` variable defaults to
6827 6765
6828Binary package version numbering strives to follow the `Debian Version 6766Binary package version numbering strives to follow the `Debian Version
6829Field Policy 6767Field Policy
6830Guidelines <http://www.debian.org/doc/debian-policy/ch-controlfields.html>`__. 6768Guidelines <https://www.debian.org/doc/debian-policy/ch-controlfields.html>`__.
6831These guidelines define how versions are compared and what "increasing" 6769These guidelines define how versions are compared and what "increasing"
6832a version means. 6770a version means.
6833 6771
@@ -6855,7 +6793,8 @@ code changes. Here is an example:
6855 PV = "1.0+git${SRCPV}" 6793 PV = "1.0+git${SRCPV}"
6856 6794
6857The OpenEmbedded build system substitutes ``SRCPV`` with the following: 6795The OpenEmbedded build system substitutes ``SRCPV`` with the following:
6858:: 6796
6797.. code-block:: none
6859 6798
6860 AUTOINC+source_code_revision 6799 AUTOINC+source_code_revision
6861 6800
@@ -6867,7 +6806,8 @@ with a number. The number used depends on the state of the PR Service:
6867 :term:`PR`. This behavior results in 6806 :term:`PR`. This behavior results in
6868 linearly increasing package versions, which is desirable. Here is an 6807 linearly increasing package versions, which is desirable. Here is an
6869 example: 6808 example:
6870 :: 6809
6810 .. code-block:: none
6871 6811
6872 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk 6812 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
6873 hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk 6813 hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk
@@ -6877,7 +6817,8 @@ with a number. The number used depends on the state of the PR Service:
6877 changing the package version since the source revision is included. 6817 changing the package version since the source revision is included.
6878 However, package versions are not increased linearly. Here is an 6818 However, package versions are not increased linearly. Here is an
6879 example: 6819 example:
6880 :: 6820
6821 .. code-block:: none
6881 6822
6882 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk 6823 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
6883 hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk 6824 hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk
@@ -7004,7 +6945,7 @@ optional arguments:
7004 As above 6945 As above
7005 modulename 6946 modulename
7006 The module name derived using file_regex 6947 The module name derived using file_regex
7007 extra_depends 6948 extra_depends
7008 Extra runtime dependencies (RDEPENDS) to be 6949 Extra runtime dependencies (RDEPENDS) to be
7009 set for all packages. The default value of None 6950 set for all packages. The default value of None
7010 causes a dependency on the main package 6951 causes a dependency on the main package
@@ -7269,13 +7210,10 @@ the steps in this section if you want to use runtime package management.
7269 7210
7270.. note:: 7211.. note::
7271 7212
7272 For information on the PACKAGE_FEED_* variables, see 7213 For information on the ``PACKAGE_FEED_*`` variables, see
7273 PACKAGE_FEED_ARCHS 7214 :term:`PACKAGE_FEED_ARCHS`, :term:`PACKAGE_FEED_BASE_PATHS`, and
7274 , 7215 :term:`PACKAGE_FEED_URIS` in the Yocto Project Reference Manual variables
7275 PACKAGE_FEED_BASE_PATHS 7216 glossary.
7276 , and
7277 PACKAGE_FEED_URIS
7278 in the Yocto Project Reference Manual variables glossary.
7279 7217
7280On the target, you must inform DNF that package databases are available. 7218On the target, you must inform DNF that package databases are available.
7281You do this by creating a file named 7219You do this by creating a file named
@@ -7290,14 +7228,10 @@ configuration point to the correct remote location for the feeds.
7290.. note:: 7228.. note::
7291 7229
7292 For development purposes, you can point the web server to the build 7230 For development purposes, you can point the web server to the build
7293 system's 7231 system's ``deploy`` directory. However, for production use, it is better to
7294 deploy 7232 copy the package directories to a location outside of the build area and use
7295 directory. However, for production use, it is better to copy the
7296 package directories to a location outside of the build area and use
7297 that location. Doing so avoids situations where the build system 7233 that location. Doing so avoids situations where the build system
7298 overwrites or changes the 7234 overwrites or changes the ``deploy`` directory.
7299 deploy
7300 directory.
7301 7235
7302When telling DNF where to look for the package databases, you must 7236When telling DNF where to look for the package databases, you must
7303declare individual locations per architecture or a single location used 7237declare individual locations per architecture or a single location used
@@ -7305,7 +7239,8 @@ for all architectures. You cannot do both:
7305 7239
7306- *Create an Explicit List of Architectures:* Define individual base 7240- *Create an Explicit List of Architectures:* Define individual base
7307 URLs to identify where each package database is located: 7241 URLs to identify where each package database is located:
7308 :: 7242
7243 .. code-block:: none
7309 7244
7310 [oe-packages] 7245 [oe-packages]
7311 baseurl=http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all 7246 baseurl=http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all
@@ -7327,7 +7262,8 @@ for all architectures. You cannot do both:
7327 7262
7328Once you have informed DNF where to find the package databases, you need 7263Once you have informed DNF where to find the package databases, you need
7329to fetch them: 7264to fetch them:
7330:: 7265
7266.. code-block:: none
7331 7267
7332 # dnf makecache 7268 # dnf makecache
7333 7269
@@ -7336,9 +7272,8 @@ upgrade packages from the specified repository or repositories.
7336 7272
7337.. note:: 7273.. note::
7338 7274
7339 See the 7275 See the `DNF documentation <https://dnf.readthedocs.io/en/latest/>`__ for
7340 DNF documentation 7276 additional information.
7341 for additional information.
7342 7277
7343.. _runtime-package-management-target-ipk: 7278.. _runtime-package-management-target-ipk:
7344 7279
@@ -7365,16 +7300,22 @@ directory containing the ``i586``, ``all``, and ``qemux86`` databases
7365through an HTTP server named ``my.server``. On the target, create a 7300through an HTTP server named ``my.server``. On the target, create a
7366configuration file (e.g. ``my_repo.conf``) inside the ``/etc/opkg/`` 7301configuration file (e.g. ``my_repo.conf``) inside the ``/etc/opkg/``
7367directory containing the following: 7302directory containing the following:
7368:: 7303
7304.. code-block:: none
7369 7305
7370 src/gz all http://my.server/ipk/all 7306 src/gz all http://my.server/ipk/all
7371 src/gz i586 http://my.server/ipk/i586 7307 src/gz i586 http://my.server/ipk/i586
7372 src/gz qemux86 http://my.server/ipk/qemux86 7308 src/gz qemux86 http://my.server/ipk/qemux86
7373 7309
7374Next, instruct ``opkg`` to fetch the 7310Next, instruct ``opkg`` to fetch the
7375repository information: # opkg update The ``opkg`` application is now 7311repository information:
7376able to find, install, and upgrade packages from the specified 7312
7377repository. 7313.. code-block:: none
7314
7315 # opkg update
7316
7317The ``opkg`` application is now able to find, install, and upgrade packages
7318from the specified repository.
7378 7319
7379.. _runtime-package-management-target-deb: 7320.. _runtime-package-management-target-deb:
7380 7321
@@ -7398,7 +7339,8 @@ list file (e.g. ``my_repo.list``) inside the
7398serving packages from a ``deb/`` directory containing the ``i586``, 7339serving packages from a ``deb/`` directory containing the ``i586``,
7399``all``, and ``qemux86`` databases through an HTTP server named 7340``all``, and ``qemux86`` databases through an HTTP server named
7400``my.server``. The list file should contain: 7341``my.server``. The list file should contain:
7401:: 7342
7343.. code-block:: none
7402 7344
7403 deb http://my.server/deb/all ./ 7345 deb http://my.server/deb/all ./
7404 deb http://my.server/deb/i586 ./ 7346 deb http://my.server/deb/i586 ./
@@ -7406,7 +7348,8 @@ serving packages from a ``deb/`` directory containing the ``i586``,
7406 7348
7407Next, instruct the ``apt`` application 7349Next, instruct the ``apt`` application
7408to fetch the repository information: 7350to fetch the repository information:
7409:: 7351
7352.. code-block:: none
7410 7353
7411 # apt-get update 7354 # apt-get update
7412 7355
@@ -7442,10 +7385,8 @@ file:
7442 7385
7443.. note:: 7386.. note::
7444 7387
7445 Be sure to supply appropriate values for both 7388 Be sure to supply appropriate values for both `key_name` and
7446 key_name 7389 `passphrase`.
7447 and
7448 passphrase
7449 7390
7450Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in 7391Aside from the ``RPM_GPG_NAME`` and ``RPM_GPG_PASSPHRASE`` variables in
7451the previous example, two optional variables related to signing exist: 7392the previous example, two optional variables related to signing exist:
@@ -7518,8 +7459,7 @@ see the :yocto_wiki:`Ptest </wiki/Ptest>` wiki page.
7518.. note:: 7459.. note::
7519 7460
7520 A recipe is "ptest-enabled" if it inherits the 7461 A recipe is "ptest-enabled" if it inherits the
7521 ptest 7462 :ref:`ptest <ref-classes-ptest>` class.
7522 class.
7523 7463
7524Adding ptest to Your Build 7464Adding ptest to Your Build
7525~~~~~~~~~~~~~~~~~~~~~~~~~~ 7465~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -7553,7 +7493,7 @@ you need to prepare the recipes that build the packages you want to
7553test. Here is what you have to do for each recipe: 7493test. Here is what you have to do for each recipe:
7554 7494
7555- *Be sure the recipe inherits 7495- *Be sure the recipe inherits
7556 the*\ :ref:`ptest <ref-classes-ptest>`\ *class:* 7496 the* :ref:`ptest <ref-classes-ptest>` *class:*
7557 Include the following line in each recipe: 7497 Include the following line in each recipe:
7558 :: 7498 ::
7559 7499
@@ -7621,7 +7561,7 @@ Creating Node Package Manager (NPM) Packages
7621manager for the JavaScript programming language. The Yocto Project 7561manager for the JavaScript programming language. The Yocto Project
7622supports the NPM :ref:`fetcher <bitbake:bb-fetchers>`. You can 7562supports the NPM :ref:`fetcher <bitbake:bb-fetchers>`. You can
7623use this fetcher in combination with 7563use this fetcher in combination with
7624:doc:```devtool`` <../ref-manual/ref-devtool-reference>` to create 7564:doc:`devtool <../ref-manual/ref-devtool-reference>` to create
7625recipes that produce NPM packages. 7565recipes that produce NPM packages.
7626 7566
7627Two workflows exist that allow you to create NPM packages using 7567Two workflows exist that allow you to create NPM packages using
@@ -7631,8 +7571,7 @@ method.
7631.. note:: 7571.. note::
7632 7572
7633 While it is possible to create NPM recipes manually, using 7573 While it is possible to create NPM recipes manually, using
7634 devtool 7574 ``devtool`` is far simpler.
7635 is far simpler.
7636 7575
7637Additionally, some requirements and caveats exist. 7576Additionally, some requirements and caveats exist.
7638 7577
@@ -7652,7 +7591,7 @@ NPM packages:
7652 is NPM's public registry. 7591 is NPM's public registry.
7653 7592
7654- Be familiar with 7593- Be familiar with
7655 :doc:```devtool`` <../ref-manual/ref-devtool-reference>`. 7594 :doc:`devtool <../ref-manual/ref-devtool-reference>`.
7656 7595
7657- The NPM host tools need the native ``nodejs-npm`` package, which is 7596- The NPM host tools need the native ``nodejs-npm`` package, which is
7658 part of the OpenEmbedded environment. You need to get the package by 7597 part of the OpenEmbedded environment. You need to get the package by
@@ -7682,9 +7621,7 @@ which is a file browser web application.
7682 7621
7683.. note:: 7622.. note::
7684 7623
7685 You must know the 7624 You must know the ``cute-files`` module version.
7686 cute-files
7687 module version.
7688 7625
7689The first thing you need to do is use ``devtool`` and the NPM fetcher to 7626The first thing you need to do is use ``devtool`` and the NPM fetcher to
7690create the recipe: 7627create the recipe:
@@ -7769,11 +7706,8 @@ test the application:
7769 7706
7770.. note:: 7707.. note::
7771 7708
7772 Because of a know issue, you cannot simply run 7709 Because of a known issue, you cannot simply run ``cute-files`` as you would
7773 cute-files 7710 if you had run ``npm install``.
7774 as you would if you had run
7775 npm install
7776 .
7777 7711
7778:: 7712::
7779 7713
@@ -7820,7 +7754,7 @@ the previous section. However, the ``SRC_URI`` looks like the following:
7820 " 7754 "
7821 7755
7822In this example, 7756In this example,
7823the main module is taken from the Git repository and dependents are 7757the main module is taken from the Git repository and dependencies are
7824taken from the NPM registry. Other than those differences, the recipe is 7758taken from the NPM registry. Other than those differences, the recipe is
7825basically the same between the two methods. You can build and deploy the 7759basically the same between the two methods. You can build and deploy the
7826package exactly as described in the previous section that uses the 7760package exactly as described in the previous section that uses the
@@ -7848,7 +7782,7 @@ of precedence is the same as this list:
7848 7782
7849- ``PACKAGE_ADD_METADATA`` 7783- ``PACKAGE_ADD_METADATA``
7850 7784
7851<PKGTYPE> is a parameter and expected to be a distinct name of specific 7785`<PKGTYPE>` is a parameter and expected to be a distinct name of specific
7852package type: 7786package type:
7853 7787
7854- IPK for .ipk packages 7788- IPK for .ipk packages
@@ -7857,15 +7791,17 @@ package type:
7857 7791
7858- RPM for .rpm packages 7792- RPM for .rpm packages
7859 7793
7860<PN> is a parameter and expected to be a package name. 7794`<PN>` is a parameter and expected to be a package name.
7861 7795
7862The variable can contain multiple [one-line] metadata fields separated 7796The variable can contain multiple [one-line] metadata fields separated
7863by the literal sequence '\n'. The separator can be redefined using the 7797by the literal sequence '\\n'. The separator can be redefined using the
7864variable flag ``separator``. 7798variable flag ``separator``.
7865 7799
7866The following is an example that adds two custom fields for ipk 7800The following is an example that adds two custom fields for ipk
7867packages: PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup: 7801packages:
7868Applications/Spreadsheets" 7802::
7803
7804 PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup:Applications/Spreadsheets"
7869 7805
7870Efficiently Fetching Source Files During a Build 7806Efficiently Fetching Source Files During a Build
7871================================================ 7807================================================
@@ -7947,7 +7883,7 @@ Within the system, SysVinit treats system components as services. These
7947services are maintained as shell scripts stored in the ``/etc/init.d/`` 7883services are maintained as shell scripts stored in the ``/etc/init.d/``
7948directory. Services organize into different run levels. This 7884directory. Services organize into different run levels. This
7949organization is maintained by putting links to the services in the 7885organization is maintained by putting links to the services in the
7950``/etc/rcN.d/`` directories, where N/ is one of the following options: 7886``/etc/rcN.d/`` directories, where `N/` is one of the following options:
7951"S", "0", "1", "2", "3", "4", "5", or "6". 7887"S", "0", "1", "2", "3", "4", "5", or "6".
7952 7888
7953.. note:: 7889.. note::
@@ -7962,7 +7898,7 @@ The runlevel concept in SysVinit corresponds to the concept of a target
7962in systemd, where target is also a type of supported unit. 7898in systemd, where target is also a type of supported unit.
7963 7899
7964In a SysVinit-based system, services load sequentially (i.e. one by one) 7900In a SysVinit-based system, services load sequentially (i.e. one by one)
7965during and parallelization is not supported. With systemd, services 7901during init and parallelization is not supported. With systemd, services
7966start in parallel. Needless to say, the method can have an impact on 7902start in parallel. Needless to say, the method can have an impact on
7967system startup performance. 7903system startup performance.
7968 7904
@@ -8161,10 +8097,8 @@ development source for numerous packages.
8161 8097
8162.. note:: 8098.. note::
8163 8099
8164 The 8100 The ``poky-bleeding`` distribution is not tested on a regular basis. Keep
8165 poky-bleeding 8101 this in mind if you use it.
8166 distribution is not tested on a regular basis. Keep this in mind if
8167 you use it.
8168 8102
8169Creating a Read-Only Root Filesystem 8103Creating a Read-Only Root Filesystem
8170==================================== 8104====================================
@@ -8279,14 +8213,13 @@ the information.
8279 8213
8280The remainder of this section describes the following: 8214The remainder of this section describes the following:
8281 8215
8282- How you can enable and disable build history 8216- :ref:`How you can enable and disable build history <dev-manual/dev-manual-common-tasks:enabling and disabling build history>`
8283 8217
8284- How to understand what the build history contains 8218- :ref:`How to understand what the build history contains <dev-manual/dev-manual-common-tasks:understanding what the build history contains>`
8285 8219
8286- How to limit the information used for build history 8220- :ref:`How to limit the information used for build history <dev-manual/dev-manual-common-tasks:using build history to gather image information only>`
8287 8221
8288- How to examine the build history from both a command-line and web 8222- :ref:`How to examine the build history from both a command-line and web interface <dev-manual/dev-manual-common-tasks:examining build history information>`
8289 interface
8290 8223
8291Enabling and Disabling Build History 8224Enabling and Disabling Build History
8292------------------------------------ 8225------------------------------------
@@ -8340,7 +8273,8 @@ The history for each package contains a text file that has name-value
8340pairs with information about the package. For example, 8273pairs with information about the package. For example,
8341``buildhistory/packages/i586-poky-linux/busybox/busybox/latest`` 8274``buildhistory/packages/i586-poky-linux/busybox/busybox/latest``
8342contains the following: 8275contains the following:
8343:: 8276
8277.. code-block:: none
8344 8278
8345 PV = 1.22.1 8279 PV = 1.22.1
8346 PR = r32 8280 PR = r32
@@ -8364,7 +8298,8 @@ package in bytes.
8364 8298
8365A file also exists that corresponds to the recipe from which the package 8299A file also exists that corresponds to the recipe from which the package
8366came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``): 8300came (e.g. ``buildhistory/packages/i586-poky-linux/busybox/latest``):
8367:: 8301
8302.. code-block:: none
8368 8303
8369 PV = 1.22.1 8304 PV = 1.22.1
8370 PR = r32 8305 PR = r32
@@ -8423,9 +8358,7 @@ output from this command:
8423 8358
8424.. note:: 8359.. note::
8425 8360
8426 Here are some notes on using the 8361 Here are some notes on using the ``buildhistory-collect-srcrevs`` command:
8427 buildhistory-collect-srcrevs
8428 command:
8429 8362
8430 - By default, only values where the ``SRCREV`` was not hardcoded 8363 - By default, only values where the ``SRCREV`` was not hardcoded
8431 (usually when ``AUTOREV`` is used) are reported. Use the ``-a`` 8364 (usually when ``AUTOREV`` is used) are reported. Use the ``-a``
@@ -8479,7 +8412,8 @@ The files produced for each image are as follows:
8479 even if package management is disabled for the final image. 8412 even if package management is disabled for the final image.
8480 8413
8481Here is an example of ``image-info.txt``: 8414Here is an example of ``image-info.txt``:
8482:: 8415
8416.. code-block:: none
8483 8417
8484 DISTRO = poky 8418 DISTRO = poky
8485 DISTRO_VERSION = 1.7 8419 DISTRO_VERSION = 1.7
@@ -8586,7 +8520,8 @@ The following list shows the files produced for SDKs:
8586 package filenames. 8520 package filenames.
8587 8521
8588Here is an example of ``sdk-info.txt``: 8522Here is an example of ``sdk-info.txt``:
8589:: 8523
8524.. code-block:: none
8590 8525
8591 DISTRO = poky 8526 DISTRO = poky
8592 DISTRO_VERSION = 1.3+snapshot-20130327 8527 DISTRO_VERSION = 1.3+snapshot-20130327
@@ -8643,29 +8578,19 @@ might be significant in human-readable form. Here is an example:
8643 8578
8644.. note:: 8579.. note::
8645 8580
8646 The 8581 The ``buildhistory-diff`` tool requires the ``GitPython``
8647 buildhistory-diff
8648 tool requires the
8649 GitPython
8650 package. Be sure to install it using Pip3 as follows: 8582 package. Be sure to install it using Pip3 as follows:
8651 :: 8583 ::
8652 8584
8653 $ pip3 install GitPython --user 8585 $ pip3 install GitPython --user
8654 8586
8655 8587
8656 Alternatively, you can install 8588 Alternatively, you can install ``python3-git`` using the appropriate
8657 python3-git 8589 distribution package manager (e.g. ``apt-get``, ``dnf``, or ``zipper``).
8658 using the appropriate distribution package manager (e.g.
8659 apt-get
8660 ,
8661 dnf
8662 , or
8663 zipper
8664 ).
8665 8590
8666To see changes to the build history using a web interface, follow the 8591To see changes to the build history using a web interface, follow the
8667instruction in the ``README`` file here. 8592instruction in the ``README`` file
8668http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/. 8593:yocto_git:`here </cgit/cgit.cgi/buildhistory-web/>`.
8669 8594
8670Here is a sample screenshot of the interface: 8595Here is a sample screenshot of the interface:
8671 8596
@@ -8713,9 +8638,7 @@ In order to run tests, you need to do the following:
8713 .. note:: 8638 .. note::
8714 8639
8715 On some distributions, you also need to comment out "Defaults 8640 On some distributions, you also need to comment out "Defaults
8716 requiretty" in 8641 requiretty" in ``/etc/sudoers``.
8717 /etc/sudoers
8718 .
8719 8642
8720 - Manually configure a tap interface for your system. 8643 - Manually configure a tap interface for your system.
8721 8644
@@ -8730,7 +8653,9 @@ In order to run tests, you need to do the following:
8730 8653
8731 - The package recipe ``qemu-helper-native`` is required to run 8654 - The package recipe ``qemu-helper-native`` is required to run
8732 this script. Build the package using the following command: 8655 this script. Build the package using the following command:
8733 $ bitbake qemu-helper-native 8656 ::
8657
8658 $ bitbake qemu-helper-native
8734 8659
8735- *Set the DISPLAY variable:* You need to set this variable so that 8660- *Set the DISPLAY variable:* You need to set this variable so that
8736 you have an X server available (e.g. start ``vncserver`` for a 8661 you have an X server available (e.g. start ``vncserver`` for a
@@ -8837,13 +8762,13 @@ options exist:
8837 comments at the top of the BeagleBoneTarget 8762 comments at the top of the BeagleBoneTarget
8838 ``meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py`` file. 8763 ``meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py`` file.
8839 8764
8840- *"EdgeRouterTarget":* Choose "EdgeRouterTarget" is you are deploying 8765- *"EdgeRouterTarget":* Choose "EdgeRouterTarget" if you are deploying
8841 images and running tests on the Ubiquiti Networks EdgeRouter Lite. 8766 images and running tests on the Ubiquiti Networks EdgeRouter Lite.
8842 For information on how to use these tests, see the comments at the 8767 For information on how to use these tests, see the comments at the
8843 top of the EdgeRouterTarget 8768 top of the EdgeRouterTarget
8844 ``meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py`` file. 8769 ``meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py`` file.
8845 8770
8846- *"GrubTarget":* Choose the "supports deploying images and running 8771- *"GrubTarget":* Choose "GrubTarget" if you are deploying images and running
8847 tests on any generic PC that boots using GRUB. For information on how 8772 tests on any generic PC that boots using GRUB. For information on how
8848 to use these tests, see the comments at the top of the GrubTarget 8773 to use these tests, see the comments at the top of the GrubTarget
8849 ``meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py`` file. 8774 ``meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py`` file.
@@ -8934,7 +8859,8 @@ power:
8934 8859
8935 In this example, the expect 8860 In this example, the expect
8936 script does the following: 8861 script does the following:
8937 :: 8862
8863 .. code-block:: shell
8938 8864
8939 ssh test@10.11.12.1 "pyctl nuc1 arg" 8865 ssh test@10.11.12.1 "pyctl nuc1 arg"
8940 8866
@@ -8943,12 +8869,9 @@ power:
8943 8869
8944 .. note:: 8870 .. note::
8945 8871
8946 You need to customize 8872 You need to customize ``TEST_POWERCONTROL_CMD`` and
8947 TEST_POWERCONTROL_CMD 8873 ``TEST_POWERCONTROL_EXTRA_ARGS`` for your own setup. The one requirement
8948 and 8874 is that it accepts "on", "off", and "cycle" as the last argument.
8949 TEST_POWERCONTROL_EXTRA_ARGS
8950 for your own setup. The one requirement is that it accepts "on",
8951 "off", and "cycle" as the last argument.
8952 8875
8953- When no command is defined, it connects to the device over SSH and 8876- When no command is defined, it connects to the device over SSH and
8954 uses the classic reboot command to reboot the device. Classic reboot 8877 uses the classic reboot command to reboot the device. Classic reboot
@@ -8959,7 +8882,7 @@ power:
8959 8882
8960If you have no hardware to automatically perform power control but still 8883If you have no hardware to automatically perform power control but still
8961wish to experiment with automated hardware testing, you can use the 8884wish to experiment with automated hardware testing, you can use the
8962dialog-power-control script that shows a dialog prompting you to perform 8885``dialog-power-control`` script that shows a dialog prompting you to perform
8963the required power action. This script requires either KDialog or Zenity 8886the required power action. This script requires either KDialog or Zenity
8964to be installed. To use this script, set the 8887to be installed. To use this script, set the
8965:term:`TEST_POWERCONTROL_CMD` 8888:term:`TEST_POWERCONTROL_CMD`
@@ -9050,9 +8973,7 @@ the ``local.conf`` file as normal. Be sure that tests reside in
9050.. note:: 8973.. note::
9051 8974
9052 Be sure that module names do not collide with module names used in 8975 Be sure that module names do not collide with module names used in
9053 the default set of test modules in 8976 the default set of test modules in ``meta/lib/oeqa/runtime``.
9054 meta/lib/oeqa/runtime
9055 .
9056 8977
9057You can change the set of tests run by appending or overriding 8978You can change the set of tests run by appending or overriding
9058:term:`TEST_SUITES` variable in 8979:term:`TEST_SUITES` variable in
@@ -9073,9 +8994,7 @@ handling.
9073.. note:: 8994.. note::
9074 8995
9075 Each module can have multiple classes with multiple test methods. 8996 Each module can have multiple classes with multiple test methods.
9076 And, Python 8997 And, Python ``unittest`` rules apply.
9077 unittest
9078 rules apply.
9079 8998
9080Here are some things to keep in mind when running tests: 8999Here are some things to keep in mind when running tests:
9081 9000
@@ -9089,8 +9008,12 @@ Here are some things to keep in mind when running tests:
9089 9008
9090 TEST_SUITES_append = " mytest" 9009 TEST_SUITES_append = " mytest"
9091 9010
9092- Run a specific list of tests as follows: TEST_SUITES = "test1 test2 9011- Run a specific list of tests as follows:
9093 test3" Remember, order is important. Be sure to place a test that is 9012 ::
9013
9014 TEST_SUITES = "test1 test2 test3"
9015
9016 Remember, order is important. Be sure to place a test that is
9094 dependent on another test later in the order. 9017 dependent on another test later in the order.
9095 9018
9096Exporting Tests 9019Exporting Tests
@@ -9105,7 +9028,7 @@ If your image is already built, make sure the following are set in your
9105``local.conf`` file: 9028``local.conf`` file:
9106:: 9029::
9107 9030
9108 INHERIT +="testexport" 9031 INHERIT += "testexport"
9109 TEST_TARGET_IP = "IP-address-for-the-test-target" 9032 TEST_TARGET_IP = "IP-address-for-the-test-target"
9110 TEST_SERVER_IP = "IP-address-for-the-test-server" 9033 TEST_SERVER_IP = "IP-address-for-the-test-server"
9111 9034
@@ -9130,7 +9053,7 @@ Here is a complete example that shows IP addresses and uses the
9130``core-image-sato`` image: 9053``core-image-sato`` image:
9131:: 9054::
9132 9055
9133 INHERIT +="testexport" 9056 INHERIT += "testexport"
9134 TEST_TARGET_IP = "192.168.7.2" 9057 TEST_TARGET_IP = "192.168.7.2"
9135 TEST_SERVER_IP = "192.168.7.1" 9058 TEST_SERVER_IP = "192.168.7.1"
9136 9059
@@ -9173,11 +9096,7 @@ code from ``meta/lib/oeqa/utils``, which are helper classes.
9173 9096
9174 Structure shell commands such that you rely on them and they return a 9097 Structure shell commands such that you rely on them and they return a
9175 single code for success. Be aware that sometimes you will need to 9098 single code for success. Be aware that sometimes you will need to
9176 parse the output. See the 9099 parse the output. See the ``df.py`` and ``date.py`` modules for examples.
9177 df.py
9178 and
9179 date.py
9180 modules for examples.
9181 9100
9182You will notice that all test classes inherit ``oeRuntimeTest``, which 9101You will notice that all test classes inherit ``oeRuntimeTest``, which
9183is found in ``meta/lib/oetest.py``. This base class offers some helper 9102is found in ``meta/lib/oetest.py``. This base class offers some helper
@@ -9270,10 +9189,8 @@ require an SSH connection and the target must be using the
9270 9189
9271.. note:: 9190.. note::
9272 9191
9273 This method uses 9192 This method uses ``scp`` to copy files from the host to the target, which
9274 scp 9193 causes permissions and special attributes to be lost.
9275 to copy files from the host to the target, which causes permissions
9276 and special attributes to be lost.
9277 9194
9278A JSON file is used to define the packages needed by a test. This file 9195A JSON file is used to define the packages needed by a test. This file
9279must be in the same path as the file used to define the tests. 9196must be in the same path as the file used to define the tests.
@@ -9339,9 +9256,9 @@ situations.
9339 of the console output. You can enter the commands after the build 9256 of the console output. You can enter the commands after the build
9340 completes to log error information into a common database, that can 9257 completes to log error information into a common database, that can
9341 help you figure out what might be going wrong. For information on how 9258 help you figure out what might be going wrong. For information on how
9342 to enable and use this feature, see the " 9259 to enable and use this feature, see the
9343 Using the Error Reporting Tool 9260 ":ref:`dev-manual/dev-manual-common-tasks:using the error reporting tool`"
9344 " section. 9261 section.
9345 9262
9346The following list shows the debugging topics in the remainder of this 9263The following list shows the debugging topics in the remainder of this
9347section: 9264section:
@@ -9414,18 +9331,18 @@ Viewing Logs from Failed Tasks
9414------------------------------ 9331------------------------------
9415 9332
9416You can find the log for a task in the file 9333You can find the log for a task in the file
9417``${``\ :term:`WORKDIR`\ ``}/temp/log.do_``\ taskname. 9334``${``\ :term:`WORKDIR`\ ``}/temp/log.do_``\ `taskname`.
9418For example, the log for the 9335For example, the log for the
9419:ref:`ref-tasks-compile` task of the 9336:ref:`ref-tasks-compile` task of the
9420QEMU minimal image for the x86 machine (``qemux86``) might be in 9337QEMU minimal image for the x86 machine (``qemux86``) might be in
9421``tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile``. 9338``tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile``.
9422To see the commands :term:`BitBake` ran 9339To see the commands :term:`BitBake` ran
9423to generate a log, look at the corresponding ``run.do_``\ taskname file 9340to generate a log, look at the corresponding ``run.do_``\ `taskname` file
9424in the same directory. 9341in the same directory.
9425 9342
9426``log.do_``\ taskname and ``run.do_``\ taskname are actually symbolic 9343``log.do_``\ `taskname` and ``run.do_``\ `taskname` are actually symbolic
9427links to ``log.do_``\ taskname\ ``.``\ pid and 9344links to ``log.do_``\ `taskname`\ ``.``\ `pid` and
9428``log.run_``\ taskname\ ``.``\ pid, where pid is the PID the task had 9345``log.run_``\ `taskname`\ ``.``\ `pid`, where `pid` is the PID the task had
9429when it ran. The symlinks always point to the files corresponding to the 9346when it ran. The symlinks always point to the files corresponding to the
9430most recent run. 9347most recent run.
9431 9348
@@ -9539,7 +9456,8 @@ Following are a few of the available ``oe-pkgdata-util`` subcommands.
9539 ``make-doc`` package: 9456 ``make-doc`` package:
9540 :: 9457 ::
9541 9458
9542 $ oe-pkgdata-util find-path /usr/share/man/man1/make.1 make-doc: /usr/share/man/man1/make.1 9459 $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
9460 make-doc: /usr/share/man/man1/make.1
9543 9461
9544- ``oe-pkgdata-util lookup-recipe package ...``: Lists the name 9462- ``oe-pkgdata-util lookup-recipe package ...``: Lists the name
9545 of the recipes that produce the given packages. 9463 of the recipes that produce the given packages.
@@ -9548,7 +9466,7 @@ For more information on the ``oe-pkgdata-util`` command, use the help
9548facility: 9466facility:
9549:: 9467::
9550 9468
9551 $ oe-pkgdata-util DASHDASHhelp 9469 $ oe-pkgdata-util --help
9552 $ oe-pkgdata-util subcommand --help 9470 $ oe-pkgdata-util subcommand --help
9553 9471
9554.. _dev-viewing-dependencies-between-recipes-and-tasks: 9472.. _dev-viewing-dependencies-between-recipes-and-tasks:
@@ -9569,8 +9487,8 @@ command:
9569This command writes the following files in the current directory: 9487This command writes the following files in the current directory:
9570 9488
9571- ``pn-buildlist``: A list of recipes/targets involved in building 9489- ``pn-buildlist``: A list of recipes/targets involved in building
9572 recipename. "Involved" here means that at least one task from the 9490 `recipename`. "Involved" here means that at least one task from the
9573 recipe needs to run when building recipename from scratch. Targets 9491 recipe needs to run when building `recipename` from scratch. Targets
9574 that are in 9492 that are in
9575 :term:`ASSUME_PROVIDED` 9493 :term:`ASSUME_PROVIDED`
9576 are not listed. 9494 are not listed.
@@ -9580,7 +9498,7 @@ This command writes the following files in the current directory:
9580The graphs are in 9498The graphs are in
9581`DOT <https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29>`__ 9499`DOT <https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29>`__
9582format and can be converted to images (e.g. using the ``dot`` tool from 9500format and can be converted to images (e.g. using the ``dot`` tool from
9583`Graphviz <http://www.graphviz.org/>`__). 9501`Graphviz <https://www.graphviz.org/>`__).
9584 9502
9585.. note:: 9503.. note::
9586 9504
@@ -9679,10 +9597,8 @@ BitBake has determined by doing the following:
9679 9597
9680 .. note:: 9598 .. note::
9681 9599
9682 Functions (e.g. 9600 Functions (e.g. ``base_do_fetch``) also count as variable dependencies.
9683 base_do_fetch 9601 These functions in turn depend on the variables they reference.
9684 ) also count as variable dependencies. These functions in turn
9685 depend on the variables they reference.
9686 9602
9687 The output of ``bitbake-dumpsig`` also includes the value each 9603 The output of ``bitbake-dumpsig`` also includes the value each
9688 variable had, a list of dependencies for each variable, and 9604 variable had, a list of dependencies for each variable, and
@@ -9706,10 +9622,9 @@ BitBake command-line options:
9706 9622
9707.. note:: 9623.. note::
9708 9624
9709 Two common values for 9625 Two common values for `SIGNATURE_HANDLER` are "none" and "printdiff", which
9710 SIGNATURE_HANDLER 9626 dump only the signature or compare the dumped signature with the cached one,
9711 are "none" and "printdiff", which dump only the signature or compare 9627 respectively.
9712 the dumped signature with the cached one, respectively.
9713 9628
9714Using BitBake with either of these options causes BitBake to dump out 9629Using BitBake with either of these options causes BitBake to dump out
9715``sigdata`` files in the ``stamps`` directory for every task it would 9630``sigdata`` files in the ``stamps`` directory for every task it would
@@ -9741,7 +9656,7 @@ The OpenEmbedded build system uses
9741:ref:`checksums <overview-checksums>` and 9656:ref:`checksums <overview-checksums>` and
9742:ref:`overview-manual/overview-manual-concepts:shared state` cache to avoid unnecessarily 9657:ref:`overview-manual/overview-manual-concepts:shared state` cache to avoid unnecessarily
9743rebuilding tasks. Collectively, this scheme is known as "shared state 9658rebuilding tasks. Collectively, this scheme is known as "shared state
9744code." 9659code".
9745 9660
9746As with all schemes, this one has some drawbacks. It is possible that 9661As with all schemes, this one has some drawbacks. It is possible that
9747you could make implicit changes to your code that the checksum 9662you could make implicit changes to your code that the checksum
@@ -9778,8 +9693,7 @@ the build system to run the task again.
9778 9693
9779 For an example of a commit that makes a cosmetic change to invalidate 9694 For an example of a commit that makes a cosmetic change to invalidate
9780 shared state, see this 9695 shared state, see this
9781 commit 9696 :yocto_git:`commit </cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54>`.
9782 .
9783 9697
9784.. _dev-debugging-taskrunning: 9698.. _dev-debugging-taskrunning:
9785 9699
@@ -9814,14 +9728,9 @@ out), then you can use the ``-f`` option.
9814 9728
9815.. note:: 9729.. note::
9816 9730
9817 The reason 9731 The reason ``-f`` is never required when running the
9818 -f 9732 :ref:`ref-tasks-devshell` task is because the
9819 is never required when running the 9733 [\ :ref:`nostamp <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ]
9820 do_devshell
9821 task is because the
9822 [
9823 nostamp
9824 ]
9825 variable flag is already set for the task. 9734 variable flag is already set for the task.
9826 9735
9827The following example shows one way you can use the ``-f`` option: 9736The following example shows one way you can use the ``-f`` option:
@@ -9847,8 +9756,7 @@ that depend on it is to use the ``-C`` option.
9847 9756
9848.. note:: 9757.. note::
9849 9758
9850 This option is upper-cased and is separate from the 9759 This option is upper-cased and is separate from the ``-c``
9851 -c
9852 option, which is lower-cased. 9760 option, which is lower-cased.
9853 9761
9854Using this option invalidates the given task and then runs the 9762Using this option invalidates the given task and then runs the
@@ -9870,7 +9778,8 @@ task dependency mechanisms.
9870 BitBake explicitly keeps track of which tasks have been tainted in 9778 BitBake explicitly keeps track of which tasks have been tainted in
9871 this fashion, and will print warnings such as the following for 9779 this fashion, and will print warnings such as the following for
9872 builds involving such tasks: 9780 builds involving such tasks:
9873 :: 9781
9782 .. code-block:: none
9874 9783
9875 WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run 9784 WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
9876 9785
@@ -9905,7 +9814,7 @@ debug output gives more information about what BitBake is doing and the
9905reason behind it. Each ``-D`` option you use increases the logging 9814reason behind it. Each ``-D`` option you use increases the logging
9906level. The most common usage is ``-DDD``. 9815level. The most common usage is ``-DDD``.
9907 9816
9908The output from ``bitbake -DDD -v`` targetname can reveal why BitBake 9817The output from ``bitbake -DDD -v targetname`` can reveal why BitBake
9909chose a certain version of a package or why BitBake picked a certain 9818chose a certain version of a package or why BitBake picked a certain
9910provider. This command could also help you in a situation where you 9819provider. This command could also help you in a situation where you
9911think BitBake did something unexpected. 9820think BitBake did something unexpected.
@@ -9936,7 +9845,7 @@ Recipe Logging Mechanisms
9936The Yocto Project provides several logging functions for producing 9845The Yocto Project provides several logging functions for producing
9937debugging output and reporting errors and warnings. For Python 9846debugging output and reporting errors and warnings. For Python
9938functions, the following logging functions exist. All of these functions 9847functions, the following logging functions exist. All of these functions
9939log to ``${T}/log.do_``\ task, and can also log to standard output 9848log to ``${T}/log.do_``\ `task`, and can also log to standard output
9940(stdout) with the right settings: 9849(stdout) with the right settings:
9941 9850
9942- ``bb.plain(msg)``: Writes msg as is to the log while also 9851- ``bb.plain(msg)``: Writes msg as is to the log while also
@@ -9965,9 +9874,8 @@ log to ``${T}/log.do_``\ task, and can also log to standard output
9965 9874
9966 .. note:: 9875 .. note::
9967 9876
9968 bb.fatal() 9877 ``bb.fatal()`` raises an exception, which means you do not need to put a
9969 raises an exception, which means you do not need to put a "return" 9878 "return" statement after the function.
9970 statement after the function.
9971 9879
9972The same logging functions are also available in shell functions, under 9880The same logging functions are also available in shell functions, under
9973the names ``bbplain``, ``bbnote``, ``bbdebug``, ``bbwarn``, ``bberror``, 9881the names ``bbplain``, ``bbnote``, ``bbdebug``, ``bbwarn``, ``bberror``,
@@ -10050,12 +9958,8 @@ Project autobuilder and the process used to fix it.
10050 9958
10051.. note:: 9959.. note::
10052 9960
10053 If you cannot properly fix a 9961 If you cannot properly fix a ``make`` race condition, you can work around it
10054 make 9962 by clearing either the :term:`PARALLEL_MAKE` or :term:`PARALLEL_MAKEINST`
10055 race condition, you can work around it by clearing either the
10056 PARALLEL_MAKE
10057 or
10058 PARALLEL_MAKEINST
10059 variables. 9963 variables.
10060 9964
10061The Failure 9965The Failure
@@ -10072,7 +9976,8 @@ and creates the following output.
10072 9976
10073If you examine the output or the log file, you see the failure during 9977If you examine the output or the log file, you see the failure during
10074``make``: 9978``make``:
10075:: 9979
9980.. code-block:: none
10076 9981
10077 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] 9982 | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
10078 | DEBUG: Executing shell function do_compile 9983 | DEBUG: Executing shell function do_compile
@@ -10257,7 +10162,9 @@ With everything in place, you can get back to trying the build again
10257locally: 10162locally:
10258:: 10163::
10259 10164
10260 $ bitbake neard This build should succeed. 10165 $ bitbake neard
10166
10167This build should succeed.
10261 10168
10262Now you can open up a ``devshell`` again and repeat the clean and make 10169Now you can open up a ``devshell`` again and repeat the clean and make
10263operations as follows: 10170operations as follows:
@@ -10286,15 +10193,13 @@ style analysis of program crashes. GDB is available as a package within
10286the Yocto Project and is installed in SDK images by default. See the 10193the Yocto Project and is installed in SDK images by default. See the
10287":ref:`ref-manual/ref-images:Images`" chapter in the Yocto 10194":ref:`ref-manual/ref-images:Images`" chapter in the Yocto
10288Project Reference Manual for a description of these images. You can find 10195Project Reference Manual for a description of these images. You can find
10289information on GDB at http://sourceware.org/gdb/. 10196information on GDB at https://sourceware.org/gdb/.
10290 10197
10291.. note:: 10198.. note::
10292 10199
10293 For best results, install debug ( 10200 For best results, install debug (``-dbg``) packages for the applications you
10294 -dbg 10201 are going to debug. Doing so makes extra debug symbols available that give
10295 ) packages for the applications you are going to debug. Doing so 10202 you more meaningful output.
10296 makes extra debug symbols available that give you more meaningful
10297 output.
10298 10203
10299Sometimes, due to memory or disk space constraints, it is not possible 10204Sometimes, due to memory or disk space constraints, it is not possible
10300to use GDB directly on the remote target to debug applications. These 10205to use GDB directly on the remote target to debug applications. These
@@ -10331,7 +10236,7 @@ match the host's binaries.
10331To remain consistent with GDB documentation and terminology, the binary 10236To remain consistent with GDB documentation and terminology, the binary
10332being debugged on the remote target machine is referred to as the 10237being debugged on the remote target machine is referred to as the
10333"inferior" binary. For documentation on GDB see the `GDB 10238"inferior" binary. For documentation on GDB see the `GDB
10334site <http://sourceware.org/gdb/documentation/>`__. 10239site <https://sourceware.org/gdb/documentation/>`__.
10335 10240
10336The following steps show you how to debug using the GNU project 10241The following steps show you how to debug using the GNU project
10337debugger. 10242debugger.
@@ -10404,13 +10309,11 @@ debugger.
10404 10309
10405 .. note:: 10310 .. note::
10406 10311
10407 If you run 10312 If you run ``bitbake gdb-cross``, the OpenEmbedded build system suggests
10408 bitbake gdb-cross 10313 the actual image (e.g. ``gdb-cross-i586``). The suggestion is usually the
10409 , the OpenEmbedded build system suggests the actual image (e.g. 10314 actual name you want to use.
10410 gdb-cross-i586
10411 ). The suggestion is usually the actual name you want to use.
10412 10315
104134. *Set up the* ``debugfs`` 103164. *Set up the* ``debugfs``\ *:*
10414 10317
10415 Run the following commands to set up the ``debugfs``: 10318 Run the following commands to set up the ``debugfs``:
10416 :: 10319 ::
@@ -10420,19 +10323,19 @@ debugger.
10420 $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image.rootfs.tar.bz2 10323 $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image.rootfs.tar.bz2
10421 $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image-dbg.rootfs.tar.bz2 10324 $ tar xvfj build-dir/tmp-glibc/deploy/images/machine/image-dbg.rootfs.tar.bz2
10422 10325
104235. *Set up GDB* 103265. *Set up GDB:*
10424 10327
10425 Install the SDK (if you built one) and then source the correct 10328 Install the SDK (if you built one) and then source the correct
10426 environment file. Sourcing the environment file puts the SDK in your 10329 environment file. Sourcing the environment file puts the SDK in your
10427 ``PATH`` environment variable. 10330 ``PATH`` environment variable.
10428 10331
10429 If you are using the build system, Gdb is located in 10332 If you are using the build system, Gdb is located in
10430 build-dir/tmp/sysroots/host/usr/bin/architecture/architecture-gdb 10333 `build-dir`\ ``/tmp/sysroots/``\ `host`\ ``/usr/bin/``\ `architecture`\ ``/``\ `architecture`\ ``-gdb``
10431 10334
104326. *Boot the target:* 103356. *Boot the target:*
10433 10336
10434 For information on how to run QEMU, see the `QEMU 10337 For information on how to run QEMU, see the `QEMU
10435 Documentation <http://wiki.qemu.org/Documentation/GettingStartedDevelopers>`__. 10338 Documentation <https://wiki.qemu.org/Documentation/GettingStartedDevelopers>`__.
10436 10339
10437 .. note:: 10340 .. note::
10438 10341
@@ -10442,7 +10345,8 @@ debugger.
10442 10345
10443 Debugging a program involves running gdbserver on the target and then 10346 Debugging a program involves running gdbserver on the target and then
10444 running Gdb on the host. The example in this step debugs ``gzip``: 10347 running Gdb on the host. The example in this step debugs ``gzip``:
10445 :: 10348
10349 .. code-block:: shell
10446 10350
10447 root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help 10351 root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
10448 10352
@@ -10466,12 +10370,9 @@ debugger.
10466 10370
10467 .. note:: 10371 .. note::
10468 10372
10469 The Gdb 10373 The Gdb ``set`` commands in the previous example can be placed into the
10470 set 10374 users ``~/.gdbinit`` file. Upon starting, Gdb automatically runs whatever
10471 commands in the previous example can be placed into the users 10375 commands are in that file.
10472 ~/.gdbinit
10473 file. Upon starting, Gdb automatically runs whatever commands are
10474 in that file.
10475 10376
104768. *Deploying without a full image rebuild:* 103778. *Deploying without a full image rebuild:*
10477 10378
@@ -10509,9 +10410,11 @@ To support this kind of debugging, you need do the following:
10509 10410
10510- Ensure that GDB is on the target. You can do this by adding "gdb" to 10411- Ensure that GDB is on the target. You can do this by adding "gdb" to
10511 :term:`IMAGE_INSTALL`: 10412 :term:`IMAGE_INSTALL`:
10512 IMAGE_INSTALL_append = " gdb" Alternatively, you can add 10413 ::
10513 "tools-debug" to 10414
10514 :term:`IMAGE_FEATURES`: 10415 IMAGE_INSTALL_append = " gdb"
10416
10417 Alternatively, you can add "tools-debug" to :term:`IMAGE_FEATURES`:
10515 :: 10418 ::
10516 10419
10517 IMAGE_FEATURES_append = " tools-debug" 10420 IMAGE_FEATURES_append = " tools-debug"
@@ -10532,18 +10435,13 @@ To support this kind of debugging, you need do the following:
10532 10435
10533 To improve the debug information accuracy, you can reduce the level 10436 To improve the debug information accuracy, you can reduce the level
10534 of optimization used by the compiler. For example, when adding the 10437 of optimization used by the compiler. For example, when adding the
10535 following line to your 10438 following line to your ``local.conf`` file, you will reduce optimization
10536 local.conf 10439 from :term:`FULL_OPTIMIZATION` of "-O2" to :term:`DEBUG_OPTIMIZATION`
10537 file, you will reduce optimization from
10538 FULL_OPTIMIZATION
10539 of "-O2" to
10540 DEBUG_OPTIMIZATION
10541 of "-O -fno-omit-frame-pointer": 10440 of "-O -fno-omit-frame-pointer":
10542 :: 10441 ::
10543 10442
10544 DEBUG_BUILD = "1" 10443 DEBUG_BUILD = "1"
10545 10444
10546
10547 Consider that this will reduce the application's performance and is 10445 Consider that this will reduce the application's performance and is
10548 recommended only for debugging purposes. 10446 recommended only for debugging purposes.
10549 10447
@@ -10575,11 +10473,9 @@ Here are some other tips that you might find useful:
10575 10473
10576 .. note:: 10474 .. note::
10577 10475
10578 Removing 10476 Removing ``TMPDIR`` might be a workaround rather than a fix.
10579 TMPDIR 10477 Consequently, trying to determine the underlying cause of an issue before
10580 might be a workaround rather than a fix. Consequently, trying to 10478 removing the directory is a good idea.
10581 determine the underlying cause of an issue before removing the
10582 directory is a good idea.
10583 10479
10584- Understanding how a feature is used in practice within existing 10480- Understanding how a feature is used in practice within existing
10585 recipes can be very helpful. It is recommended that you configure 10481 recipes can be very helpful. It is recommended that you configure
@@ -10624,9 +10520,7 @@ Here are some other tips that you might find useful:
10624 10520
10625 The manuals might not be the right place to document variables 10521 The manuals might not be the right place to document variables
10626 that are purely internal and have a limited scope (e.g. internal 10522 that are purely internal and have a limited scope (e.g. internal
10627 variables used to implement a single 10523 variables used to implement a single ``.bbclass`` file).
10628 .bbclass
10629 file).
10630 10524
10631Making Changes to the Yocto Project 10525Making Changes to the Yocto Project
10632=================================== 10526===================================
@@ -10640,15 +10534,15 @@ Submitting a Defect Against the Yocto Project
10640--------------------------------------------- 10534---------------------------------------------
10641 10535
10642Use the Yocto Project implementation of 10536Use the Yocto Project implementation of
10643`Bugzilla <http://www.bugzilla.org/about/>`__ to submit a defect (bug) 10537`Bugzilla <https://www.bugzilla.org/about/>`__ to submit a defect (bug)
10644against the Yocto Project. For additional information on this 10538against the Yocto Project. For additional information on this
10645implementation of Bugzilla see the :ref:"`Yocto Project 10539implementation of Bugzilla see the ":ref:`Yocto Project
10646Bugzilla <resources-bugtracker>`" section in the 10540Bugzilla <resources-bugtracker>`" section in the
10647Yocto Project Reference Manual. For more detail on any of the following 10541Yocto Project Reference Manual. For more detail on any of the following
10648steps, see the Yocto Project 10542steps, see the Yocto Project
10649:yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`. 10543:yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`.
10650 10544
10651Use the following general steps to submit a bug" 10545Use the following general steps to submit a bug:
10652 10546
106531. Open the Yocto Project implementation of :yocto_bugs:`Bugzilla <>`. 105471. Open the Yocto Project implementation of :yocto_bugs:`Bugzilla <>`.
10654 10548
@@ -10662,7 +10556,7 @@ Use the following general steps to submit a bug"
10662 Runtime", "BSPs", and "bsps-meta-intel", respectively. 10556 Runtime", "BSPs", and "bsps-meta-intel", respectively.
10663 10557
106644. Choose the "Version" of the Yocto Project for which you found the 105584. Choose the "Version" of the Yocto Project for which you found the
10665 bug (e.g. DISTRO). 10559 bug (e.g. &DISTRO;).
10666 10560
106675. Determine and select the "Severity" of the bug. The severity 105615. Determine and select the "Severity" of the bug. The severity
10668 indicates how the bug impacted your work. 10562 indicates how the bug impacted your work.
@@ -10728,24 +10622,24 @@ the combo-layer tool. The upstream location used for submitting changes
10728varies by component: 10622varies by component:
10729 10623
10730- *Core Metadata:* Send your patch to the 10624- *Core Metadata:* Send your patch to the
10731 `openembedded-core <http://lists.openembedded.org/mailman/listinfo/openembedded-core>`__ 10625 :oe_lists:`openembedded-core </g/openembedded-core>`
10732 mailing list. For example, a change to anything under the ``meta`` or 10626 mailing list. For example, a change to anything under the ``meta`` or
10733 ``scripts`` directories should be sent to this mailing list. 10627 ``scripts`` directories should be sent to this mailing list.
10734 10628
10735- *BitBake:* For changes to BitBake (i.e. anything under the 10629- *BitBake:* For changes to BitBake (i.e. anything under the
10736 ``bitbake`` directory), send your patch to the 10630 ``bitbake`` directory), send your patch to the
10737 `bitbake-devel <http://lists.openembedded.org/mailman/listinfo/bitbake-devel>`__ 10631 :oe_lists:`bitbake-devel </g/bitbake-devel>`
10738 mailing list. 10632 mailing list.
10739 10633
10740- *"meta-\*" trees:* These trees contain Metadata. Use the 10634- *"meta-\*" trees:* These trees contain Metadata. Use the
10741 `poky <https://lists.yoctoproject.org/g/poky>`__ mailing list. 10635 :yocto_lists:`poky </g/poky>` mailing list.
10742 10636
10743- *Documentation*: For changes to the Yocto Project documentation, use the `docs 10637- *Documentation*: For changes to the Yocto Project documentation, use the
10744 <https://lists.yoctoproject.org/g/docs>`__ mailing list. 10638 :yocto_lists:`docs </g/docs>` mailing list.
10745 10639
10746For changes to other layers hosted in the Yocto Project source 10640For changes to other layers hosted in the Yocto Project source
10747repositories (i.e. ``yoctoproject.org``) and tools use the `Yocto Project 10641repositories (i.e. ``yoctoproject.org``) and tools use the
10748<https://lists.yoctoproject.org/g/yocto/>`__ general mailing list. 10642:yocto_lists:`Yocto Project </g/yocto/>` general mailing list.
10749 10643
10750.. note:: 10644.. note::
10751 10645
@@ -10783,7 +10677,7 @@ whether the patch has been merged into one of these branches.
10783 flow. Asking about the status of a patch or change is reasonable if 10677 flow. Asking about the status of a patch or change is reasonable if
10784 the change has been idle for a while with no feedback. The Yocto 10678 the change has been idle for a while with no feedback. The Yocto
10785 Project does have plans to use 10679 Project does have plans to use
10786 Patchwork 10680 `Patchwork <https://en.wikipedia.org/wiki/Patchwork_(software)>`__
10787 to track the status of patches and also to automatically preview 10681 to track the status of patches and also to automatically preview
10788 patches. 10682 patches.
10789 10683
@@ -10801,8 +10695,7 @@ repository:
10801 10695
10802 You can find general Git information on how to push a change upstream 10696 You can find general Git information on how to push a change upstream
10803 in the 10697 in the
10804 Git Community Book 10698 `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__.
10805 .
10806 10699
108071. *Make Your Changes Locally:* Make your changes in your local Git 107001. *Make Your Changes Locally:* Make your changes in your local Git
10808 repository. You should make small, controlled, isolated changes. 10701 repository. You should make small, controlled, isolated changes.
@@ -10821,7 +10714,8 @@ repository:
10821 required by the Linux kernel. Adding this line signifies that you, 10714 required by the Linux kernel. Adding this line signifies that you,
10822 the submitter, have agreed to the Developer's Certificate of 10715 the submitter, have agreed to the Developer's Certificate of
10823 Origin 1.1 as follows: 10716 Origin 1.1 as follows:
10824 :: 10717
10718 .. code-block:: none
10825 10719
10826 Developer's Certificate of Origin 1.1 10720 Developer's Certificate of Origin 1.1
10827 10721
@@ -10849,7 +10743,7 @@ repository:
10849 maintained indefinitely and may be redistributed consistent with 10743 maintained indefinitely and may be redistributed consistent with
10850 this project or the open source license(s) involved. 10744 this project or the open source license(s) involved.
10851 10745
10852 - Provide a single-line summary of the change. and, if more 10746 - Provide a single-line summary of the change and, if more
10853 explanation is needed, provide more detail in the body of the 10747 explanation is needed, provide more detail in the body of the
10854 commit. This summary is typically viewable in the "shortlist" of 10748 commit. This summary is typically viewable in the "shortlist" of
10855 changes. Thus, providing something short and descriptive that 10749 changes. Thus, providing something short and descriptive that
@@ -10892,10 +10786,10 @@ repository:
10892 10786
10893 For example, suppose you have permissions to push 10787 For example, suppose you have permissions to push
10894 into the upstream ``meta-intel-contrib`` repository and you are 10788 into the upstream ``meta-intel-contrib`` repository and you are
10895 working in a local branch named your_name\ ``/README``. The following 10789 working in a local branch named `your_name`\ ``/README``. The following
10896 command pushes your local commits to the ``meta-intel-contrib`` 10790 command pushes your local commits to the ``meta-intel-contrib``
10897 upstream repository and puts the commit in a branch named 10791 upstream repository and puts the commit in a branch named
10898 your_name\ ``/README``: 10792 `your_name`\ ``/README``:
10899 :: 10793 ::
10900 10794
10901 $ git push meta-intel-contrib your_name/README 10795 $ git push meta-intel-contrib your_name/README
@@ -10954,7 +10848,7 @@ repository:
10954 $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" 10848 $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
10955 10849
10956 Running this script forms ``*.patch`` files in a folder named 10850 Running this script forms ``*.patch`` files in a folder named
10957 ``pull-``\ PID in the current directory. One of the patch files is a 10851 ``pull-``\ `PID` in the current directory. One of the patch files is a
10958 cover letter. 10852 cover letter.
10959 10853
10960 Before running the ``send-pull-request`` script, you must edit the 10854 Before running the ``send-pull-request`` script, you must edit the
@@ -10971,8 +10865,7 @@ repository:
10971 10865
10972 .. note:: 10866 .. note::
10973 10867
10974 For help on using these scripts, simply provide the 10868 For help on using these scripts, simply provide the ``-h``
10975 -h
10976 argument as follows: 10869 argument as follows:
10977 :: 10870 ::
10978 10871
@@ -11014,9 +10907,9 @@ without using the scripts:
11014 Developer's Certificate of Origin (DCO) shown earlier. 10907 Developer's Certificate of Origin (DCO) shown earlier.
11015 10908
11016 When you form a commit, you must follow certain standards established 10909 When you form a commit, you must follow certain standards established
11017 by the Yocto Project development team. See `Step 10910 by the Yocto Project development team. See :ref:`Step 3
11018 3 <#making-sure-you-have-correct-commit-information>`__ in the 10911 <dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull>`
11019 previous section for information on how to provide commit information 10912 in the previous section for information on how to provide commit information
11020 that meets Yocto Project commit message standards. 10913 that meets Yocto Project commit message standards.
11021 10914
110224. *Format the Commit:* Format the commit into an email message. To 109154. *Format the Commit:* Format the commit into an email message. To
@@ -11057,12 +10950,9 @@ without using the scripts:
11057 10950
11058 .. note:: 10951 .. note::
11059 10952
11060 In order to use 10953 In order to use ``git send-email``, you must have the proper Git packages
11061 git send-email 10954 installed on your host.
11062 , you must have the proper Git packages installed on your host. 10955 For Ubuntu, Debian, and Fedora the package is ``git-email``.
11063 For Ubuntu, Debian, and Fedora the package is
11064 git-email
11065 .
11066 10956
11067 The ``git send-email`` command sends email by using a local or remote 10957 The ``git send-email`` command sends email by using a local or remote
11068 Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or 10958 Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
@@ -11288,10 +11178,7 @@ in the whitelist.
11288 11178
11289 When using a string subset, be sure to use the part of the expanded 11179 When using a string subset, be sure to use the part of the expanded
11290 string that precedes the appended underscore character (e.g. 11180 string that precedes the appended underscore character (e.g.
11291 usethispart_1.3 11181 ``usethispart_1.3``, ``usethispart_1.4``, and so forth).
11292 ,
11293 usethispart_1.4
11294 , and so forth).
11295 11182
11296For example, simply specifying the string "commercial" in the whitelist 11183For example, simply specifying the string "commercial" in the whitelist
11297matches any expanded ``LICENSE_FLAGS`` definition that starts with the 11184matches any expanded ``LICENSE_FLAGS`` definition that starts with the
@@ -11410,9 +11297,7 @@ audit all artifacts to ensure completeness.
11410.. note:: 11297.. note::
11411 11298
11412 The Yocto Project generates a license manifest during image creation 11299 The Yocto Project generates a license manifest during image creation
11413 that is located in 11300 that is located in ``${DEPLOY_DIR}/licenses/``\ `image_name`\ ``-``\ `datestamp`
11414 ${DEPLOY_DIR}/licenses/
11415 image_name-datestamp
11416 to assist with any audits. 11301 to assist with any audits.
11417 11302
11418Providing the Source Code 11303Providing the Source Code
@@ -11459,7 +11344,8 @@ the size of the directory can get large.
11459A way to help mitigate the size issue is to only release tarballs for 11344A way to help mitigate the size issue is to only release tarballs for
11460licenses that require the release of source. Let us assume you are only 11345licenses that require the release of source. Let us assume you are only
11461concerned with GPL code as identified by running the following script: 11346concerned with GPL code as identified by running the following script:
11462:: 11347
11348.. code-block:: shell
11463 11349
11464 # Script to archive a subset of packages matching specific license(s) 11350 # Script to archive a subset of packages matching specific license(s)
11465 # Source and license files are copied into sub folders of package folder 11351 # Source and license files are copied into sub folders of package folder
@@ -11549,7 +11435,8 @@ required to release those layers under section 3 of GPLv2 or section 1
11549of GPLv3. One way of doing that is with a clean checkout of the version 11435of GPLv3. One way of doing that is with a clean checkout of the version
11550of the Yocto Project and layers used during your build. Here is an 11436of the Yocto Project and layers used during your build. Here is an
11551example: 11437example:
11552:: 11438
11439.. code-block:: shell
11553 11440
11554 # We built using the dunfell branch of the poky repo 11441 # We built using the dunfell branch of the poky repo
11555 $ git clone -b dunfell git://git.yoctoproject.org/poky 11442 $ git clone -b dunfell git://git.yoctoproject.org/poky
@@ -11654,7 +11541,7 @@ The server receives the information collected and saves it in a
11654database. 11541database.
11655 11542
11656A live instance of the error reporting server exists at 11543A live instance of the error reporting server exists at
11657http://errors.yoctoproject.org. This server exists so that when 11544https://errors.yoctoproject.org. This server exists so that when
11658you want to get help with build failures, you can submit all of the 11545you want to get help with build failures, you can submit all of the
11659information on the failure easily and then point to the URL in your bug 11546information on the failure easily and then point to the URL in your bug
11660report or send an email to the mailing list. 11547report or send an email to the mailing list.
@@ -11696,7 +11583,7 @@ following command sends the errors to an upstream server:
11696 $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt 11583 $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt
11697 11584
11698In the previous example, the errors are sent to a public database 11585In the previous example, the errors are sent to a public database
11699available at http://errors.yoctoproject.org, which is used by the 11586available at https://errors.yoctoproject.org, which is used by the
11700entire community. If you specify a particular server, you can send the 11587entire community. If you specify a particular server, you can send the
11701errors to a different database. Use the following command for more 11588errors to a different database. Use the following command for more
11702information on available options: 11589information on available options:
@@ -11708,7 +11595,7 @@ When sending the error file, you are prompted to review the data being
11708sent as well as to provide a name and optional email address. Once you 11595sent as well as to provide a name and optional email address. Once you
11709satisfy these prompts, the command returns a link from the server that 11596satisfy these prompts, the command returns a link from the server that
11710corresponds to your entry in the database. For example, here is a 11597corresponds to your entry in the database. For example, here is a
11711typical link: http://errors.yoctoproject.org/Errors/Details/9522/ 11598typical link: https://errors.yoctoproject.org/Errors/Details/9522/
11712 11599
11713Following the link takes you to a web interface where you can browse, 11600Following the link takes you to a web interface where you can browse,
11714query the errors, and view statistics. 11601query the errors, and view statistics.
@@ -11727,8 +11614,7 @@ Setting Up Your Own Error Reporting Server
11727------------------------------------------ 11614------------------------------------------
11728 11615
11729If you want to set up your own error reporting server, you can obtain 11616If you want to set up your own error reporting server, you can obtain
11730the code from the Git repository at 11617the code from the Git repository at :yocto_git:`/cgit/cgit.cgi/error-report-web/`.
11731http://git.yoctoproject.org/cgit/cgit.cgi/error-report-web/.
11732Instructions on how to set it up are in the README document. 11618Instructions on how to set it up are in the README document.
11733 11619
11734.. _dev-using-wayland-and-weston: 11620.. _dev-using-wayland-and-weston:
@@ -11736,7 +11622,7 @@ Instructions on how to set it up are in the README document.
11736Using Wayland and Weston 11622Using Wayland and Weston
11737======================== 11623========================
11738 11624
11739`Wayland <http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)>`__ 11625`Wayland <https://en.wikipedia.org/wiki/Wayland_(display_server_protocol)>`__
11740is a computer display server protocol that provides a method for 11626is a computer display server protocol that provides a method for
11741compositing window managers to communicate directly with applications 11627compositing window managers to communicate directly with applications
11742and video hardware and expects them to communicate with input hardware 11628and video hardware and expects them to communicate with input hardware
@@ -11746,7 +11632,7 @@ might otherwise achieve.
11746 11632
11747The Yocto Project provides the Wayland protocol libraries and the 11633The Yocto Project provides the Wayland protocol libraries and the
11748reference 11634reference
11749`Weston <http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston>`__ 11635`Weston <https://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston>`__
11750compositor as part of its release. You can find the integrated packages 11636compositor as part of its release. You can find the integrated packages
11751in the ``meta`` layer of the :term:`Source Directory`. 11637in the ``meta`` layer of the :term:`Source Directory`.
11752Specifically, you 11638Specifically, you
diff --git a/documentation/dev-manual/dev-manual-intro.rst b/documentation/dev-manual/dev-manual-intro.rst
index da08b7b6ef..05136f7353 100644
--- a/documentation/dev-manual/dev-manual-intro.rst
+++ b/documentation/dev-manual/dev-manual-intro.rst
@@ -39,7 +39,7 @@ This manual does not provide the following:
39 39
40- Reference or Conceptual Material: This type of material resides in an 40- Reference or Conceptual Material: This type of material resides in an
41 appropriate reference manual. For example, system variables are 41 appropriate reference manual. For example, system variables are
42 documented in the :doc`../ref-manual/ref-manual`. 42 documented in the :doc:`../ref-manual/ref-manual`.
43 43
44- Detailed Public Information Not Specific to the Yocto Project: For 44- Detailed Public Information Not Specific to the Yocto Project: For
45 example, exhaustive information on how to use the Source Control 45 example, exhaustive information on how to use the Source Control
diff --git a/documentation/dev-manual/dev-manual-qemu.rst b/documentation/dev-manual/dev-manual-qemu.rst
index 9337a35428..c91e8b5389 100644
--- a/documentation/dev-manual/dev-manual-qemu.rst
+++ b/documentation/dev-manual/dev-manual-qemu.rst
@@ -33,10 +33,10 @@ implementation of QEMU.
33For official information and documentation on QEMU in general, see the 33For official information and documentation on QEMU in general, see the
34following references: 34following references:
35 35
36- `QEMU Website <http://wiki.qemu.org/Main_Page>`__\ *:* The official 36- `QEMU Website <https://wiki.qemu.org/Main_Page>`__\ *:* The official
37 website for the QEMU Open Source project. 37 website for the QEMU Open Source project.
38 38
39- `Documentation <http://wiki.qemu.org/Manual>`__\ *:* The QEMU user 39- `Documentation <https://wiki.qemu.org/Manual>`__\ *:* The QEMU user
40 manual. 40 manual.
41 41
42.. _qemu-running-qemu: 42.. _qemu-running-qemu:
@@ -141,14 +141,14 @@ available. Follow these general steps to run QEMU:
141 141
142 - This example does not provide enough information for QEMU to 142 - This example does not provide enough information for QEMU to
143 launch. While the command does provide a root filesystem type, it 143 launch. While the command does provide a root filesystem type, it
144 must also minimally provide a MACHINE, KERNEL, or VM option. 144 must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option.
145 :: 145 ::
146 146
147 $ runqemu ext4 147 $ runqemu ext4
148 148
149 - This example specifies to boot a virtual machine image 149 - This example specifies to boot a virtual machine image
150 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu`` 150 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
151 determines the QEMU architecture (MACHINE) to be "qemux86-64" and 151 determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
152 the root filesystem type to be "vmdk". 152 the root filesystem type to be "vmdk".
153 :: 153 ::
154 154
@@ -208,7 +208,8 @@ using an NFS server.
208 extracts it into a location that you specify. Here is an example that 208 extracts it into a location that you specify. Here is an example that
209 takes a file system and extracts it to a directory named 209 takes a file system and extracts it to a directory named
210 ``test-nfs``: 210 ``test-nfs``:
211 :: 211
212 .. code-block:: none
212 213
213 runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs 214 runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
214 215
@@ -217,7 +218,8 @@ using an NFS server.
217 You can then also make changes to the files within ``./test-nfs`` and 218 You can then also make changes to the files within ``./test-nfs`` and
218 see those changes appear in the image in real time. Here is an 219 see those changes appear in the image in real time. Here is an
219 example using the ``qemux86`` image: 220 example using the ``qemux86`` image:
220 :: 221
222 .. code-block:: none
221 223
222 runqemu qemux86-64 ./test-nfs 224 runqemu qemux86-64 ./test-nfs
223 225
@@ -226,14 +228,20 @@ using an NFS server.
226 Should you need to start, stop, or restart the NFS share, you can use 228 Should you need to start, stop, or restart the NFS share, you can use
227 the following commands: 229 the following commands:
228 230
229 - The following command starts the NFS share: runqemu-export-rootfs 231 - The following command starts the NFS share:
230 start file-system-location 232 ::
233
234 runqemu-export-rootfs start file-system-location
235
236 - The following command stops the NFS share:
237 ::
231 238
232 - The following command stops the NFS share: runqemu-export-rootfs 239 runqemu-export-rootfs stop file-system-location
233 stop file-system-location
234 240
235 - The following command restarts the NFS share: 241 - The following command restarts the NFS share:
236 runqemu-export-rootfs restart file-system-location 242 ::
243
244 runqemu-export-rootfs restart file-system-location
237 245
238.. _qemu-kvm-cpu-compatibility: 246.. _qemu-kvm-cpu-compatibility:
239 247
@@ -380,30 +388,29 @@ command line:
380.. note:: 388.. note::
381 389
382 If you do provide some "illegal" option combination or perhaps you do 390 If you do provide some "illegal" option combination or perhaps you do
383 not provide enough in the way of options, 391 not provide enough in the way of options, ``runqemu``
384 runqemu
385 provides appropriate error messaging to help you correct the problem. 392 provides appropriate error messaging to help you correct the problem.
386 393
387- QEMUARCH: The QEMU machine architecture, which must be "qemuarm", 394- `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm",
388 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or 395 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or
389 "qemux86-64". 396 "qemux86-64".
390 397
391- ``VM``: The virtual machine image, which must be a ``.wic.vmdk`` 398- `VM`: The virtual machine image, which must be a ``.wic.vmdk``
392 file. Use this option when you want to boot a ``.wic.vmdk`` image. 399 file. Use this option when you want to boot a ``.wic.vmdk`` image.
393 The image filename you provide must contain one of the following 400 The image filename you provide must contain one of the following
394 strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64", 401 strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64",
395 "qemumips", "qemuppc", or "qemush4". 402 "qemumips", "qemuppc", or "qemush4".
396 403
397- ROOTFS: A root filesystem that has one of the following filetype 404- `ROOTFS`: A root filesystem that has one of the following filetype
398 extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If 405 extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If
399 the filename you provide for this option uses "nfs", it must provide 406 the filename you provide for this option uses "nfs", it must provide
400 an explicit root filesystem path. 407 an explicit root filesystem path.
401 408
402- KERNEL: A kernel image, which is a ``.bin`` file. When you provide a 409- `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a
403 ``.bin`` file, ``runqemu`` detects it and assumes the file is a 410 ``.bin`` file, ``runqemu`` detects it and assumes the file is a
404 kernel image. 411 kernel image.
405 412
406- MACHINE: The architecture of the QEMU machine, which must be one of 413- `MACHINE`: The architecture of the QEMU machine, which must be one of
407 the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64", 414 the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64",
408 "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH 415 "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH
409 options are basically identical. If you do not provide a MACHINE 416 options are basically identical. If you do not provide a MACHINE
diff --git a/documentation/dev-manual/dev-manual-start.rst b/documentation/dev-manual/dev-manual-start.rst
index 333c6a566f..a85b86fbfb 100644
--- a/documentation/dev-manual/dev-manual-start.rst
+++ b/documentation/dev-manual/dev-manual-start.rst
@@ -88,12 +88,10 @@ particular working environment and set of practices.
88 .. note:: 88 .. note::
89 89
90 For information about BitBake, see the 90 For information about BitBake, see the
91 BitBake User Manual 91 :doc:`bitbake:index`.
92 .
93 92
94 It is relatively easy to set up Git services and create 93 It is relatively easy to set up Git services and create
95 infrastructure like 94 infrastructure like :yocto_git:`/`, which is based on
96 :yocto_git:`http://git.yoctoproject.org <>`, which is based on
97 server software called ``gitolite`` with ``cgit`` being used to 95 server software called ``gitolite`` with ``cgit`` being used to
98 generate the web interface that lets you view the repositories. The 96 generate the web interface that lets you view the repositories. The
99 ``gitolite`` software identifies users using SSH keys and allows 97 ``gitolite`` software identifies users using SSH keys and allows
@@ -106,10 +104,7 @@ particular working environment and set of practices.
106 However, sites such as the following exist that describe how to 104 However, sites such as the following exist that describe how to
107 perform setup: 105 perform setup:
108 106
109 - `Git documentation <http://git-scm.com/book/ch4-8.html>`__: 107 - `Gitolite <https://gitolite.com>`__: Information for
110 Describes how to install ``gitolite`` on the server.
111
112 - `Gitolite <http://gitolite.com>`__: Information for
113 ``gitolite``. 108 ``gitolite``.
114 109
115 - `Interfaces, frontends, and 110 - `Interfaces, frontends, and
@@ -161,8 +156,7 @@ particular working environment and set of practices.
161 integration" style testing of software components and regression 156 integration" style testing of software components and regression
162 identification and tracking. 157 identification and tracking.
163 158
164 See "`Yocto Project 159 See ":yocto_ab:`Yocto Project Autobuilder <>`" for more
165 Autobuilder <http://autobuilder.yoctoproject.org>`__" for more
166 information and links to buildbot. The Yocto Project team has found 160 information and links to buildbot. The Yocto Project team has found
167 this implementation works well in this role. A public example of 161 this implementation works well in this role. A public example of
168 this is the Yocto Project Autobuilders, which the Yocto Project team 162 this is the Yocto Project Autobuilders, which the Yocto Project team
@@ -207,8 +201,7 @@ particular working environment and set of practices.
207 201
208 .. note:: 202 .. note::
209 203
210 You can also use a more collective push model. The 204 You can also use a more collective push model. The ``gitolite``
211 gitolite
212 software supports both the push and pull models quite easily. 205 software supports both the push and pull models quite easily.
213 206
214 As with any development environment, it is important to document the 207 As with any development environment, it is important to document the
@@ -285,11 +278,10 @@ v2 (WSL).
285.. note:: 278.. note::
286 279
287 The Yocto Project is not compatible with 280 The Yocto Project is not compatible with
288 Windows Subsystem for Linux v1 281 `Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__.
289 . It is compatible but not officially supported nor validated with 282 It is compatible but not officially supported nor validated with
290 WSLv2. If you still decide to use WSL please upgrade to 283 WSLv2. If you still decide to use WSL please upgrade to
291 WSLv2 284 `WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__.
292 .
293 285
294Once your build host is set up to use the Yocto Project, further steps 286Once your build host is set up to use the Yocto Project, further steps
295are necessary depending on what you want to accomplish. See the 287are necessary depending on what you want to accomplish. See the
@@ -453,9 +445,9 @@ as your Yocto Project build host:
453 445
454Once you have a container set up, everything is in place to develop just 446Once you have a container set up, everything is in place to develop just
455as if you were running on a native Linux machine. If you are going to 447as if you were running on a native Linux machine. If you are going to
456use the Poky container, see the "`Cloning the ``poky`` 448use the Poky container, see the
457Repository <#cloning-the-poky-repository>`__" section. If you are going 449":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
458to use the Extensible SDK container, see the 450section. If you are going to use the Extensible SDK container, see the
459":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto 451":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
460Project Application Development and the Extensible Software Development 452Project Application Development and the Extensible Software Development
461Kit (eSDK) manual. If you are going to use the Toaster container, see 453Kit (eSDK) manual. If you are going to use the Toaster container, see
@@ -566,10 +558,7 @@ your Yocto Project build host:
566 558
567 The current implementation of WSLv2 does not have out-of-the-box 559 The current implementation of WSLv2 does not have out-of-the-box
568 access to external devices such as those connected through a USB 560 access to external devices such as those connected through a USB
569 port, but it automatically mounts your 561 port, but it automatically mounts your ``C:`` drive on ``/mnt/c/``
570 C:
571 drive on
572 /mnt/c/
573 (and others), which you can use to share deploy artifacts to be later 562 (and others), which you can use to share deploy artifacts to be later
574 flashed on hardware through Windows, but your build directory should 563 flashed on hardware through Windows, but your build directory should
575 not reside inside this mountpoint. 564 not reside inside this mountpoint.
@@ -623,11 +612,8 @@ Use the following procedure to locate the latest upstream copy of the
623 612
624 .. note:: 613 .. note::
625 614
626 For information on cloning a repository, see the " 615 For information on cloning a repository, see the
627 Cloning the 616 ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" section.
628 poky
629 Repository
630 " section.
631 617
632Accessing Index of Releases 618Accessing Index of Releases
633--------------------------- 619---------------------------
@@ -653,12 +639,10 @@ Follow these steps to locate and download a particular tarball:
653 639
654 .. note:: 640 .. note::
655 641
656 The 642 The ``yocto`` directory contains the full array of released Poky
657 yocto 643 tarballs. The ``poky`` directory in the Index of Releases was
658 directory contains the full array of released Poky tarballs. The 644 historically used for very early releases and exists now only for
659 poky 645 retroactive completeness.
660 directory in the Index of Releases was historically used for very
661 early releases and exists now only for retroactive completeness.
662 646
6632. *Select a Component:* Click on any released component in which you 6472. *Select a Component:* Click on any released component in which you
664 are interested (e.g. ``yocto``). 648 are interested (e.g. ``yocto``).
@@ -702,8 +686,7 @@ Releases <#accessing-index-of-releases>`__" section.
702 .. note:: 686 .. note::
703 687
704 For a "map" of Yocto Project releases to version numbers, see the 688 For a "map" of Yocto Project releases to version numbers, see the
705 Releases 689 :yocto_wiki:`Releases </wiki/Releases>` wiki page.
706 wiki page.
707 690
708 You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto 691 You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto
709 Project releases. 692 Project releases.
@@ -825,8 +808,9 @@ and then specifically check out that development branch.
825 808
8261. *Switch to the Poky Directory:* If you have a local poky Git 8091. *Switch to the Poky Directory:* If you have a local poky Git
827 repository, switch to that directory. If you do not have the local 810 repository, switch to that directory. If you do not have the local
828 copy of poky, see the "`Cloning the ``poky`` 811 copy of poky, see the
829 Repository <#cloning-the-poky-repository>`__" section. 812 ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
813 section.
830 814
8312. *Determine Existing Branch Names:* 8152. *Determine Existing Branch Names:*
832 :: 816 ::
@@ -854,13 +838,13 @@ and then specifically check out that development branch.
854 &DISTRO; Release (&DISTRO_NAME;), use the following command: 838 &DISTRO; Release (&DISTRO_NAME;), use the following command:
855 :: 839 ::
856 840
857 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; 841 $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
858 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin. 842 Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
859 Switched to a new branch '&DISTRO_NAME;' 843 Switched to a new branch '&DISTRO_NAME_NO_CAP;'
860 844
861 The previous command checks out the "&DISTRO_NAME;" development 845 The previous command checks out the "&DISTRO_NAME_NO_CAP;" development
862 branch and reports that the branch is tracking the upstream 846 branch and reports that the branch is tracking the upstream
863 "origin/&DISTRO_NAME;" branch. 847 "origin/&DISTRO_NAME_NO_CAP;" branch.
864 848
865 The following command displays the branches that are now part of your 849 The following command displays the branches that are now part of your
866 local poky repository. The asterisk character indicates the branch 850 local poky repository. The asterisk character indicates the branch
@@ -868,8 +852,8 @@ and then specifically check out that development branch.
868 :: 852 ::
869 853
870 $ git branch 854 $ git branch
871 master * 855 master
872 &DISTRO_NAME; 856 * &DISTRO_NAME_NO_CAP;
873 857
874.. _checkout-out-by-tag-in-poky: 858.. _checkout-out-by-tag-in-poky:
875 859
@@ -889,8 +873,9 @@ similar to checking out by branch name except you use tag names.
889 873
8901. *Switch to the Poky Directory:* If you have a local poky Git 8741. *Switch to the Poky Directory:* If you have a local poky Git
891 repository, switch to that directory. If you do not have the local 875 repository, switch to that directory. If you do not have the local
892 copy of poky, see the "`Cloning the ``poky`` 876 copy of poky, see the
893 Repository <#cloning-the-poky-repository>`__" section. 877 ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
878 section.
894 879
8952. *Fetch the Tag Names:* To checkout the branch based on a tag name, 8802. *Fetch the Tag Names:* To checkout the branch based on a tag name,
896 you need to fetch the upstream tags into your local repository: 881 you need to fetch the upstream tags into your local repository: