summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorQuentin Schulz <foss@0leil.net>2021-04-07 18:07:24 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-04-09 15:24:46 +0100
commitc380ba5a177de32e97820279685c4af6f837c010 (patch)
treec494289cda99f5bb76bad0d9492a3d1104d176d4 /documentation/dev-manual
parent802ac0b75e42657c7ff9f4ff5b2816c65ad29eea (diff)
downloadpoky-c380ba5a177de32e97820279685c4af6f837c010.tar.gz
docs: replace anchor links
Anchor links are treated by Sphinx as external links and are not checked during build, meaning it is impossible to know if a link becomes broken or not. As a matter of fact, most of the anchor links replaced in this commit were actually broken. The README now states that anchor links are forbidden so that there's no need to go through such a change later on. (From yocto-docs rev: de9e4d26b46afa3c79137d07529a74553400d2e0) Signed-off-by: Quentin Schulz <foss@0leil.net> Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/common-tasks.rst241
-rw-r--r--documentation/dev-manual/qemu.rst6
-rw-r--r--documentation/dev-manual/start.rst13
3 files changed, 117 insertions, 143 deletions
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 3f35dc6361..176025f9e8 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -155,8 +155,8 @@ Follow these general steps to create your layer without using tools:
1555. *Optionally Test for Compatibility:* If you want permission to use 1555. *Optionally Test for Compatibility:* If you want permission to use
156 the Yocto Project Compatibility logo with your layer or application 156 the Yocto Project Compatibility logo with your layer or application
157 that uses your layer, perform the steps to apply for compatibility. 157 that uses your layer, perform the steps to apply for compatibility.
158 See the "`Making Sure Your Layer is Compatible With Yocto 158 See the
159 Project <#making-sure-your-layer-is-compatible-with-yocto-project>`__" 159 ":ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project`"
160 section for more information. 160 section for more information.
161 161
162Following Best Practices When Creating Layers 162Following Best Practices When Creating Layers
@@ -282,9 +282,8 @@ following list:
282- *Perform Steps to Apply for Yocto Project Compatibility:* If you want 282- *Perform Steps to Apply for Yocto Project Compatibility:* If you want
283 permission to use the Yocto Project Compatibility logo with your 283 permission to use the Yocto Project Compatibility logo with your
284 layer or application that uses your layer, perform the steps to apply 284 layer or application that uses your layer, perform the steps to apply
285 for compatibility. See the "`Making Sure Your Layer is Compatible 285 for compatibility. See the
286 With Yocto 286 ":ref:`dev-manual/common-tasks:making sure your layer is compatible with yocto project`"
287 Project <#making-sure-your-layer-is-compatible-with-yocto-project>`__"
288 section for more information. 287 section for more information.
289 288
290- *Follow the Layer Naming Convention:* Store custom layers in a Git 289- *Follow the Layer Naming Convention:* Store custom layers in a Git
@@ -1247,8 +1246,7 @@ the recipe.
1247 your layer such that it can be found. 1246 your layer such that it can be found.
1248 1247
1249 You can find more information on how layers are structured in the 1248 You can find more information on how layers are structured in the
1250 "`Understanding and Creating 1249 ":ref:`dev-manual/common-tasks:understanding and creating layers`" section.
1251 Layers <#understanding-and-creating-layers>`__" section.
1252 1250
1253- *Naming Your Recipe:* When you name your recipe, you need to follow 1251- *Naming Your Recipe:* When you name your recipe, you need to follow
1254 this naming convention: 1252 this naming convention:
@@ -1364,7 +1362,7 @@ extension (e.g. ``.tar``, ``.tar.gz``, ``.tar.bz2``, ``.zip``, and so
1364forth), are automatically extracted during the 1362forth), are automatically extracted during the
1365:ref:`ref-tasks-unpack` task. For 1363:ref:`ref-tasks-unpack` task. For
1366another example that specifies these types of files, see the 1364another example that specifies these types of files, see the
1367"`Autotooled Package <#new-recipe-autotooled-package>`__" section. 1365":ref:`dev-manual/common-tasks:autotooled package`" section.
1368 1366
1369Another way of specifying source is from an SCM. For Git repositories, 1367Another way of specifying source is from an SCM. For Git repositories,
1370you must specify :term:`SRCREV` and 1368you must specify :term:`SRCREV` and
@@ -1445,15 +1443,14 @@ and searches specific directories in a certain order:
1445``${``\ :term:`BPN`\ ``}``, and 1443``${``\ :term:`BPN`\ ``}``, and
1446``files``. The directories are assumed to be subdirectories of the 1444``files``. The directories are assumed to be subdirectories of the
1447directory in which the recipe or append file resides. For another 1445directory in which the recipe or append file resides. For another
1448example that specifies these types of files, see the "`Single .c File 1446example that specifies these types of files, see the
1449Package (Hello 1447":ref:`dev-manual/common-tasks:single .c file package (hello world!)`" section.
1450World!) <#new-recipe-single-c-file-package-hello-world>`__" section.
1451 1448
1452The previous example also specifies a patch file. Patch files are files 1449The previous example also specifies a patch file. Patch files are files
1453whose names usually end in ``.patch`` or ``.diff`` but can end with 1450whose names usually end in ``.patch`` or ``.diff`` but can end with
1454compressed suffixes such as ``diff.gz`` and ``patch.bz2``, for example. 1451compressed suffixes such as ``diff.gz`` and ``patch.bz2``, for example.
1455The build system automatically applies patches as described in the 1452The build system automatically applies patches as described in the
1456"`Patching Code <#new-recipe-patching-code>`__" section. 1453":ref:`dev-manual/common-tasks:patching code`" section.
1457 1454
1458Unpacking Code 1455Unpacking Code
1459-------------- 1456--------------
@@ -1543,7 +1540,7 @@ variables:
1543 appropriate files in the ``LIC_FILES_CHKSUM`` variable with incorrect 1540 appropriate files in the ``LIC_FILES_CHKSUM`` variable with incorrect
1544 md5 strings, attempt to build the software, and then note the 1541 md5 strings, attempt to build the software, and then note the
1545 resulting error messages that will report the correct md5 strings. 1542 resulting error messages that will report the correct md5 strings.
1546 See the "`Fetching Code <#new-recipe-fetching-code>`__" section for 1543 See the ":ref:`dev-manual/common-tasks:fetching code`" section for
1547 additional information. 1544 additional information.
1548 1545
1549 Here is an example that assumes the software has a ``COPYING`` file: 1546 Here is an example that assumes the software has a ``COPYING`` file:
@@ -1787,8 +1784,8 @@ Here are some common issues that cause failures.
1787 1784
1788 PARALLEL_MAKE = "" 1785 PARALLEL_MAKE = ""
1789 1786
1790 For information on parallel Makefile issues, see the "`Debugging 1787 For information on parallel Makefile issues, see the
1791 Parallel Make Races <#debugging-parallel-make-races>`__" section. 1788 ":ref:`dev-manual/common-tasks:debugging parallel make races`" section.
1792 1789
1793- *Improper host path usage:* This failure applies to recipes building 1790- *Improper host path usage:* This failure applies to recipes building
1794 for the target or ``nativesdk`` only. The failure occurs when the 1791 for the target or ``nativesdk`` only. The failure occurs when the
@@ -1854,8 +1851,7 @@ the software being built:
1854 ``PREFIX=${D}``, ``INSTALLROOT=${D}``, and so forth). 1851 ``PREFIX=${D}``, ``INSTALLROOT=${D}``, and so forth).
1855 1852
1856 For an example recipe using ``make install``, see the 1853 For an example recipe using ``make install``, see the
1857 "`Makefile-Based Package <#new-recipe-makefile-based-package>`__" 1854 ":ref:`dev-manual/common-tasks:makefile-based package`" section.
1858 section.
1859 1855
1860- *Manual:* You need to define a ``do_install`` function in your 1856- *Manual:* You need to define a ``do_install`` function in your
1861 recipe. The function must first use ``install -d`` to create the 1857 recipe. The function must first use ``install -d`` to create the
@@ -1990,14 +1986,13 @@ take. The following list describes the process:
1990 ``do_install(_append)``, and so forth as needed. 1986 ``do_install(_append)``, and so forth as needed.
1991 1987
1992- *Splitting an Application into Multiple Packages*: If you need to 1988- *Splitting an Application into Multiple Packages*: If you need to
1993 split an application into several packages, see the "`Splitting an 1989 split an application into several packages, see the
1994 Application into Multiple 1990 ":ref:`dev-manual/common-tasks:splitting an application into multiple packages`"
1995 Packages <#splitting-an-application-into-multiple-packages>`__"
1996 section for an example. 1991 section for an example.
1997 1992
1998- *Installing a Post-Installation Script*: For an example showing how 1993- *Installing a Post-Installation Script*: For an example showing how
1999 to install a post-installation script, see the "`Post-Installation 1994 to install a post-installation script, see the
2000 Scripts <#new-recipe-post-installation-scripts>`__" section. 1995 ":ref:`dev-manual/common-tasks:post-installation scripts`" section.
2001 1996
2002- *Marking Package Architecture*: Depending on what your recipe is 1997- *Marking Package Architecture*: Depending on what your recipe is
2003 building and how it is configured, it might be important to mark the 1998 building and how it is configured, it might be important to mark the
@@ -2172,9 +2167,8 @@ Properly Versioning Pre-Release Recipes
2172Sometimes the name of a recipe can lead to versioning problems when the 2167Sometimes the name of a recipe can lead to versioning problems when the
2173recipe is upgraded to a final release. For example, consider the 2168recipe is upgraded to a final release. For example, consider the
2174``irssi_0.8.16-rc1.bb`` recipe file in the list of example recipes in 2169``irssi_0.8.16-rc1.bb`` recipe file in the list of example recipes in
2175the "`Storing and Naming the 2170the ":ref:`dev-manual/common-tasks:storing and naming the recipe`" section.
2176Recipe <#new-recipe-storing-and-naming-the-recipe>`__" section. This 2171This recipe is at a release candidate stage (i.e. "rc1"). When the recipe is
2177recipe is at a release candidate stage (i.e. "rc1"). When the recipe is
2178released, the recipe filename becomes ``irssi_0.8.16.bb``. The version 2172released, the recipe filename becomes ``irssi_0.8.16.bb``. The version
2179change from ``0.8.16-rc1`` to ``0.8.16`` is seen as a decrease by the 2173change from ``0.8.16-rc1`` to ``0.8.16`` is seen as a decrease by the
2180build system and package managers, so the resulting packages will not 2174build system and package managers, so the resulting packages will not
@@ -2258,8 +2252,7 @@ software you built runs correctly. To accomplish runtime testing, add
2258the build's output packages to your image and test them on the target. 2252the build's output packages to your image and test them on the target.
2259 2253
2260For information on how to customize your image by adding specific 2254For information on how to customize your image by adding specific
2261packages, see the "`Customizing 2255packages, see ":ref:`dev-manual/common-tasks:customizing images`" section.
2262Images <#usingpoky-extend-customimage>`__" section.
2263 2256
2264Examples 2257Examples
2265-------- 2258--------
@@ -2309,8 +2302,8 @@ directory BitBake uses for the build.
2309 2302
2310By default, the ``helloworld``, ``helloworld-dbg``, and 2303By default, the ``helloworld``, ``helloworld-dbg``, and
2311``helloworld-dev`` packages are built. For information on how to 2304``helloworld-dev`` packages are built. For information on how to
2312customize the packaging process, see the "`Splitting an Application into 2305customize the packaging process, see the
2313Multiple Packages <#splitting-an-application-into-multiple-packages>`__" 2306":ref:`dev-manual/common-tasks:splitting an application into multiple packages`"
2314section. 2307section.
2315 2308
2316Autotooled Package 2309Autotooled Package
@@ -3423,9 +3416,8 @@ Follow these general steps:
34231. *Find the Source Code:* Temporary source code used by the 34161. *Find the Source Code:* Temporary source code used by the
3424 OpenEmbedded build system is kept in the 3417 OpenEmbedded build system is kept in the
3425 :term:`Build Directory`. See the 3418 :term:`Build Directory`. See the
3426 "`Finding Temporary Source 3419 ":ref:`dev-manual/common-tasks:finding temporary source code`" section to
3427 Code <#finding-the-temporary-source-code>`__" section to learn how to 3420 learn how to locate the directory that has the temporary source code for a
3428 locate the directory that has the temporary source code for a
3429 particular package. 3421 particular package.
3430 3422
34312. *Change Your Working Directory:* You need to be in the directory that 34232. *Change Your Working Directory:* You need to be in the directory that
@@ -3994,24 +3986,21 @@ perform to create distributions with smaller root filesystems, achieve
3994faster boot times, maintain your critical functionality, and avoid 3986faster boot times, maintain your critical functionality, and avoid
3995initial RAM disks: 3987initial RAM disks:
3996 3988
3997- `Determine your goals and guiding 3989- :ref:`Determine your goals and guiding principles
3998 principles. <#goals-and-guiding-principles>`__ 3990 <dev-manual/common-tasks:goals and guiding principles>`
3999 3991
4000- `Understand what contributes to your image 3992- :ref:`dev-manual/common-tasks:understand what contributes to your image size`
4001 size. <#understand-what-gives-your-image-size>`__
4002 3993
4003- `Reduce the size of the root 3994- :ref:`Reduce the size of the root filesystem
4004 filesystem. <#trim-the-root-filesystem>`__ 3995 <dev-manual/common-tasks:trim the root filesystem>`
4005 3996
4006- `Reduce the size of the kernel. <#trim-the-kernel>`__ 3997- :ref:`Reduce the size of the kernel <dev-manual/common-tasks:trim the kernel>`
4007 3998
4008- `Eliminate packaging 3999- :ref:`dev-manual/common-tasks:remove package management requirements`
4009 requirements. <#remove-package-management-requirements>`__
4010 4000
4011- `Look for other ways to minimize 4001- :ref:`dev-manual/common-tasks:look for other ways to minimize size`
4012 size. <#look-for-other-ways-to-minimize-size>`__
4013 4002
4014- `Iterate on the process. <#iterate-on-the-process>`__ 4003- :ref:`dev-manual/common-tasks:iterate on the process`
4015 4004
4016Goals and Guiding Principles 4005Goals and Guiding Principles
4017~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4006~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4031,8 +4020,8 @@ very small distributions:
4031- Leverage the device-specific options. 4020- Leverage the device-specific options.
4032 4021
4033- Work in a separate layer so that you keep changes isolated. For 4022- Work in a separate layer so that you keep changes isolated. For
4034 information on how to create layers, see the "`Understanding and 4023 information on how to create layers, see the
4035 Creating Layers <#understanding-and-creating-layers>`__" section. 4024 ":ref:`dev-manual/common-tasks:understanding and creating layers`" section.
4036 4025
4037Understand What Contributes to Your Image Size 4026Understand What Contributes to Your Image Size
4038~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4027~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -4576,13 +4565,13 @@ directory:
4576 If you do have recipes that use ``AUTOREV``, you can take steps to 4565 If you do have recipes that use ``AUTOREV``, you can take steps to
4577 still use the recipes in an offline build. Do the following: 4566 still use the recipes in an offline build. Do the following:
4578 4567
4579 1. Use a configuration generated by enabling `build 4568 1. Use a configuration generated by enabling :ref:`build
4580 history <#maintaining-build-output-quality>`__. 4569 history <dev-manual/common-tasks:maintaining build output quality>`.
4581 4570
4582 2. Use the ``buildhistory-collect-srcrevs`` command to collect the 4571 2. Use the ``buildhistory-collect-srcrevs`` command to collect the
4583 stored ``SRCREV`` values from the build's history. For more 4572 stored ``SRCREV`` values from the build's history. For more
4584 information on collecting these values, see the "`Build History 4573 information on collecting these values, see the
4585 Package Information <#build-history-package-information>`__" 4574 ":ref:`dev-manual/common-tasks:build history package information`"
4586 section. 4575 section.
4587 4576
4588 3. Once you have the correct source revisions, you can modify 4577 3. Once you have the correct source revisions, you can modify
@@ -4706,16 +4695,16 @@ Libraries are an integral part of your system. This section describes
4706some common practices you might find helpful when working with libraries 4695some common practices you might find helpful when working with libraries
4707to build your system: 4696to build your system:
4708 4697
4709- `How to include static library 4698- :ref:`How to include static library files
4710 files <#including-static-library-files>`__ 4699 <dev-manual/common-tasks:including static library files>`
4711 4700
4712- `How to use the Multilib feature to combine multiple versions of 4701- :ref:`How to use the Multilib feature to combine multiple versions of
4713 library files into a single 4702 library files into a single image
4714 image <#combining-multiple-versions-library-files-into-one-image>`__ 4703 <dev-manual/common-tasks:combining multiple versions of library files into one image>`
4715 4704
4716- `How to install multiple versions of the same library in parallel on 4705- :ref:`How to install multiple versions of the same library in parallel on
4717 the same 4706 the same system
4718 system <#installing-multiple-versions-of-the-same-library>`__ 4707 <dev-manual/common-tasks:installing multiple versions of the same library>`
4719 4708
4720Including Static Library Files 4709Including Static Library Files
4721------------------------------ 4710------------------------------
@@ -5053,7 +5042,7 @@ because the library is produced for the target architecture, but its
5053code needs to be executed on the build host. This problem is solved with 5042code needs to be executed on the build host. This problem is solved with
5054the OpenEmbedded build system by running the code through QEMU, which 5043the OpenEmbedded build system by running the code through QEMU, which
5055allows precisely that. Unfortunately, QEMU does not always work 5044allows precisely that. Unfortunately, QEMU does not always work
5056perfectly as mentioned in the "`Known Issues <#known-issues>`__" 5045perfectly as mentioned in the ":ref:`dev-manual/common-tasks:known issues`"
5057section. 5046section.
5058 5047
5059Enabling the Generation of Introspection Data 5048Enabling the Generation of Introspection Data
@@ -5225,11 +5214,11 @@ OpenEmbedded build artifacts. Image generation is driven by partitioning
5225commands contained in an Openembedded kickstart file (``.wks``) 5214commands contained in an Openembedded kickstart file (``.wks``)
5226specified either directly on the command line or as one of a selection 5215specified either directly on the command line or as one of a selection
5227of canned kickstart files as shown with the ``wic list images`` command 5216of canned kickstart files as shown with the ``wic list images`` command
5228in the "`Using an Existing Kickstart 5217in the
5229File <#using-a-provided-kickstart-file>`__" section. When you apply the 5218":ref:`dev-manual/common-tasks:generate an image using an existing kickstart file`"
5230command to a given set of build artifacts, the result is an image or set 5219section. When you apply the command to a given set of build artifacts, the
5231of images that can be directly written onto media and used on a 5220result is an image or set of images that can be directly written onto media and
5232particular system. 5221used on a particular system.
5233 5222
5234.. note:: 5223.. note::
5235 5224
@@ -5240,8 +5229,8 @@ particular system.
5240The ``wic`` command and the infrastructure it is based on is by 5229The ``wic`` command and the infrastructure it is based on is by
5241definition incomplete. The purpose of the command is to allow the 5230definition incomplete. The purpose of the command is to allow the
5242generation of customized images, and as such, was designed to be 5231generation of customized images, and as such, was designed to be
5243completely extensible through a plugin interface. See the "`Using the 5232completely extensible through a plugin interface. See the
5244Wic PlugIn Interface <#wic-using-the-wic-plugin-interface>`__" section 5233":ref:`dev-manual/common-tasks:using the wic plugin interface`" section
5245for information on these plugins. 5234for information on these plugins.
5246 5235
5247This section provides some background information on Wic, describes what 5236This section provides some background information on Wic, describes what
@@ -5678,7 +5667,7 @@ Wic Examples
5678 5667
5679This section provides several examples that show how to use the Wic 5668This section provides several examples that show how to use the Wic
5680utility. All the examples assume the list of requirements in the 5669utility. All the examples assume the list of requirements in the
5681"`Requirements <#wic-requirements>`__" section have been met. The 5670":ref:`dev-manual/common-tasks:requirements`" section have been met. The
5682examples assume the previously generated image is 5671examples assume the previously generated image is
5683``core-image-minimal``. 5672``core-image-minimal``.
5684 5673
@@ -6093,8 +6082,7 @@ more secure:
6093 6082
6094- Ensure you remove or disable debugging functionality before producing 6083- Ensure you remove or disable debugging functionality before producing
6095 the final image. For information on how to do this, see the 6084 the final image. For information on how to do this, see the
6096 "`Considerations Specific to the OpenEmbedded Build 6085 ":ref:`dev-manual/common-tasks:considerations specific to the openembedded build system`"
6097 System <#considerations-specific-to-the-openembedded-build-system>`__"
6098 section. 6086 section.
6099 6087
6100- Ensure you have no network services listening that are not needed. 6088- Ensure you have no network services listening that are not needed.
@@ -6275,17 +6263,17 @@ layer. The following steps provide some more detail:
6275 distro-specific configuration files that are included by an 6263 distro-specific configuration files that are included by an
6276 existing recipe, you should add an append file (``.bbappend``) for 6264 existing recipe, you should add an append file (``.bbappend``) for
6277 those. For general information and recommendations on how to add 6265 those. For general information and recommendations on how to add
6278 recipes to your layer, see the "`Creating Your Own 6266 recipes to your layer, see the
6279 Layer <#creating-your-own-layer>`__" and "`Following Best 6267 ":ref:`dev-manual/common-tasks:creating your own layer`" and
6280 Practices When Creating 6268 ":ref:`dev-manual/common-tasks:following best practices when creating layers`"
6281 Layers <#best-practices-to-follow-when-creating-layers>`__"
6282 sections. 6269 sections.
6283 6270
6284 - Add any image recipes that are specific to your distribution. 6271 - Add any image recipes that are specific to your distribution.
6285 6272
6286 - Add a ``psplash`` append file for a branded splash screen. For 6273 - Add a ``psplash`` append file for a branded splash screen. For
6287 information on append files, see the "`Using .bbappend Files in 6274 information on append files, see the
6288 Your Layer <#using-bbappend-files>`__" section. 6275 ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`"
6276 section.
6289 6277
6290 - Add any other append files to make custom changes that are 6278 - Add any other append files to make custom changes that are
6291 specific to individual recipes. 6279 specific to individual recipes.
@@ -6383,29 +6371,22 @@ Working with Packages
6383 6371
6384This section describes a few tasks that involve packages: 6372This section describes a few tasks that involve packages:
6385 6373
6386- `Excluding packages from an 6374- :ref:`dev-manual/common-tasks:excluding packages from an image`
6387 image <#excluding-packages-from-an-image>`__
6388 6375
6389- `Incrementing a binary package 6376- :ref:`dev-manual/common-tasks:incrementing a package version`
6390 version <#incrementing-a-binary-package-version>`__
6391 6377
6392- `Handling optional module 6378- :ref:`dev-manual/common-tasks:handling optional module packaging`
6393 packaging <#handling-optional-module-packaging>`__
6394 6379
6395- `Using runtime package 6380- :ref:`dev-manual/common-tasks:using runtime package management`
6396 management <#using-runtime-package-management>`__
6397 6381
6398- `Generating and using signed 6382- :ref:`dev-manual/common-tasks:generating and using signed packages`
6399 packages <#generating-and-using-signed-packages>`__
6400 6383
6401- `Setting up and running package test 6384- :ref:`Setting up and running package test
6402 (ptest) <#testing-packages-with-ptest>`__ 6385 (ptest) <dev-manual/common-tasks:testing packages with ptest>`
6403 6386
6404- `Creating node package manager (NPM) 6387- :ref:`dev-manual/common-tasks:creating node package manager (npm) packages`
6405 packages <#creating-node-package-manager-npm-packages>`__
6406 6388
6407- `Adding custom metadata to 6389- :ref:`dev-manual/common-tasks:adding custom metadata to packages`
6408 packages <#adding-custom-metadata-to-packages>`__
6409 6390
6410Excluding Packages from an Image 6391Excluding Packages from an Image
6411-------------------------------- 6392--------------------------------
@@ -6494,9 +6475,8 @@ much preferred over a manual system. In either system, the main
6494requirement is that binary package version numbering increases in a 6475requirement is that binary package version numbering increases in a
6495linear fashion and that a number of version components exist that 6476linear fashion and that a number of version components exist that
6496support that linear progression. For information on how to ensure 6477support that linear progression. For information on how to ensure
6497package revisioning remains linear, see the "`Automatically Incrementing 6478package revisioning remains linear, see the
6498a Binary Package Revision 6479":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
6499Number <#automatically-incrementing-a-binary-package-revision-number>`__"
6500section. 6480section.
6501 6481
6502The following three sections provide related information on the PR 6482The following three sections provide related information on the PR
@@ -6587,8 +6567,8 @@ each building system's ``local.conf`` file:
6587 BUILDHISTORY_COMMIT = "1" 6567 BUILDHISTORY_COMMIT = "1"
6588 6568
6589For information on build 6569For information on build
6590history, see the "`Maintaining Build Output 6570history, see the
6591Quality <#maintaining-build-output-quality>`__" section. 6571":ref:`dev-manual/common-tasks:maintaining build output quality`" section.
6592 6572
6593.. note:: 6573.. note::
6594 6574
@@ -8591,8 +8571,8 @@ options exist:
8591 it the same IP address for each reboot. 8571 it the same IP address for each reboot.
8592 8572
8593 If you choose "SystemdbootTarget", there are additional requirements 8573 If you choose "SystemdbootTarget", there are additional requirements
8594 and considerations. See the "`Selecting 8574 and considerations. See the
8595 SystemdbootTarget <#selecting-systemdboottarget>`__" section, which 8575 ":ref:`dev-manual/common-tasks:selecting systemdboottarget`" section, which
8596 follows, for more information. 8576 follows, for more information.
8597 8577
8598- *"BeagleBoneTarget":* Choose "BeagleBoneTarget" if you are deploying 8578- *"BeagleBoneTarget":* Choose "BeagleBoneTarget" if you are deploying
@@ -8624,7 +8604,7 @@ Selecting SystemdbootTarget
8624 8604
8625If you did not set ``TEST_TARGET`` to "SystemdbootTarget", then you do 8605If you did not set ``TEST_TARGET`` to "SystemdbootTarget", then you do
8626not need any information in this section. You can skip down to the 8606not need any information in this section. You can skip down to the
8627"`Running Tests <#qemu-image-running-tests>`__" section. 8607":ref:`dev-manual/common-tasks:running tests`" section.
8628 8608
8629If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to 8609If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to
8630perform a one-time setup of your master image by doing the following: 8610perform a one-time setup of your master image by doing the following:
@@ -9090,13 +9070,11 @@ situations.
9090The following list shows the debugging topics in the remainder of this 9070The following list shows the debugging topics in the remainder of this
9091section: 9071section:
9092 9072
9093- "`Viewing Logs from Failed 9073- ":ref:`dev-manual/common-tasks:viewing logs from failed tasks`" describes
9094 Tasks <#dev-debugging-viewing-logs-from-failed-tasks>`__" describes
9095 how to find and view logs from tasks that failed during the build 9074 how to find and view logs from tasks that failed during the build
9096 process. 9075 process.
9097 9076
9098- "`Viewing Variable 9077- ":ref:`dev-manual/common-tasks:viewing variable values`" describes how to
9099 Values <#dev-debugging-viewing-variable-values>`__" describes how to
9100 use the BitBake ``-e`` option to examine variable values after a 9078 use the BitBake ``-e`` option to examine variable values after a
9101 recipe has been parsed. 9079 recipe has been parsed.
9102 9080
@@ -9105,51 +9083,47 @@ section:
9105 :term:`PKGDATA_DIR` and 9083 :term:`PKGDATA_DIR` and
9106 display package-related information for built packages. 9084 display package-related information for built packages.
9107 9085
9108- "`Viewing Dependencies Between Recipes and 9086- ":ref:`dev-manual/common-tasks:viewing dependencies between recipes and tasks`"
9109 Tasks <#dev-viewing-dependencies-between-recipes-and-tasks>`__"
9110 describes how to use the BitBake ``-g`` option to display recipe 9087 describes how to use the BitBake ``-g`` option to display recipe
9111 dependency information used during the build. 9088 dependency information used during the build.
9112 9089
9113- "`Viewing Task Variable 9090- ":ref:`dev-manual/common-tasks:viewing task variable dependencies`" describes
9114 Dependencies <#dev-viewing-task-variable-dependencies>`__" describes
9115 how to use the ``bitbake-dumpsig`` command in conjunction with key 9091 how to use the ``bitbake-dumpsig`` command in conjunction with key
9116 subdirectories in the 9092 subdirectories in the
9117 :term:`Build Directory` to determine 9093 :term:`Build Directory` to determine
9118 variable dependencies. 9094 variable dependencies.
9119 9095
9120- "`Running Specific Tasks <#dev-debugging-taskrunning>`__" describes 9096- ":ref:`dev-manual/common-tasks:running specific tasks`" describes
9121 how to use several BitBake options (e.g. ``-c``, ``-C``, and ``-f``) 9097 how to use several BitBake options (e.g. ``-c``, ``-C``, and ``-f``)
9122 to run specific tasks in the build chain. It can be useful to run 9098 to run specific tasks in the build chain. It can be useful to run
9123 tasks "out-of-order" when trying isolate build issues. 9099 tasks "out-of-order" when trying isolate build issues.
9124 9100
9125- "`General BitBake Problems <#dev-debugging-bitbake>`__" describes how 9101- ":ref:`dev-manual/common-tasks:general bitbake problems`" describes how
9126 to use BitBake's ``-D`` debug output option to reveal more about what 9102 to use BitBake's ``-D`` debug output option to reveal more about what
9127 BitBake is doing during the build. 9103 BitBake is doing during the build.
9128 9104
9129- "`Building with No Dependencies <#dev-debugging-buildfile>`__" 9105- ":ref:`dev-manual/common-tasks:building with no dependencies`"
9130 describes how to use the BitBake ``-b`` option to build a recipe 9106 describes how to use the BitBake ``-b`` option to build a recipe
9131 while ignoring dependencies. 9107 while ignoring dependencies.
9132 9108
9133- "`Recipe Logging Mechanisms <#recipe-logging-mechanisms>`__" 9109- ":ref:`dev-manual/common-tasks:recipe logging mechanisms`"
9134 describes how to use the many recipe logging functions to produce 9110 describes how to use the many recipe logging functions to produce
9135 debugging output and report errors and warnings. 9111 debugging output and report errors and warnings.
9136 9112
9137- "`Debugging Parallel Make Races <#debugging-parallel-make-races>`__" 9113- ":ref:`dev-manual/common-tasks:debugging parallel make races`"
9138 describes how to debug situations where the build consists of several 9114 describes how to debug situations where the build consists of several
9139 parts that are run simultaneously and when the output or result of 9115 parts that are run simultaneously and when the output or result of
9140 one part is not ready for use with a different part of the build that 9116 one part is not ready for use with a different part of the build that
9141 depends on that output. 9117 depends on that output.
9142 9118
9143- "`Debugging With the GNU Project Debugger (GDB) 9119- ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`"
9144 Remotely <#platdev-gdb-remotedebug>`__" describes how to use GDB to 9120 describes how to use GDB to allow you to examine running programs, which can
9145 allow you to examine running programs, which can help you fix 9121 help you fix problems.
9146 problems.
9147 9122
9148- "`Debugging with the GNU Project Debugger (GDB) on the 9123- ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) on the target`"
9149 Target <#debugging-with-the-gnu-project-debugger-gdb-on-the-target>`__"
9150 describes how to use GDB directly on target hardware for debugging. 9124 describes how to use GDB directly on target hardware for debugging.
9151 9125
9152- "`Other Debugging Tips <#dev-other-debugging-others>`__" describes 9126- ":ref:`dev-manual/common-tasks:other debugging tips`" describes
9153 miscellaneous debugging tips that can be useful. 9127 miscellaneous debugging tips that can be useful.
9154 9128
9155Viewing Logs from Failed Tasks 9129Viewing Logs from Failed Tasks
@@ -9457,8 +9431,8 @@ state (sstate) task can be a useful debugging aid. This information is
9457available in signature information (``siginfo``) files in 9431available in signature information (``siginfo``) files in
9458:term:`SSTATE_DIR`. For 9432:term:`SSTATE_DIR`. For
9459information on how to view and interpret information in ``siginfo`` 9433information on how to view and interpret information in ``siginfo``
9460files, see the "`Viewing Task Variable 9434files, see the
9461Dependencies <#dev-viewing-task-variable-dependencies>`__" section. 9435":ref:`dev-manual/common-tasks:viewing task variable dependencies`" section.
9462 9436
9463For conceptual information on shared state, see the 9437For conceptual information on shared state, see the
9464":ref:`overview-manual/concepts:shared state`" 9438":ref:`overview-manual/concepts:shared state`"
@@ -9877,9 +9851,8 @@ Once the local build for "neard" completes, start a ``devshell`` build:
9877 9851
9878 $ bitbake neard -c devshell 9852 $ bitbake neard -c devshell
9879 9853
9880For information on how to use a 9854For information on how to use a ``devshell``, see the
9881``devshell``, see the "`Using a Development 9855":ref:`dev-manual/common-tasks:using a development shell`" section.
9882Shell <#platdev-appdev-devshell>`__" section.
9883 9856
9884In the ``devshell``, do the following: 9857In the ``devshell``, do the following:
9885:: 9858::
@@ -9921,7 +9894,7 @@ to patch the ``Makefile.am`` file, which is generated from
9921 File Makefile.am added to patch patches/parallelmake.patch 9894 File Makefile.am added to patch patches/parallelmake.patch
9922 9895
9923For more information on using Quilt, see the 9896For more information on using Quilt, see the
9924"`Using Quilt in Your Workflow <#using-a-quilt-workflow>`__" section. 9897":ref:`dev-manual/common-tasks:using quilt in your workflow`" section.
9925 9898
9926At this point you need to make the edits to ``Makefile.am`` to add the 9899At this point you need to make the edits to ``Makefile.am`` to add the
9927missing dependency. For our example, you have to add the following line 9900missing dependency. For our example, you have to add the following line
@@ -9987,9 +9960,9 @@ The build should work without issue.
9987 9960
9988As with all solved problems, if they originated upstream, you need to 9961As with all solved problems, if they originated upstream, you need to
9989submit the fix for the recipe in OE-Core and upstream so that the 9962submit the fix for the recipe in OE-Core and upstream so that the
9990problem is taken care of at its source. See the "`Submitting a Change to 9963problem is taken care of at its source. See the
9991the Yocto Project <#how-to-submit-a-change>`__" section for more 9964":ref:`dev-manual/common-tasks:submitting a change to the yocto project`"
9992information. 9965section for more information.
9993 9966
9994Debugging With the GNU Project Debugger (GDB) Remotely 9967Debugging With the GNU Project Debugger (GDB) Remotely
9995------------------------------------------------------ 9968------------------------------------------------------
@@ -10363,8 +10336,9 @@ Here are some other tips that you might find useful:
10363 :yocto_bugs:`Bugzilla <>`. For information on 10336 :yocto_bugs:`Bugzilla <>`. For information on
10364 how to submit a bug against the Yocto Project, see the Yocto Project 10337 how to submit a bug against the Yocto Project, see the Yocto Project
10365 Bugzilla :yocto_wiki:`wiki page </Bugzilla_Configuration_and_Bug_Tracking>` 10338 Bugzilla :yocto_wiki:`wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
10366 and the "`Submitting a Defect Against the Yocto 10339 and the
10367 Project <#submitting-a-defect-against-the-yocto-project>`__" section. 10340 ":ref:`dev-manual/common-tasks:submitting a defect against the yocto project`"
10341 section.
10368 10342
10369 .. note:: 10343 .. note::
10370 10344
@@ -10619,8 +10593,9 @@ Using Email to Submit a Patch
10619 10593
10620Depending on the components changed, you need to submit the email to a 10594Depending on the components changed, you need to submit the email to a
10621specific mailing list. For some guidance on which mailing list to use, 10595specific mailing list. For some guidance on which mailing list to use,
10622see the `list <#figuring-out-the-mailing-list-to-use>`__ at the 10596see the
10623beginning of this section. For a description of all the available 10597:ref:`list <dev-manual/common-tasks:submitting a change to the yocto project>`
10598at the beginning of this section. For a description of all the available
10624mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the 10599mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
10625Yocto Project Reference Manual. 10600Yocto Project Reference Manual.
10626 10601
@@ -11034,7 +11009,7 @@ file. For example, to enable the
11034``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` package, you 11009``poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly`` package, you
11035could add either the string "commercial_gst-plugins-ugly" or the more 11010could add either the string "commercial_gst-plugins-ugly" or the more
11036general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the 11011general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the
11037"`License Flag Matching <#license-flag-matching>`__" section for a full 11012":ref:`dev-manual/common-tasks:license flag matching`" section for a full
11038explanation of how ``LICENSE_FLAGS`` matching works. Here is the 11013explanation of how ``LICENSE_FLAGS`` matching works. Here is the
11039example: 11014example:
11040:: 11015::
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index c6bb9e9776..92799d6d25 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -306,8 +306,8 @@ present, the toolchain is also automatically used.
306 tarball by using the ``runqemu-extract-sdk`` command. After 306 tarball by using the ``runqemu-extract-sdk`` command. After
307 running the command, you must then point the ``runqemu`` script to 307 running the command, you must then point the ``runqemu`` script to
308 the extracted directory instead of a root filesystem image file. 308 the extracted directory instead of a root filesystem image file.
309 See the "`Running Under a Network File System (NFS) 309 See the
310 Server <#qemu-running-under-a-network-file-system-nfs-server>`__" 310 ":ref:`dev-manual/qemu:running under a network file system (nfs) server`"
311 section for more information. 311 section for more information.
312 312
313QEMU Command-Line Syntax 313QEMU Command-Line Syntax
@@ -452,7 +452,7 @@ command line:
452 or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the 452 or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the
453 following conditions must be met: 453 following conditions must be met:
454 454
455 - `kvm <#kvm-cond>`__ option conditions must be met. 455 - ``kvm`` option conditions defined above must be met.
456 456
457 - Your build host has to have virtio net device, which are 457 - Your build host has to have virtio net device, which are
458 ``/dev/vhost-net``. 458 ``/dev/vhost-net``.
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index efe369c751..39036183b0 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -230,8 +230,8 @@ particular working environment and set of practices.
230 - Separate the project's Metadata and code by using separate Git 230 - Separate the project's Metadata and code by using separate Git
231 repositories. See the ":ref:`overview-manual/development-environment:yocto project source repositories`" 231 repositories. See the ":ref:`overview-manual/development-environment:yocto project source repositories`"
232 section in the Yocto Project Overview and Concepts Manual for 232 section in the Yocto Project Overview and Concepts Manual for
233 information on these repositories. See the "`Locating Yocto 233 information on these repositories. See the
234 Project Source Files <#locating-yocto-project-source-files>`__" 234 ":ref:`dev-manual/start:locating yocto project source files`"
235 section for information on how to set up local Git repositories 235 section for information on how to set up local Git repositories
236 for related upstream Yocto Project Git repositories. 236 for related upstream Yocto Project Git repositories.
237 237
@@ -655,8 +655,7 @@ The :yocto_home:`Yocto Project Website <>` uses a "DOWNLOADS" page
655from which you can locate and download tarballs of any Yocto Project 655from which you can locate and download tarballs of any Yocto Project
656release. Rather than Git repositories, these files represent snapshot 656release. Rather than Git repositories, these files represent snapshot
657tarballs similar to the tarballs located in the Index of Releases 657tarballs similar to the tarballs located in the Index of Releases
658described in the "`Accessing Index of 658described in the ":ref:`dev-manual/start:accessing index of releases`" section.
659Releases <#accessing-index-of-releases>`__" section.
660 659
661.. note:: 660.. note::
662 661
@@ -759,9 +758,9 @@ Follow these steps to create a local version of the upstream
759 "master" branch, which results in a snapshot of the latest 758 "master" branch, which results in a snapshot of the latest
760 development changes for "master". For information on how to check out 759 development changes for "master". For information on how to check out
761 a specific development branch or on how to check out a local branch 760 a specific development branch or on how to check out a local branch
762 based on a tag name, see the "`Checking Out By Branch in 761 based on a tag name, see the
763 Poky <#checking-out-by-branch-in-poky>`__" and `Checking Out By Tag 762 ":ref:`dev-manual/start:checking out by branch in poky`" and
764 in Poky <#checkout-out-by-tag-in-poky>`__" sections, respectively. 763 ":ref:`dev-manual/start:checking out by tag in poky`" sections, respectively.
765 764
766 Once the local repository is created, you can change to that 765 Once the local repository is created, you can change to that
767 directory and check its status. Here, the single "master" branch 766 directory and check its status. Here, the single "master" branch