diff options
23 files changed, 301 insertions, 323 deletions
diff --git a/documentation/README b/documentation/README index b491e46a1d..176c6db35b 100644 --- a/documentation/README +++ b/documentation/README | |||
@@ -259,6 +259,9 @@ websites. | |||
259 | More information can be found here: | 259 | More information can be found here: |
260 | https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html. | 260 | https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html. |
261 | 261 | ||
262 | Anchor (<#link>) links are forbidden as they are not checked by Sphinx during | ||
263 | the build and may be broken without knowing about it. | ||
264 | |||
262 | References | 265 | References |
263 | ========== | 266 | ========== |
264 | 267 | ||
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: | |||
155 | 5. *Optionally Test for Compatibility:* If you want permission to use | 155 | 5. *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 | ||
162 | Following Best Practices When Creating Layers | 162 | Following 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 | |||
1364 | forth), are automatically extracted during the | 1362 | forth), are automatically extracted during the |
1365 | :ref:`ref-tasks-unpack` task. For | 1363 | :ref:`ref-tasks-unpack` task. For |
1366 | another example that specifies these types of files, see the | 1364 | another 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 | ||
1369 | Another way of specifying source is from an SCM. For Git repositories, | 1367 | Another way of specifying source is from an SCM. For Git repositories, |
1370 | you must specify :term:`SRCREV` and | 1368 | you 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 |
1447 | directory in which the recipe or append file resides. For another | 1445 | directory in which the recipe or append file resides. For another |
1448 | example that specifies these types of files, see the "`Single .c File | 1446 | example that specifies these types of files, see the |
1449 | Package (Hello | 1447 | ":ref:`dev-manual/common-tasks:single .c file package (hello world!)`" section. |
1450 | World!) <#new-recipe-single-c-file-package-hello-world>`__" section. | ||
1451 | 1448 | ||
1452 | The previous example also specifies a patch file. Patch files are files | 1449 | The previous example also specifies a patch file. Patch files are files |
1453 | whose names usually end in ``.patch`` or ``.diff`` but can end with | 1450 | whose names usually end in ``.patch`` or ``.diff`` but can end with |
1454 | compressed suffixes such as ``diff.gz`` and ``patch.bz2``, for example. | 1451 | compressed suffixes such as ``diff.gz`` and ``patch.bz2``, for example. |
1455 | The build system automatically applies patches as described in the | 1452 | The 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 | ||
1458 | Unpacking Code | 1455 | Unpacking 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 | |||
2172 | Sometimes the name of a recipe can lead to versioning problems when the | 2167 | Sometimes the name of a recipe can lead to versioning problems when the |
2173 | recipe is upgraded to a final release. For example, consider the | 2168 | recipe 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 |
2175 | the "`Storing and Naming the | 2170 | the ":ref:`dev-manual/common-tasks:storing and naming the recipe`" section. |
2176 | Recipe <#new-recipe-storing-and-naming-the-recipe>`__" section. This | 2171 | This recipe is at a release candidate stage (i.e. "rc1"). When the recipe is |
2177 | recipe is at a release candidate stage (i.e. "rc1"). When the recipe is | ||
2178 | released, the recipe filename becomes ``irssi_0.8.16.bb``. The version | 2172 | released, the recipe filename becomes ``irssi_0.8.16.bb``. The version |
2179 | change from ``0.8.16-rc1`` to ``0.8.16`` is seen as a decrease by the | 2173 | change from ``0.8.16-rc1`` to ``0.8.16`` is seen as a decrease by the |
2180 | build system and package managers, so the resulting packages will not | 2174 | build system and package managers, so the resulting packages will not |
@@ -2258,8 +2252,7 @@ software you built runs correctly. To accomplish runtime testing, add | |||
2258 | the build's output packages to your image and test them on the target. | 2252 | the build's output packages to your image and test them on the target. |
2259 | 2253 | ||
2260 | For information on how to customize your image by adding specific | 2254 | For information on how to customize your image by adding specific |
2261 | packages, see the "`Customizing | 2255 | packages, see ":ref:`dev-manual/common-tasks:customizing images`" section. |
2262 | Images <#usingpoky-extend-customimage>`__" section. | ||
2263 | 2256 | ||
2264 | Examples | 2257 | Examples |
2265 | -------- | 2258 | -------- |
@@ -2309,8 +2302,8 @@ directory BitBake uses for the build. | |||
2309 | 2302 | ||
2310 | By default, the ``helloworld``, ``helloworld-dbg``, and | 2303 | By 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 |
2312 | customize the packaging process, see the "`Splitting an Application into | 2305 | customize the packaging process, see the |
2313 | Multiple Packages <#splitting-an-application-into-multiple-packages>`__" | 2306 | ":ref:`dev-manual/common-tasks:splitting an application into multiple packages`" |
2314 | section. | 2307 | section. |
2315 | 2308 | ||
2316 | Autotooled Package | 2309 | Autotooled Package |
@@ -3423,9 +3416,8 @@ Follow these general steps: | |||
3423 | 1. *Find the Source Code:* Temporary source code used by the | 3416 | 1. *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 | ||
3431 | 2. *Change Your Working Directory:* You need to be in the directory that | 3423 | 2. *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 | |||
3994 | faster boot times, maintain your critical functionality, and avoid | 3986 | faster boot times, maintain your critical functionality, and avoid |
3995 | initial RAM disks: | 3987 | initial 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 | ||
4016 | Goals and Guiding Principles | 4005 | Goals 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 | ||
4037 | Understand What Contributes to Your Image Size | 4026 | Understand 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 | |||
4706 | some common practices you might find helpful when working with libraries | 4695 | some common practices you might find helpful when working with libraries |
4707 | to build your system: | 4696 | to 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 | ||
4720 | Including Static Library Files | 4709 | Including Static Library Files |
4721 | ------------------------------ | 4710 | ------------------------------ |
@@ -5053,7 +5042,7 @@ because the library is produced for the target architecture, but its | |||
5053 | code needs to be executed on the build host. This problem is solved with | 5042 | code needs to be executed on the build host. This problem is solved with |
5054 | the OpenEmbedded build system by running the code through QEMU, which | 5043 | the OpenEmbedded build system by running the code through QEMU, which |
5055 | allows precisely that. Unfortunately, QEMU does not always work | 5044 | allows precisely that. Unfortunately, QEMU does not always work |
5056 | perfectly as mentioned in the "`Known Issues <#known-issues>`__" | 5045 | perfectly as mentioned in the ":ref:`dev-manual/common-tasks:known issues`" |
5057 | section. | 5046 | section. |
5058 | 5047 | ||
5059 | Enabling the Generation of Introspection Data | 5048 | Enabling the Generation of Introspection Data |
@@ -5225,11 +5214,11 @@ OpenEmbedded build artifacts. Image generation is driven by partitioning | |||
5225 | commands contained in an Openembedded kickstart file (``.wks``) | 5214 | commands contained in an Openembedded kickstart file (``.wks``) |
5226 | specified either directly on the command line or as one of a selection | 5215 | specified either directly on the command line or as one of a selection |
5227 | of canned kickstart files as shown with the ``wic list images`` command | 5216 | of canned kickstart files as shown with the ``wic list images`` command |
5228 | in the "`Using an Existing Kickstart | 5217 | in the |
5229 | File <#using-a-provided-kickstart-file>`__" section. When you apply the | 5218 | ":ref:`dev-manual/common-tasks:generate an image using an existing kickstart file`" |
5230 | command to a given set of build artifacts, the result is an image or set | 5219 | section. When you apply the command to a given set of build artifacts, the |
5231 | of images that can be directly written onto media and used on a | 5220 | result is an image or set of images that can be directly written onto media and |
5232 | particular system. | 5221 | used on a particular system. |
5233 | 5222 | ||
5234 | .. note:: | 5223 | .. note:: |
5235 | 5224 | ||
@@ -5240,8 +5229,8 @@ particular system. | |||
5240 | The ``wic`` command and the infrastructure it is based on is by | 5229 | The ``wic`` command and the infrastructure it is based on is by |
5241 | definition incomplete. The purpose of the command is to allow the | 5230 | definition incomplete. The purpose of the command is to allow the |
5242 | generation of customized images, and as such, was designed to be | 5231 | generation of customized images, and as such, was designed to be |
5243 | completely extensible through a plugin interface. See the "`Using the | 5232 | completely extensible through a plugin interface. See the |
5244 | Wic PlugIn Interface <#wic-using-the-wic-plugin-interface>`__" section | 5233 | ":ref:`dev-manual/common-tasks:using the wic plugin interface`" section |
5245 | for information on these plugins. | 5234 | for information on these plugins. |
5246 | 5235 | ||
5247 | This section provides some background information on Wic, describes what | 5236 | This section provides some background information on Wic, describes what |
@@ -5678,7 +5667,7 @@ Wic Examples | |||
5678 | 5667 | ||
5679 | This section provides several examples that show how to use the Wic | 5668 | This section provides several examples that show how to use the Wic |
5680 | utility. All the examples assume the list of requirements in the | 5669 | utility. 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 |
5682 | examples assume the previously generated image is | 5671 | examples 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 | ||
6384 | This section describes a few tasks that involve packages: | 6372 | This 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 | ||
6410 | Excluding Packages from an Image | 6391 | Excluding Packages from an Image |
6411 | -------------------------------- | 6392 | -------------------------------- |
@@ -6494,9 +6475,8 @@ much preferred over a manual system. In either system, the main | |||
6494 | requirement is that binary package version numbering increases in a | 6475 | requirement is that binary package version numbering increases in a |
6495 | linear fashion and that a number of version components exist that | 6476 | linear fashion and that a number of version components exist that |
6496 | support that linear progression. For information on how to ensure | 6477 | support that linear progression. For information on how to ensure |
6497 | package revisioning remains linear, see the "`Automatically Incrementing | 6478 | package revisioning remains linear, see the |
6498 | a Binary Package Revision | 6479 | ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" |
6499 | Number <#automatically-incrementing-a-binary-package-revision-number>`__" | ||
6500 | section. | 6480 | section. |
6501 | 6481 | ||
6502 | The following three sections provide related information on the PR | 6482 | The 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 | ||
6589 | For information on build | 6569 | For information on build |
6590 | history, see the "`Maintaining Build Output | 6570 | history, see the |
6591 | Quality <#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 | ||
8625 | If you did not set ``TEST_TARGET`` to "SystemdbootTarget", then you do | 8605 | If you did not set ``TEST_TARGET`` to "SystemdbootTarget", then you do |
8626 | not need any information in this section. You can skip down to the | 8606 | not 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 | ||
8629 | If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to | 8609 | If you did set ``TEST_TARGET`` to "SystemdbootTarget", you also need to |
8630 | perform a one-time setup of your master image by doing the following: | 8610 | perform a one-time setup of your master image by doing the following: |
@@ -9090,13 +9070,11 @@ situations. | |||
9090 | The following list shows the debugging topics in the remainder of this | 9070 | The following list shows the debugging topics in the remainder of this |
9091 | section: | 9071 | section: |
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 | ||
9155 | Viewing Logs from Failed Tasks | 9129 | Viewing Logs from Failed Tasks |
@@ -9457,8 +9431,8 @@ state (sstate) task can be a useful debugging aid. This information is | |||
9457 | available in signature information (``siginfo``) files in | 9431 | available in signature information (``siginfo``) files in |
9458 | :term:`SSTATE_DIR`. For | 9432 | :term:`SSTATE_DIR`. For |
9459 | information on how to view and interpret information in ``siginfo`` | 9433 | information on how to view and interpret information in ``siginfo`` |
9460 | files, see the "`Viewing Task Variable | 9434 | files, see the |
9461 | Dependencies <#dev-viewing-task-variable-dependencies>`__" section. | 9435 | ":ref:`dev-manual/common-tasks:viewing task variable dependencies`" section. |
9462 | 9436 | ||
9463 | For conceptual information on shared state, see the | 9437 | For 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 | ||
9880 | For information on how to use a | 9854 | For 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. |
9882 | Shell <#platdev-appdev-devshell>`__" section. | ||
9883 | 9856 | ||
9884 | In the ``devshell``, do the following: | 9857 | In 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 | ||
9923 | For more information on using Quilt, see the | 9896 | For 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 | ||
9926 | At this point you need to make the edits to ``Makefile.am`` to add the | 9899 | At this point you need to make the edits to ``Makefile.am`` to add the |
9927 | missing dependency. For our example, you have to add the following line | 9900 | missing dependency. For our example, you have to add the following line |
@@ -9987,9 +9960,9 @@ The build should work without issue. | |||
9987 | 9960 | ||
9988 | As with all solved problems, if they originated upstream, you need to | 9961 | As with all solved problems, if they originated upstream, you need to |
9989 | submit the fix for the recipe in OE-Core and upstream so that the | 9962 | submit the fix for the recipe in OE-Core and upstream so that the |
9990 | problem is taken care of at its source. See the "`Submitting a Change to | 9963 | problem is taken care of at its source. See the |
9991 | the Yocto Project <#how-to-submit-a-change>`__" section for more | 9964 | ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" |
9992 | information. | 9965 | section for more information. |
9993 | 9966 | ||
9994 | Debugging With the GNU Project Debugger (GDB) Remotely | 9967 | Debugging 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 | ||
10620 | Depending on the components changed, you need to submit the email to a | 10594 | Depending on the components changed, you need to submit the email to a |
10621 | specific mailing list. For some guidance on which mailing list to use, | 10595 | specific mailing list. For some guidance on which mailing list to use, |
10622 | see the `list <#figuring-out-the-mailing-list-to-use>`__ at the | 10596 | see the |
10623 | beginning of this section. For a description of all the available | 10597 | :ref:`list <dev-manual/common-tasks:submitting a change to the yocto project>` |
10598 | at the beginning of this section. For a description of all the available | ||
10624 | mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the | 10599 | mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the |
10625 | Yocto Project Reference Manual. | 10600 | Yocto 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 |
11035 | could add either the string "commercial_gst-plugins-ugly" or the more | 11010 | could add either the string "commercial_gst-plugins-ugly" or the more |
11036 | general string "commercial" to ``LICENSE_FLAGS_WHITELIST``. See the | 11011 | general 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 |
11038 | explanation of how ``LICENSE_FLAGS`` matching works. Here is the | 11013 | explanation of how ``LICENSE_FLAGS`` matching works. Here is the |
11039 | example: | 11014 | example: |
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 | ||
313 | QEMU Command-Line Syntax | 313 | QEMU 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 | |||
655 | from which you can locate and download tarballs of any Yocto Project | 655 | from which you can locate and download tarballs of any Yocto Project |
656 | release. Rather than Git repositories, these files represent snapshot | 656 | release. Rather than Git repositories, these files represent snapshot |
657 | tarballs similar to the tarballs located in the Index of Releases | 657 | tarballs similar to the tarballs located in the Index of Releases |
658 | described in the "`Accessing Index of | 658 | described in the ":ref:`dev-manual/start:accessing index of releases`" section. |
659 | Releases <#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 |
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst index dd0b76bc31..fb6dfca85f 100644 --- a/documentation/kernel-dev/advanced.rst +++ b/documentation/kernel-dev/advanced.rst | |||
@@ -56,8 +56,8 @@ using the same BSP description. Multiple Corei7-based BSPs could share | |||
56 | the same "intel-corei7-64" value for ``KMACHINE``. It is important to | 56 | the same "intel-corei7-64" value for ``KMACHINE``. It is important to |
57 | realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` | 57 | realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` |
58 | is the machine type within a BSP Layer. Even with this distinction, | 58 | is the machine type within a BSP Layer. Even with this distinction, |
59 | however, these two variables can hold the same value. See the `BSP | 59 | however, these two variables can hold the same value. See the |
60 | Descriptions <#bsp-descriptions>`__ section for more information. | 60 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. |
61 | 61 | ||
62 | Every linux-yocto style recipe must also indicate the Linux kernel | 62 | Every linux-yocto style recipe must also indicate the Linux kernel |
63 | source repository branch used to build the Linux kernel. The | 63 | source repository branch used to build the Linux kernel. The |
@@ -87,7 +87,7 @@ Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | |||
87 | arguments used by the kernel tools to find the appropriate description | 87 | arguments used by the kernel tools to find the appropriate description |
88 | within the kernel Metadata with which to build out the sources and | 88 | within the kernel Metadata with which to build out the sources and |
89 | configuration. The linux-yocto recipes define "standard", "tiny", and | 89 | configuration. The linux-yocto recipes define "standard", "tiny", and |
90 | "preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__" | 90 | "preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" |
91 | section for more information on kernel types. | 91 | section for more information on kernel types. |
92 | 92 | ||
93 | During the build, the kern-tools search for the BSP description file | 93 | During the build, the kern-tools search for the BSP description file |
@@ -123,8 +123,8 @@ the entries in ``KERNEL_FEATURES`` are dependent on their location | |||
123 | within the kernel Metadata itself. The examples here are taken from the | 123 | within the kernel Metadata itself. The examples here are taken from the |
124 | ``yocto-kernel-cache`` repository. Each branch of this repository | 124 | ``yocto-kernel-cache`` repository. Each branch of this repository |
125 | contains "features" and "cfg" subdirectories at the top-level. For more | 125 | contains "features" and "cfg" subdirectories at the top-level. For more |
126 | information, see the "`Kernel Metadata | 126 | information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`" |
127 | Syntax <#kernel-metadata-syntax>`__" section. | 127 | section. |
128 | 128 | ||
129 | Kernel Metadata Syntax | 129 | Kernel Metadata Syntax |
130 | ====================== | 130 | ====================== |
@@ -148,7 +148,7 @@ Features aggregate sources in the form of patches and configuration | |||
148 | fragments into a modular reusable unit. You can use features to | 148 | fragments into a modular reusable unit. You can use features to |
149 | implement conceptually separate kernel Metadata descriptions such as | 149 | implement conceptually separate kernel Metadata descriptions such as |
150 | pure configuration fragments, simple patches, complex features, and | 150 | pure configuration fragments, simple patches, complex features, and |
151 | kernel types. `Kernel types <#kernel-types>`__ define general kernel | 151 | kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel |
152 | features and policy to be reused in the BSPs. | 152 | features and policy to be reused in the BSPs. |
153 | 153 | ||
154 | BSPs define hardware-specific features and aggregate them with kernel | 154 | BSPs define hardware-specific features and aggregate them with kernel |
@@ -167,10 +167,9 @@ following Metadata file hierarchy is recommended: | |||
167 | ktypes/ | 167 | ktypes/ |
168 | patches/ | 168 | patches/ |
169 | 169 | ||
170 | The ``bsp`` directory contains the `BSP | 170 | The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`. |
171 | descriptions <#bsp-descriptions>`__. The remaining directories all | 171 | The remaining directories all contain "features". Separating ``bsp`` from the |
172 | contain "features". Separating ``bsp`` from the rest of the structure | 172 | rest of the structure aids conceptualizing intended usage. |
173 | aids conceptualizing intended usage. | ||
174 | 173 | ||
175 | Use these guidelines to help place your ``scc`` description files within | 174 | Use these guidelines to help place your ``scc`` description files within |
176 | the structure: | 175 | the structure: |
@@ -198,11 +197,12 @@ contain "features" as far as the kernel tools are concerned. | |||
198 | Paths used in kernel Metadata files are relative to base, which is | 197 | Paths used in kernel Metadata files are relative to base, which is |
199 | either | 198 | either |
200 | :term:`FILESEXTRAPATHS` if | 199 | :term:`FILESEXTRAPATHS` if |
201 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, | 200 | you are creating Metadata in |
201 | :ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`, | ||
202 | or the top level of | 202 | or the top level of |
203 | :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` | 203 | :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` |
204 | if you are creating `Metadata outside of the | 204 | if you are creating |
205 | recipe-space <#metadata-outside-the-recipe-space>`__. | 205 | :ref:`kernel-dev/advanced:metadata outside the recipe-space`. |
206 | 206 | ||
207 | .. [1] | 207 | .. [1] |
208 | ``scc`` stands for Series Configuration Control, but the naming has | 208 | ``scc`` stands for Series Configuration Control, but the naming has |
@@ -353,9 +353,9 @@ as how an additional feature description file is included with the | |||
353 | Typically, features are less granular than configuration fragments and | 353 | Typically, features are less granular than configuration fragments and |
354 | are more likely than configuration fragments and patches to be the types | 354 | are more likely than configuration fragments and patches to be the types |
355 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the | 355 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the |
356 | Linux kernel recipe. See the "`Using Kernel Metadata in a | 356 | Linux kernel recipe. See the |
357 | Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the | 357 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier |
358 | manual. | 358 | in the manual. |
359 | 359 | ||
360 | Kernel Types | 360 | Kernel Types |
361 | ------------ | 361 | ------------ |
@@ -364,7 +364,7 @@ A kernel type defines a high-level kernel policy by aggregating | |||
364 | non-hardware configuration fragments with patches you want to use when | 364 | non-hardware configuration fragments with patches you want to use when |
365 | building a Linux kernel of a specific type (e.g. a real-time kernel). | 365 | building a Linux kernel of a specific type (e.g. a real-time kernel). |
366 | Syntactically, kernel types are no different than features as described | 366 | Syntactically, kernel types are no different than features as described |
367 | in the "`Features <#features>`__" section. The | 367 | in the ":ref:`kernel-dev/advanced:features`" section. The |
368 | :term:`LINUX_KERNEL_TYPE` | 368 | :term:`LINUX_KERNEL_TYPE` |
369 | variable in the kernel recipe selects the kernel type. For example, in | 369 | variable in the kernel recipe selects the kernel type. For example, in |
370 | the ``linux-yocto_4.12.bb`` kernel recipe found in | 370 | the ``linux-yocto_4.12.bb`` kernel recipe found in |
@@ -540,7 +540,7 @@ example, this is done using the following: | |||
540 | 540 | ||
541 | This file aggregates all the configuration | 541 | This file aggregates all the configuration |
542 | fragments, patches, and features that make up your standard kernel | 542 | fragments, patches, and features that make up your standard kernel |
543 | policy. See the "`Kernel Types <#kernel-types>`__" section for more | 543 | policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more |
544 | information. | 544 | information. |
545 | 545 | ||
546 | To aggregate common configurations and features specific to the kernel | 546 | To aggregate common configurations and features specific to the kernel |
@@ -825,11 +825,11 @@ Given this scenario, you do not need to create any branches in the | |||
825 | source repository. Rather, you just take the static patches you need and | 825 | source repository. Rather, you just take the static patches you need and |
826 | encapsulate them within a feature description. Once you have the feature | 826 | encapsulate them within a feature description. Once you have the feature |
827 | description, you simply include that into the BSP description as | 827 | description, you simply include that into the BSP description as |
828 | described in the "`BSP Descriptions <#bsp-descriptions>`__" section. | 828 | described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section. |
829 | 829 | ||
830 | You can find information on how to create patches and BSP descriptions | 830 | You can find information on how to create patches and BSP descriptions |
831 | in the "`Patches <#patches>`__" and "`BSP | 831 | in the ":ref:`kernel-dev/advanced:patches`" and |
832 | Descriptions <#bsp-descriptions>`__" sections. | 832 | ":ref:`kernel-dev/advanced:bsp descriptions`" sections. |
833 | 833 | ||
834 | Machine Branches | 834 | Machine Branches |
835 | ---------------- | 835 | ---------------- |
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst index 3878f831be..56217b9d38 100644 --- a/documentation/kernel-dev/common.rst +++ b/documentation/kernel-dev/common.rst | |||
@@ -365,8 +365,7 @@ section: | |||
365 | 365 | ||
366 | At this point, you are ready to start making modifications to the kernel | 366 | At this point, you are ready to start making modifications to the kernel |
367 | using traditional kernel development steps. For a continued example, see | 367 | using traditional kernel development steps. For a continued example, see |
368 | the "`Using Traditional Kernel Development to Patch the | 368 | the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
369 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
370 | section. | 369 | section. |
371 | 370 | ||
372 | Creating and Preparing a Layer | 371 | Creating and Preparing a Layer |
@@ -463,8 +462,8 @@ Modifying an existing recipe can consist of the following: | |||
463 | - :ref:`kernel-dev/common:changing the configuration` | 462 | - :ref:`kernel-dev/common:changing the configuration` |
464 | 463 | ||
465 | Before modifying an existing recipe, be sure that you have created a | 464 | Before modifying an existing recipe, be sure that you have created a |
466 | minimal, custom layer from which you can work. See the "`Creating and | 465 | minimal, custom layer from which you can work. See the |
467 | Preparing a Layer <#creating-and-preparing-a-layer>`__" section for | 466 | ":ref:`kernel-dev/common:creating and preparing a layer`" section for |
468 | information. | 467 | information. |
469 | 468 | ||
470 | Creating the Append File | 469 | Creating the Append File |
@@ -710,7 +709,7 @@ Linux kernel, BitBake detects the change in the recipe and fetches and | |||
710 | applies the new configuration before building the kernel. | 709 | applies the new configuration before building the kernel. |
711 | 710 | ||
712 | For a detailed example showing how to configure the kernel, see the | 711 | For a detailed example showing how to configure the kernel, see the |
713 | "`Configuring the Kernel <#configuring-the-kernel>`__" section. | 712 | ":ref:`kernel-dev/common:configuring the kernel`" section. |
714 | 713 | ||
715 | Using an "In-Tree"Â Â ``defconfig`` File | 714 | Using an "In-Tree"Â Â ``defconfig`` File |
716 | -------------------------------------- | 715 | -------------------------------------- |
@@ -954,15 +953,14 @@ emulator console output at boot time through ``printk`` statements in | |||
954 | the kernel's ``calibrate.c`` source code file. Applying the patch and | 953 | the kernel's ``calibrate.c`` source code file. Applying the patch and |
955 | booting the modified image causes the added messages to appear on the | 954 | booting the modified image causes the added messages to appear on the |
956 | emulator's console. The example is a continuation of the setup procedure | 955 | emulator's console. The example is a continuation of the setup procedure |
957 | found in the "`Getting Ready for Traditional Kernel | 956 | found in the |
958 | Development <#getting-ready-for-traditional-kernel-development>`__" | 957 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
959 | Section. | 958 | Section. |
960 | 959 | ||
961 | 1. *Edit the Source Files* Prior to this step, you should have used Git | 960 | 1. *Edit the Source Files* Prior to this step, you should have used Git |
962 | to create a local copy of the repository for your kernel. Assuming | 961 | to create a local copy of the repository for your kernel. Assuming |
963 | you created the repository as directed in the "`Getting Ready for | 962 | you created the repository as directed in the |
964 | Traditional Kernel | 963 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
965 | Development <#getting-ready-for-traditional-kernel-development>`__" | ||
966 | section, use the following commands to edit the ``calibrate.c`` file: | 964 | section, use the following commands to edit the ``calibrate.c`` file: |
967 | 965 | ||
968 | 1. *Change the working directory*: You need to locate the source | 966 | 1. *Change the working directory*: You need to locate the source |
@@ -1104,9 +1102,9 @@ Section. | |||
1104 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | 1102 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements |
1105 | enable the OpenEmbedded build system to find the patch file. | 1103 | enable the OpenEmbedded build system to find the patch file. |
1106 | 1104 | ||
1107 | For more information on append files and patches, see the "`Creating | 1105 | For more information on append files and patches, see the |
1108 | the Append File <#creating-the-append-file>`__" and "`Applying | 1106 | ":ref:`kernel-dev/common:creating the append file`" and |
1109 | Patches <#applying-patches>`__" sections. You can also see the | 1107 | ":ref:`kernel-dev/common:applying patches`" sections. You can also see the |
1110 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | 1108 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" |
1111 | section in the Yocto Project Development Tasks Manual. | 1109 | section in the Yocto Project Development Tasks Manual. |
1112 | 1110 | ||
@@ -1140,8 +1138,8 @@ configuration fragments, and how to interactively modify your | |||
1140 | ``.config`` file to create the leanest kernel configuration file | 1138 | ``.config`` file to create the leanest kernel configuration file |
1141 | possible. | 1139 | possible. |
1142 | 1140 | ||
1143 | For more information on kernel configuration, see the "`Changing the | 1141 | For more information on kernel configuration, see the |
1144 | Configuration <#changing-the-configuration>`__" section. | 1142 | ":ref:`kernel-dev/common:changing the configuration`" section. |
1145 | 1143 | ||
1146 | Using  ``menuconfig`` | 1144 | Using  ``menuconfig`` |
1147 | --------------------- | 1145 | --------------------- |
@@ -1297,8 +1295,8 @@ created to hold the configuration changes. | |||
1297 | applies these on top of and after applying the existing ``defconfig`` file | 1295 | applies these on top of and after applying the existing ``defconfig`` file |
1298 | configurations. | 1296 | configurations. |
1299 | 1297 | ||
1300 | For more information on configuring the kernel, see the "`Changing the | 1298 | For more information on configuring the kernel, see the |
1301 | Configuration <#changing-the-configuration>`__" section. | 1299 | ":ref:`kernel-dev/common:changing the configuration`" section. |
1302 | 1300 | ||
1303 | Creating Configuration Fragments | 1301 | Creating Configuration Fragments |
1304 | -------------------------------- | 1302 | -------------------------------- |
@@ -1369,8 +1367,8 @@ steps: | |||
1369 | $ bitbake linux-yocto -c diffconfig | 1367 | $ bitbake linux-yocto -c diffconfig |
1370 | 1368 | ||
1371 | The ``diffconfig`` command creates a file that is a list of Linux kernel | 1369 | The ``diffconfig`` command creates a file that is a list of Linux kernel |
1372 | ``CONFIG_`` assignments. See the "`Changing the | 1370 | ``CONFIG_`` assignments. See the |
1373 | Configuration <#changing-the-configuration>`__" section for additional | 1371 | ":ref:`kernel-dev/common:changing the configuration`" section for additional |
1374 | information on how to use the output as a configuration fragment. | 1372 | information on how to use the output as a configuration fragment. |
1375 | 1373 | ||
1376 | .. note:: | 1374 | .. note:: |
@@ -1614,8 +1612,7 @@ source directory. Follow these steps to clean up the version string: | |||
1614 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 1612 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
1615 | section. For | 1613 | section. For |
1616 | information on building the kernel image when using Bitbake, see the | 1614 | information on building the kernel image when using Bitbake, see the |
1617 | "`Using Traditional Kernel Development to Patch the | 1615 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
1618 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
1619 | section. | 1616 | section. |
1620 | 1617 | ||
1621 | Working With Your Own Sources | 1618 | Working With Your Own Sources |
@@ -1733,8 +1730,9 @@ Here are some basic steps you can use to work with your own sources: | |||
1733 | 1730 | ||
1734 | 5. *Customize Your Recipe as Needed:* Provide further customizations to | 1731 | 5. *Customize Your Recipe as Needed:* Provide further customizations to |
1735 | your recipe as needed just as you would customize an existing | 1732 | your recipe as needed just as you would customize an existing |
1736 | linux-yocto recipe. See the "`Modifying an Existing | 1733 | linux-yocto recipe. See the |
1737 | Recipe <#modifying-an-existing-recipe>`__" section for information. | 1734 | ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section |
1735 | for information. | ||
1738 | 1736 | ||
1739 | Working with Out-of-Tree Modules | 1737 | Working with Out-of-Tree Modules |
1740 | ================================ | 1738 | ================================ |
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst index f6c9b97137..5592f74c82 100644 --- a/documentation/kernel-dev/intro.rst +++ b/documentation/kernel-dev/intro.rst | |||
@@ -90,8 +90,7 @@ understand the following documentation: | |||
90 | - The ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 90 | - The ":ref:`dev-manual/common-tasks:understanding and creating layers`" |
91 | section in the Yocto Project Development Tasks Manual. | 91 | section in the Yocto Project Development Tasks Manual. |
92 | 92 | ||
93 | - The "`Kernel Modification | 93 | - The ":ref:`kernel-dev/intro:kernel modification workflow`" section. |
94 | Workflow <#kernel-modification-workflow>`__" section. | ||
95 | 94 | ||
96 | Kernel Modification Workflow | 95 | Kernel Modification Workflow |
97 | ============================ | 96 | ============================ |
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index f0c7dab4c8..ada5143b2a 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst | |||
@@ -132,7 +132,7 @@ Layers | |||
132 | 132 | ||
133 | Layers are repositories that contain related metadata (i.e. sets of | 133 | Layers are repositories that contain related metadata (i.e. sets of |
134 | instructions) that tell the OpenEmbedded build system how to build a | 134 | instructions) that tell the OpenEmbedded build system how to build a |
135 | target. Yocto Project's `layer model <#the-yocto-project-layer-model>`__ | 135 | target. :ref:`overview-manual/yp-intro:the yocto project layer model` |
136 | facilitates collaboration, sharing, customization, and reuse within the | 136 | facilitates collaboration, sharing, customization, and reuse within the |
137 | Yocto Project development environment. Layers logically separate | 137 | Yocto Project development environment. Layers logically separate |
138 | information for your project. For example, you can use a layer to hold | 138 | information for your project. For example, you can use a layer to hold |
@@ -207,8 +207,8 @@ you can tell BitBake the target architecture for which you are building | |||
207 | the image, where to store downloaded source, and other build properties. | 207 | the image, where to store downloaded source, and other build properties. |
208 | 208 | ||
209 | The following figure shows an expanded representation of the "User | 209 | The following figure shows an expanded representation of the "User |
210 | Configuration" box of the `general workflow | 210 | Configuration" box of the :ref:`general workflow |
211 | figure <#general-workflow-figure>`__: | 211 | figure <overview-manual/concepts:openembedded build system concepts>`: |
212 | 212 | ||
213 | .. image:: figures/user-configuration.png | 213 | .. image:: figures/user-configuration.png |
214 | :align: center | 214 | :align: center |
@@ -374,7 +374,7 @@ provide Metadata for the software, machine, and policies. | |||
374 | 374 | ||
375 | In general, three types of layer input exists. You can see them below | 375 | In general, three types of layer input exists. You can see them below |
376 | the "User Configuration" box in the `general workflow | 376 | the "User Configuration" box in the `general workflow |
377 | figure <#general-workflow-figure>`__: | 377 | figure <overview-manual/concepts:openembedded build system concepts>`: |
378 | 378 | ||
379 | - *Metadata (.bb + Patches):* Software layers containing | 379 | - *Metadata (.bb + Patches):* Software layers containing |
380 | user-supplied recipe files, patches, and append files. A good example | 380 | user-supplied recipe files, patches, and append files. A good example |
@@ -387,8 +387,8 @@ figure <#general-workflow-figure>`__: | |||
387 | - *Machine BSP Configuration:* Board Support Package (BSP) layers (i.e. | 387 | - *Machine BSP Configuration:* Board Support Package (BSP) layers (i.e. |
388 | "BSP Layer" in the following figure) providing machine-specific | 388 | "BSP Layer" in the following figure) providing machine-specific |
389 | configurations. This type of information is specific to a particular | 389 | configurations. This type of information is specific to a particular |
390 | target architecture. A good example of a BSP layer from the `Poky | 390 | target architecture. A good example of a BSP layer from the |
391 | Reference Distribution <#gs-reference-distribution-poky>`__ is the | 391 | :ref:`overview-manual/yp-intro:reference distribution (poky)` is the |
392 | :yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` | 392 | :yocto_git:`meta-yocto-bsp </poky/tree/meta-yocto-bsp>` |
393 | layer. | 393 | layer. |
394 | 394 | ||
@@ -403,7 +403,8 @@ figure <#general-workflow-figure>`__: | |||
403 | that contain many policy configurations for the Poky distribution. | 403 | that contain many policy configurations for the Poky distribution. |
404 | 404 | ||
405 | The following figure shows an expanded representation of these three | 405 | The following figure shows an expanded representation of these three |
406 | layers from the `general workflow figure <#general-workflow-figure>`__: | 406 | layers from the :ref:`general workflow figure |
407 | <overview-manual/concepts:openembedded build system concepts>`: | ||
407 | 408 | ||
408 | .. image:: figures/layer-input.png | 409 | .. image:: figures/layer-input.png |
409 | :align: center | 410 | :align: center |
@@ -418,9 +419,9 @@ in the | |||
418 | section in the | 419 | section in the |
419 | Yocto Project Development Tasks Manual. For a general discussion on | 420 | Yocto Project Development Tasks Manual. For a general discussion on |
420 | layers and the many layers from which you can draw, see the | 421 | layers and the many layers from which you can draw, see the |
421 | "`Layers <#overview-layers>`__" and "`The Yocto Project Layer | 422 | ":ref:`overview-manual/concepts:layers`" and |
422 | Model <#the-yocto-project-layer-model>`__" sections both earlier in this | 423 | ":ref:`overview-manual/yp-intro:the yocto project layer model`" sections both |
423 | manual. | 424 | earlier in this manual. |
424 | 425 | ||
425 | If you explored the previous links, you discovered some areas where many | 426 | If you explored the previous links, you discovered some areas where many |
426 | layers that work with the Yocto Project exist. The :yocto_git:`Source | 427 | layers that work with the Yocto Project exist. The :yocto_git:`Source |
@@ -514,11 +515,12 @@ Sources | |||
514 | ------- | 515 | ------- |
515 | 516 | ||
516 | In order for the OpenEmbedded build system to create an image or any | 517 | In order for the OpenEmbedded build system to create an image or any |
517 | target, it must be able to access source files. The `general workflow | 518 | target, it must be able to access source files. The :ref:`general workflow |
518 | figure <#general-workflow-figure>`__ represents source files using the | 519 | figure <overview-manual/concepts:openembedded build system concepts>` |
519 | "Upstream Project Releases", "Local Projects", and "SCMs (optional)" | 520 | represents source files using the "Upstream Project Releases", "Local |
520 | boxes. The figure represents mirrors, which also play a role in locating | 521 | Projects", and "SCMs (optional)" boxes. The figure represents mirrors, |
521 | source files, with the "Source Materials" box. | 522 | which also play a role in locating source files, with the "Source |
523 | Materials" box. | ||
522 | 524 | ||
523 | The method by which source files are ultimately organized is a function | 525 | The method by which source files are ultimately organized is a function |
524 | of the project. For example, for released software, projects tend to use | 526 | of the project. For example, for released software, projects tend to use |
@@ -554,7 +556,7 @@ Directory if needed without fear of removing any downloaded source file. | |||
554 | 556 | ||
555 | The remainder of this section provides a deeper look into the source | 557 | The remainder of this section provides a deeper look into the source |
556 | files and the mirrors. Here is a more detailed look at the source file | 558 | files and the mirrors. Here is a more detailed look at the source file |
557 | area of the `general workflow figure <#general-workflow-figure>`__: | 559 | area of the :ref:`general workflow figure <overview-manual/concepts:openembedded build system concepts>`: |
558 | 560 | ||
559 | .. image:: figures/source-input.png | 561 | .. image:: figures/source-input.png |
560 | :align: center | 562 | :align: center |
@@ -628,9 +630,9 @@ Package Feeds | |||
628 | 630 | ||
629 | When the OpenEmbedded build system generates an image or an SDK, it gets | 631 | When the OpenEmbedded build system generates an image or an SDK, it gets |
630 | the packages from a package feed area located in the | 632 | the packages from a package feed area located in the |
631 | :term:`Build Directory`. The `general | 633 | :term:`Build Directory`. The :ref:`general workflow figure |
632 | workflow figure <#general-workflow-figure>`__ shows this package feeds | 634 | <overview-manual/concepts:openembedded build system concepts>` |
633 | area in the upper-right corner. | 635 | shows this package feeds area in the upper-right corner. |
634 | 636 | ||
635 | This section looks a little closer into the package feeds area used by | 637 | This section looks a little closer into the package feeds area used by |
636 | the build system. Here is a more detailed look at the area: | 638 | the build system. Here is a more detailed look at the area: |
@@ -691,10 +693,10 @@ BitBake Tool | |||
691 | 693 | ||
692 | The OpenEmbedded build system uses | 694 | The OpenEmbedded build system uses |
693 | :term:`BitBake` to produce images and | 695 | :term:`BitBake` to produce images and |
694 | Software Development Kits (SDKs). You can see from the `general workflow | 696 | Software Development Kits (SDKs). You can see from the :ref:`general workflow |
695 | figure <#general-workflow-figure>`__, the BitBake area consists of | 697 | figure <overview-manual/concepts:openembedded build system concepts>`, |
696 | several functional areas. This section takes a closer look at each of | 698 | the BitBake area consists of several functional areas. This section takes a |
697 | those areas. | 699 | closer look at each of those areas. |
698 | 700 | ||
699 | .. note:: | 701 | .. note:: |
700 | 702 | ||
@@ -820,7 +822,7 @@ source files, which are located in the | |||
820 | :term:`S` directory. | 822 | :term:`S` directory. |
821 | 823 | ||
822 | For more information on how the source directories are created, see the | 824 | For more information on how the source directories are created, see the |
823 | "`Source Fetching <#source-fetching-dev-environment>`__" section. For | 825 | ":ref:`overview-manual/concepts:source fetching`" section. For |
824 | more information on how to create patches and how the build system | 826 | more information on how to create patches and how the build system |
825 | processes patches, see the | 827 | processes patches, see the |
826 | ":ref:`dev-manual/common-tasks:patching code`" | 828 | ":ref:`dev-manual/common-tasks:patching code`" |
@@ -957,8 +959,8 @@ details on how this is accomplished, you can look at | |||
957 | Depending on the type of packages being created (RPM, DEB, or IPK), the | 959 | Depending on the type of packages being created (RPM, DEB, or IPK), the |
958 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` | 960 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` |
959 | task creates the actual packages and places them in the Package Feed | 961 | task creates the actual packages and places them in the Package Feed |
960 | area, which is ``${TMPDIR}/deploy``. You can see the "`Package | 962 | area, which is ``${TMPDIR}/deploy``. You can see the |
961 | Feeds <#package-feeds-dev-environment>`__" section for more detail on | 963 | ":ref:`overview-manual/concepts:package feeds`" section for more detail on |
962 | that part of the build process. | 964 | that part of the build process. |
963 | 965 | ||
964 | .. note:: | 966 | .. note:: |
@@ -1119,7 +1121,7 @@ and | |||
1119 | :ref:`ref-tasks-populate_sdk_ext` | 1121 | :ref:`ref-tasks-populate_sdk_ext` |
1120 | tasks use these key variables to help create the list of packages to | 1122 | tasks use these key variables to help create the list of packages to |
1121 | actually install. For information on the variables listed in the figure, | 1123 | actually install. For information on the variables listed in the figure, |
1122 | see the "`Application Development SDK <#sdk-dev-environment>`__" | 1124 | see the ":ref:`overview-manual/concepts:application development sdk`" |
1123 | section. | 1125 | section. |
1124 | 1126 | ||
1125 | The ``do_populate_sdk`` task helps create the standard SDK and handles | 1127 | The ``do_populate_sdk`` task helps create the standard SDK and handles |
@@ -1147,8 +1149,8 @@ For each task that completes successfully, BitBake writes a stamp file | |||
1147 | into the :term:`STAMPS_DIR` | 1149 | into the :term:`STAMPS_DIR` |
1148 | directory. The beginning of the stamp file's filename is determined by | 1150 | directory. The beginning of the stamp file's filename is determined by |
1149 | the :term:`STAMP` variable, and the end | 1151 | the :term:`STAMP` variable, and the end |
1150 | of the name consists of the task's name and current `input | 1152 | of the name consists of the task's name and current :ref:`input |
1151 | checksum <#overview-checksums>`__. | 1153 | checksum <overview-manual/concepts:checksums (signatures)>`. |
1152 | 1154 | ||
1153 | .. note:: | 1155 | .. note:: |
1154 | 1156 | ||
@@ -1165,10 +1167,10 @@ file does not exist, the task is rerun. | |||
1165 | .. note:: | 1167 | .. note:: |
1166 | 1168 | ||
1167 | The stamp mechanism is more general than the shared state (sstate) | 1169 | The stamp mechanism is more general than the shared state (sstate) |
1168 | cache mechanism described in the "`Setscene Tasks and Shared | 1170 | cache mechanism described in the |
1169 | State <#setscene-tasks-and-shared-state>`__" section. BitBake avoids | 1171 | ":ref:`overview-manual/concepts:setscene tasks and shared state`" section. |
1170 | rerunning any task that has a valid stamp file, not just tasks that | 1172 | BitBake avoids rerunning any task that has a valid stamp file, not just |
1171 | can be accelerated through the sstate cache. | 1173 | tasks that can be accelerated through the sstate cache. |
1172 | 1174 | ||
1173 | However, you should realize that stamp files only serve as a marker | 1175 | However, you should realize that stamp files only serve as a marker |
1174 | that some work has been done and that these files do not record task | 1176 | that some work has been done and that these files do not record task |
@@ -1271,7 +1273,8 @@ Images | |||
1271 | 1273 | ||
1272 | The images produced by the build system are compressed forms of the root | 1274 | The images produced by the build system are compressed forms of the root |
1273 | filesystem and are ready to boot on a target device. You can see from | 1275 | filesystem and are ready to boot on a target device. You can see from |
1274 | the `general workflow figure <#general-workflow-figure>`__ that BitBake | 1276 | the :ref:`general workflow figure |
1277 | <overview-manual/concepts:openembedded build system concepts>` that BitBake | ||
1275 | output, in part, consists of images. This section takes a closer look at | 1278 | output, in part, consists of images. This section takes a closer look at |
1276 | this output: | 1279 | this output: |
1277 | 1280 | ||
@@ -1327,7 +1330,8 @@ current configuration. | |||
1327 | Application Development SDK | 1330 | Application Development SDK |
1328 | --------------------------- | 1331 | --------------------------- |
1329 | 1332 | ||
1330 | In the `general workflow figure <#general-workflow-figure>`__, the | 1333 | In the :ref:`general workflow figure |
1334 | <overview-manual/concepts:openembedded build system concepts>`, the | ||
1331 | output labeled "Application Development SDK" represents an SDK. The SDK | 1335 | output labeled "Application Development SDK" represents an SDK. The SDK |
1332 | generation process differs depending on whether you build an extensible | 1336 | generation process differs depending on whether you build an extensible |
1333 | SDK (e.g. ``bitbake -c populate_sdk_ext`` imagename) or a standard SDK | 1337 | SDK (e.g. ``bitbake -c populate_sdk_ext`` imagename) or a standard SDK |
@@ -1357,8 +1361,8 @@ can initialize the environment before using the tools. | |||
1357 | your own SDK installer. | 1361 | your own SDK installer. |
1358 | 1362 | ||
1359 | - For background information on cross-development toolchains in the | 1363 | - For background information on cross-development toolchains in the |
1360 | Yocto Project development environment, see the "`Cross-Development | 1364 | Yocto Project development environment, see the |
1361 | Toolchain Generation <#cross-development-toolchain-generation>`__" | 1365 | ":ref:`overview-manual/concepts:cross-development toolchain generation`" |
1362 | section. | 1366 | section. |
1363 | 1367 | ||
1364 | - For information on setting up a cross-development environment, see | 1368 | - For information on setting up a cross-development environment, see |
@@ -1773,10 +1777,10 @@ through this setting in the ``bitbake.conf`` file: | |||
1773 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | 1777 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" |
1774 | 1778 | ||
1775 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same | 1779 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same |
1776 | as the "OEBasic" version but adds the task hash to the `stamp | 1780 | as the "OEBasic" version but adds the task hash to the :ref:`stamp |
1777 | files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any | 1781 | files <overview-manual/concepts:stamp files and the rerunning of tasks>`. This |
1778 | metadata change that changes the task hash, automatically causing the | 1782 | results in any metadata change that changes the task hash, automatically causing |
1779 | task to be run again. This removes the need to bump | 1783 | the task to be run again. This removes the need to bump |
1780 | :term:`PR` values, and changes to metadata | 1784 | :term:`PR` values, and changes to metadata |
1781 | automatically ripple across the build. | 1785 | automatically ripple across the build. |
1782 | 1786 | ||
@@ -1901,9 +1905,10 @@ The following list explains the previous example: | |||
1901 | 1905 | ||
1902 | 1906 | ||
1903 | - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends | 1907 | - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends |
1904 | extra metadata to the `stamp | 1908 | extra metadata to the :ref:`stamp |
1905 | file <#stamp-files-and-the-rerunning-of-tasks>`__. In this case, the | 1909 | file <overview-manual/concepts:stamp files and the rerunning of tasks>`. In |
1906 | metadata makes the task specific to a machine's architecture. See | 1910 | this case, the metadata makes the task specific to a machine's architecture. |
1911 | See | ||
1907 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:the task list`" | 1912 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:the task list`" |
1908 | section in the BitBake User Manual for more information on the | 1913 | section in the BitBake User Manual for more information on the |
1909 | ``stamp-extra-info`` flag. | 1914 | ``stamp-extra-info`` flag. |
diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst index 011a479578..6d1dbfcc72 100644 --- a/documentation/overview-manual/development-environment.rst +++ b/documentation/overview-manual/development-environment.rst | |||
@@ -157,7 +157,8 @@ these tarballs gives you a snapshot of the released files. | |||
157 | 157 | ||
158 | - The recommended method for setting up the Yocto Project | 158 | - The recommended method for setting up the Yocto Project |
159 | :term:`Source Directory` and the files | 159 | :term:`Source Directory` and the files |
160 | for supported BSPs (e.g., ``meta-intel``) is to use `Git <#git>`__ | 160 | for supported BSPs (e.g., ``meta-intel``) is to use |
161 | :ref:`overview-manual/development-environment:git` | ||
161 | to create a local copy of the upstream repositories. | 162 | to create a local copy of the upstream repositories. |
162 | 163 | ||
163 | - Be sure to always work in matching branches for both the selected | 164 | - Be sure to always work in matching branches for both the selected |
@@ -214,7 +215,8 @@ Git Workflows and the Yocto Project | |||
214 | =================================== | 215 | =================================== |
215 | 216 | ||
216 | Developing using the Yocto Project likely requires the use of | 217 | Developing using the Yocto Project likely requires the use of |
217 | `Git <#git>`__. Git is a free, open source distributed version control | 218 | :ref:`overview-manual/development-environment:git`. |
219 | Git is a free, open source distributed version control | ||
218 | system used as part of many collaborative design environments. This | 220 | system used as part of many collaborative design environments. This |
219 | section provides workflow concepts using the Yocto Project and Git. In | 221 | section provides workflow concepts using the Yocto Project and Git. In |
220 | particular, the information covers basic practices that describe roles | 222 | particular, the information covers basic practices that describe roles |
@@ -382,11 +384,10 @@ commands. | |||
382 | Repositories, Tags, and Branches | 384 | Repositories, Tags, and Branches |
383 | -------------------------------- | 385 | -------------------------------- |
384 | 386 | ||
385 | As mentioned briefly in the previous section and also in the "`Git | 387 | As mentioned briefly in the previous section and also in the |
386 | Workflows and the Yocto | 388 | ":ref:`overview-manual/development-environment:git workflows and the yocto project`" |
387 | Project <#gs-git-workflows-and-the-yocto-project>`__" section, the Yocto | 389 | section, the Yocto Project maintains source repositories at :yocto_git:`/`. |
388 | Project maintains source repositories at :yocto_git:`/`. If you | 390 | If you look at this web-interface of the repositories, each item is a separate |
389 | look at this web-interface of the repositories, each item is a separate | ||
390 | Git repository. | 391 | Git repository. |
391 | 392 | ||
392 | Git repositories use branching techniques that track content change (not | 393 | Git repositories use branching techniques that track content change (not |
diff --git a/documentation/overview-manual/intro.rst b/documentation/overview-manual/intro.rst index bd247dd45c..a2afe77564 100644 --- a/documentation/overview-manual/intro.rst +++ b/documentation/overview-manual/intro.rst | |||
@@ -14,17 +14,16 @@ information suitable for a new Yocto Project user. | |||
14 | 14 | ||
15 | The following list describes what you can get from this manual: | 15 | The following list describes what you can get from this manual: |
16 | 16 | ||
17 | - `Introducing the Yocto Project <#overview-yp>`__\ *:* This chapter | 17 | - :ref:`overview-manual/yp-intro:introducing the yocto project`\ *:* |
18 | provides an introduction to the Yocto Project. You will learn about | 18 | This chapter provides an introduction to the Yocto Project. You will learn |
19 | features and challenges of the Yocto Project, the layer model, | 19 | about features and challenges of the Yocto Project, the layer model, |
20 | components and tools, development methods, the | 20 | components and tools, development methods, the |
21 | :term:`Poky` reference distribution, the | 21 | :term:`Poky` reference distribution, the |
22 | OpenEmbedded build system workflow, and some basic Yocto terms. | 22 | OpenEmbedded build system workflow, and some basic Yocto terms. |
23 | 23 | ||
24 | - `The Yocto Project Development | 24 | - :ref:`overview-manual/development-environment:the yocto project development environment`\ *:* |
25 | Environment <#overview-development-environment>`__\ *:* This chapter | 25 | This chapter helps you get started understanding the Yocto Project |
26 | helps you get started understanding the Yocto Project development | 26 | development environment. You will learn about open source, development hosts, |
27 | environment. You will learn about open source, development hosts, | ||
28 | Yocto Project source repositories, workflows using Git and the Yocto | 27 | Yocto Project source repositories, workflows using Git and the Yocto |
29 | Project, a Git primer, and information about licensing. | 28 | Project, a Git primer, and information about licensing. |
30 | 29 | ||
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst index b01b4e6a8f..fca02e4cec 100644 --- a/documentation/overview-manual/yp-intro.rst +++ b/documentation/overview-manual/yp-intro.rst | |||
@@ -96,18 +96,18 @@ Project: | |||
96 | of your design instead of adopting decisions enforced by some system | 96 | of your design instead of adopting decisions enforced by some system |
97 | software provider. | 97 | software provider. |
98 | 98 | ||
99 | - *Uses a Layer Model:* The Yocto Project `layer | 99 | - *Uses a Layer Model:* The Yocto Project :ref:`layer |
100 | infrastructure <#the-yocto-project-layer-model>`__ groups related | 100 | infrastructure <overview-manual/yp-intro:the yocto project layer model>` |
101 | functionality into separate bundles. You can incrementally add these | 101 | groups related functionality into separate bundles. You can incrementally |
102 | grouped functionalities to your project as needed. Using layers to | 102 | add these grouped functionalities to your project as needed. Using layers to |
103 | isolate and group functionality reduces project complexity and | 103 | isolate and group functionality reduces project complexity and |
104 | redundancy, allows you to easily extend the system, make | 104 | redundancy, allows you to easily extend the system, make |
105 | customizations, and keep functionality organized. | 105 | customizations, and keep functionality organized. |
106 | 106 | ||
107 | - *Supports Partial Builds:* You can build and rebuild individual | 107 | - *Supports Partial Builds:* You can build and rebuild individual |
108 | packages as needed. Yocto Project accomplishes this through its | 108 | packages as needed. Yocto Project accomplishes this through its |
109 | `shared-state cache <#shared-state-cache>`__ (sstate) scheme. Being | 109 | :ref:`overview-manual/concepts:shared state cache` (sstate) scheme. |
110 | able to build and debug components individually eases project | 110 | Being able to build and debug components individually eases project |
111 | development. | 111 | development. |
112 | 112 | ||
113 | - *Releases According to a Strict Schedule:* Major releases occur on a | 113 | - *Releases According to a Strict Schedule:* Major releases occur on a |
@@ -155,8 +155,9 @@ developing using the Yocto Project: | |||
155 | documents on the Yocto Project website. | 155 | documents on the Yocto Project website. |
156 | 156 | ||
157 | - *Project Workflow Could Be Confusing:* The `Yocto Project | 157 | - *Project Workflow Could Be Confusing:* The `Yocto Project |
158 | workflow <#overview-development-environment>`__ could be confusing if | 158 | workflow <overview-manual/development-environment:the yocto project development environment>` |
159 | you are used to traditional desktop and server software development. | 159 | could be confusing if you are used to traditional desktop and server |
160 | software development. | ||
160 | In a desktop development environment, mechanisms exist to easily pull | 161 | In a desktop development environment, mechanisms exist to easily pull |
161 | and install new packages, which are typically pre-compiled binaries | 162 | and install new packages, which are typically pre-compiled binaries |
162 | from servers accessible over the Internet. Using the Yocto Project, | 163 | from servers accessible over the Internet. Using the Yocto Project, |
@@ -437,8 +438,8 @@ activities using the Yocto Project: | |||
437 | Thanks to Pseudo, the Yocto Project never needs root privileges to | 438 | Thanks to Pseudo, the Yocto Project never needs root privileges to |
438 | build images for your target system. | 439 | build images for your target system. |
439 | 440 | ||
440 | You can read more about Pseudo in the "`Fakeroot and | 441 | You can read more about Pseudo in the |
441 | Pseudo <#fakeroot-and-pseudo>`__" section. | 442 | ":ref:`overview-manual/concepts:fakeroot and pseudo`" section. |
442 | 443 | ||
443 | Open-Embedded Build System Components | 444 | Open-Embedded Build System Components |
444 | ------------------------------------- | 445 | ------------------------------------- |
@@ -480,9 +481,9 @@ The following list consists of components associated with the | |||
480 | 481 | ||
481 | Sharing a core set of metadata results in Poky as an integration | 482 | Sharing a core set of metadata results in Poky as an integration |
482 | layer on top of OE-Core. You can see that in this | 483 | layer on top of OE-Core. You can see that in this |
483 | `figure <#yp-key-dev-elements>`__. The Yocto Project combines various | 484 | :ref:`figure <overview-manual/yp-intro:what is the yocto project?>`. |
484 | components such as BitBake, OE-Core, script "glue", and documentation | 485 | The Yocto Project combines various components such as BitBake, OE-Core, |
485 | for its build system. | 486 | script "glue", and documentation for its build system. |
486 | 487 | ||
487 | Reference Distribution (Poky) | 488 | Reference Distribution (Poky) |
488 | ----------------------------- | 489 | ----------------------------- |
@@ -490,8 +491,8 @@ Reference Distribution (Poky) | |||
490 | Poky is the Yocto Project reference distribution. It contains the | 491 | Poky is the Yocto Project reference distribution. It contains the |
491 | :term:`OpenEmbedded Build System` | 492 | :term:`OpenEmbedded Build System` |
492 | (BitBake and OE-Core) as well as a set of metadata to get you started | 493 | (BitBake and OE-Core) as well as a set of metadata to get you started |
493 | building your own distribution. See the | 494 | building your own distribution. See the figure in |
494 | `figure <#what-is-the-yocto-project>`__ in "What is the Yocto Project?" | 495 | ":ref:`overview-manual/yp-intro:what is the yocto project?`" |
495 | section for an illustration that shows Poky and its relationship with | 496 | section for an illustration that shows Poky and its relationship with |
496 | other parts of the Yocto Project. | 497 | other parts of the Yocto Project. |
497 | 498 | ||
@@ -503,8 +504,9 @@ To use the Yocto Project tools and components, you can download | |||
503 | Poky does not contain binary files. It is a working example of how to | 504 | Poky does not contain binary files. It is a working example of how to |
504 | build your own custom Linux distribution from source. | 505 | build your own custom Linux distribution from source. |
505 | 506 | ||
506 | You can read more about Poky in the "`Reference Embedded Distribution | 507 | You can read more about Poky in the |
507 | (Poky) <#reference-embedded-distribution>`__" section. | 508 | ":ref:`overview-manual/yp-intro:reference embedded distribution (poky)`" |
509 | section. | ||
508 | 510 | ||
509 | Packages for Finished Targets | 511 | Packages for Finished Targets |
510 | ----------------------------- | 512 | ----------------------------- |
@@ -567,7 +569,7 @@ Linux. | |||
567 | 569 | ||
568 | 3. *CROPS:* The final and best solution available now for developing | 570 | 3. *CROPS:* The final and best solution available now for developing |
569 | using the Yocto Project on a system not native to Linux is with | 571 | using the Yocto Project on a system not native to Linux is with |
570 | `CROPS <#gs-crops-overview>`__. | 572 | :ref:`CROPS <overview-manual/yp-intro:development tools>`. |
571 | 573 | ||
572 | Development Methods | 574 | Development Methods |
573 | =================== | 575 | =================== |
@@ -727,7 +729,8 @@ Sato. | |||
727 | One of the most powerful properties of Poky is that every aspect of a | 729 | One of the most powerful properties of Poky is that every aspect of a |
728 | build is controlled by the metadata. You can use metadata to augment | 730 | build is controlled by the metadata. You can use metadata to augment |
729 | these base image types by adding metadata | 731 | these base image types by adding metadata |
730 | `layers <#the-yocto-project-layer-model>`__ that extend functionality. | 732 | `layers <overview-manual/yp-intro:the yocto project layer model>` that extend |
733 | functionality. | ||
731 | These layers can provide, for example, an additional software stack for | 734 | These layers can provide, for example, an additional software stack for |
732 | an image type, add a board support package (BSP) for additional | 735 | an image type, add a board support package (BSP) for additional |
733 | hardware, or even create a new image type. | 736 | hardware, or even create a new image type. |
@@ -784,8 +787,8 @@ Following is a brief summary of the "workflow": | |||
784 | 7. The build system generates the file system image and a customized | 787 | 7. The build system generates the file system image and a customized |
785 | Extensible SDK (eSDK) for application development in parallel. | 788 | Extensible SDK (eSDK) for application development in parallel. |
786 | 789 | ||
787 | For a very detailed look at this workflow, see the "`OpenEmbedded Build | 790 | For a very detailed look at this workflow, see the |
788 | System Concepts <#openembedded-build-system-build-concepts>`__" section. | 791 | ":ref:`overview-manual/concepts:openembedded build system concepts`" section. |
789 | 792 | ||
790 | Some Basic Terms | 793 | Some Basic Terms |
791 | ================ | 794 | ================ |
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst index 5075f0c224..629aa2ffb9 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst | |||
@@ -178,8 +178,8 @@ resides in ``/home/user/sources/jackson``: | |||
178 | $ devtool add jackson /home/user/sources/jackson | 178 | $ devtool add jackson /home/user/sources/jackson |
179 | 179 | ||
180 | If you add a recipe and the workspace layer does not exist, the command | 180 | If you add a recipe and the workspace layer does not exist, the command |
181 | creates the layer and populates it as described in "`The Workspace Layer | 181 | creates the layer and populates it as described in |
182 | Structure <#devtool-the-workspace-layer-structure>`__" section. | 182 | ":ref:`devtool-the-workspace-layer-structure`" section. |
183 | 183 | ||
184 | Running ``devtool add`` when the workspace layer exists causes the tool | 184 | Running ``devtool add`` when the workspace layer exists causes the tool |
185 | to add the recipe, append files, and source files into the existing | 185 | to add the recipe, append files, and source files into the existing |
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst index 2716bc9cfd..2d638f92b5 100644 --- a/documentation/ref-manual/migration-1.5.rst +++ b/documentation/ref-manual/migration-1.5.rst | |||
@@ -298,7 +298,7 @@ Removed and Renamed Recipes | |||
298 | - ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``. | 298 | - ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``. |
299 | 299 | ||
300 | - ``tinylogin`` has been removed. It has been replaced by a suid | 300 | - ``tinylogin`` has been removed. It has been replaced by a suid |
301 | portion of Busybox. See the "`BusyBox <#busybox>`__" | 301 | portion of Busybox. See the ":ref:`migration-1.5-busybox`" |
302 | section for more information. | 302 | section for more information. |
303 | 303 | ||
304 | - ``external-python-tarball`` has been renamed to | 304 | - ``external-python-tarball`` has been renamed to |
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst index 4a5acc45ca..b7bac0c0d7 100644 --- a/documentation/ref-manual/migration-2.1.rst +++ b/documentation/ref-manual/migration-2.1.rst | |||
@@ -179,9 +179,8 @@ The following recipes have been removed in the 2.1 release: | |||
179 | 179 | ||
180 | - ``python-pygtk``: Recipe became obsolete. | 180 | - ``python-pygtk``: Recipe became obsolete. |
181 | 181 | ||
182 | - ``adt-installer``: Recipe became obsolete. See the "`ADT | 182 | - ``adt-installer``: Recipe became obsolete. See the |
183 | Removed <#adt-removed>`__" section for more | 183 | ":ref:`ref-manual/migration-2.1:adt removed`" section for more information. |
184 | information. | ||
185 | 184 | ||
186 | .. _migration-2.1-class-changes: | 185 | .. _migration-2.1-class-changes: |
187 | 186 | ||
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst index 5c6fecf328..8b3c5d6719 100644 --- a/documentation/ref-manual/migration-2.2.rst +++ b/documentation/ref-manual/migration-2.2.rst | |||
@@ -367,8 +367,8 @@ The following recipes have been removed: | |||
367 | 367 | ||
368 | - ``sato-icon-theme``: Became obsolete. | 368 | - ``sato-icon-theme``: Became obsolete. |
369 | 369 | ||
370 | - ``swabber-native``: Swabber has been removed. See the `entry on | 370 | - ``swabber-native``: Swabber has been removed. See the :ref:`entry on |
371 | Swabber <#swabber-has-been-removed>`__. | 371 | Swabber <ref-manual/migration-2.2:swabber has been removed>`. |
372 | 372 | ||
373 | - ``tslib``: No longer needed and has been moved to ``meta-oe``. | 373 | - ``tslib``: No longer needed and has been moved to ``meta-oe``. |
374 | 374 | ||
@@ -393,8 +393,8 @@ The following classes have been removed: | |||
393 | 393 | ||
394 | - ``sip``: Mostly unused. | 394 | - ``sip``: Mostly unused. |
395 | 395 | ||
396 | - ``swabber``: See the `entry on | 396 | - ``swabber``: See the :ref:`entry on |
397 | Swabber <#swabber-has-been-removed>`__. | 397 | Swabber <ref-manual/migration-2.2:swabber has been removed>`. |
398 | 398 | ||
399 | .. _migration-2.2-minor-packaging-changes: | 399 | .. _migration-2.2-minor-packaging-changes: |
400 | 400 | ||
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst index 5d524f3817..0517b0a2bb 100644 --- a/documentation/ref-manual/migration-2.6.rst +++ b/documentation/ref-manual/migration-2.6.rst | |||
@@ -110,7 +110,7 @@ upon the older ``*proto`` recipes need to be changed to depend on the | |||
110 | newer ``xorgproto`` recipe instead. | 110 | newer ``xorgproto`` recipe instead. |
111 | 111 | ||
112 | For names of recipes removed because of this repository change, see the | 112 | For names of recipes removed because of this repository change, see the |
113 | `Removed Recipes <#removed-recipes>`__ section. | 113 | :ref:`ref-manual/migration-2.6:removed recipes` section. |
114 | 114 | ||
115 | .. _migration-2.6-distutils-distutils3-fetching-dependencies: | 115 | .. _migration-2.6-distutils-distutils3-fetching-dependencies: |
116 | 116 | ||
diff --git a/documentation/ref-manual/release-process.rst b/documentation/ref-manual/release-process.rst index 107d06c76d..93ab6ed08a 100644 --- a/documentation/ref-manual/release-process.rst +++ b/documentation/ref-manual/release-process.rst | |||
@@ -15,9 +15,8 @@ Major and Minor Release Cadence | |||
15 | The Yocto Project delivers major releases (e.g. &DISTRO;) using a six | 15 | The Yocto Project delivers major releases (e.g. &DISTRO;) using a six |
16 | month cadence roughly timed each April and October of the year. | 16 | month cadence roughly timed each April and October of the year. |
17 | Following are examples of some major YP releases with their codenames | 17 | Following are examples of some major YP releases with their codenames |
18 | also shown. See the "`Major Release | 18 | also shown. See the ":ref:`ref-manual/release-process:major release codenames`" |
19 | Codenames <#major-release-codenames>`__" section for information on | 19 | section for information on codenames used with major releases. |
20 | codenames used with major releases. | ||
21 | 20 | ||
22 | - 2.2 (Morty) | 21 | - 2.2 (Morty) |
23 | - 2.1 (Krogoth) | 22 | - 2.1 (Krogoth) |
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst index cdfde8b4b2..8e7115046b 100644 --- a/documentation/sdk-manual/appendix-customizing.rst +++ b/documentation/sdk-manual/appendix-customizing.rst | |||
@@ -101,17 +101,15 @@ adjustments: | |||
101 | 101 | ||
102 | - Generally, you want to have a shared state mirror set up so users of | 102 | - Generally, you want to have a shared state mirror set up so users of |
103 | the SDK can add additional items to the SDK after installation | 103 | the SDK can add additional items to the SDK after installation |
104 | without needing to build the items from source. See the "`Providing | 104 | without needing to build the items from source. See the |
105 | Additional Installable Extensible SDK | 105 | ":ref:`sdk-manual/appendix-customizing:providing additional installable extensible sdk content`" |
106 | Content <#sdk-providing-additional-installable-extensible-sdk-content>`__" | ||
107 | section for information. | 106 | section for information. |
108 | 107 | ||
109 | - If you want users of the SDK to be able to easily update the SDK, you | 108 | - If you want users of the SDK to be able to easily update the SDK, you |
110 | need to set the | 109 | need to set the |
111 | :term:`SDK_UPDATE_URL` | 110 | :term:`SDK_UPDATE_URL` |
112 | variable. For more information, see the "`Providing Updates to the | 111 | variable. For more information, see the |
113 | Extensible SDK After | 112 | ":ref:`sdk-manual/appendix-customizing:providing updates to the extensible sdk after installation`" |
114 | Installation <#sdk-providing-updates-to-the-extensible-sdk-after-installation>`__" | ||
115 | section. | 113 | section. |
116 | 114 | ||
117 | - If you have adjusted the list of files and directories that appear in | 115 | - If you have adjusted the list of files and directories that appear in |
@@ -140,8 +138,8 @@ Changing the Extensible SDK Installer Title | |||
140 | You can change the displayed title for the SDK installer by setting the | 138 | You can change the displayed title for the SDK installer by setting the |
141 | :term:`SDK_TITLE` variable and then | 139 | :term:`SDK_TITLE` variable and then |
142 | rebuilding the SDK installer. For information on how to build an SDK | 140 | rebuilding the SDK installer. For information on how to build an SDK |
143 | installer, see the "`Building an SDK | 141 | installer, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`" |
144 | Installer <#sdk-building-an-sdk-installer>`__" section. | 142 | section. |
145 | 143 | ||
146 | By default, this title is derived from | 144 | By default, this title is derived from |
147 | :term:`DISTRO_NAME` when it is | 145 | :term:`DISTRO_NAME` when it is |
@@ -189,9 +187,8 @@ the installed SDKs to update the installed SDKs by using the | |||
189 | variable to point to the corresponding HTTP or HTTPS URL. Setting | 187 | variable to point to the corresponding HTTP or HTTPS URL. Setting |
190 | this variable causes any SDK built to default to that URL and thus, | 188 | this variable causes any SDK built to default to that URL and thus, |
191 | the user does not have to pass the URL to the ``devtool sdk-update`` | 189 | the user does not have to pass the URL to the ``devtool sdk-update`` |
192 | command as described in the "`Applying Updates to an Installed | 190 | command as described in the |
193 | Extensible | 191 | ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`" |
194 | SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" | ||
195 | section. | 192 | section. |
196 | 193 | ||
197 | 3. Build the extensible SDK normally (i.e., use the | 194 | 3. Build the extensible SDK normally (i.e., use the |
@@ -208,9 +205,9 @@ the installed SDKs to update the installed SDKs by using the | |||
208 | 205 | ||
209 | Completing the above steps allows users of the existing installed SDKs | 206 | Completing the above steps allows users of the existing installed SDKs |
210 | to simply run ``devtool sdk-update`` to retrieve and apply the latest | 207 | to simply run ``devtool sdk-update`` to retrieve and apply the latest |
211 | updates. See the "`Applying Updates to an Installed Extensible | 208 | updates. See the |
212 | SDK <#sdk-applying-updates-to-an-installed-extensible-sdk>`__" section | 209 | ":ref:`sdk-manual/extensible:applying updates to an installed extensible sdk`" |
213 | for further information. | 210 | section for further information. |
214 | 211 | ||
215 | Changing the Default SDK Installation Directory | 212 | Changing the Default SDK Installation Directory |
216 | =============================================== | 213 | =============================================== |
diff --git a/documentation/sdk-manual/appendix-obtain.rst b/documentation/sdk-manual/appendix-obtain.rst index 0fd421f31f..3c1dc52d19 100644 --- a/documentation/sdk-manual/appendix-obtain.rst +++ b/documentation/sdk-manual/appendix-obtain.rst | |||
@@ -68,10 +68,10 @@ Follow these steps to locate and hand-install the toolchain: | |||
68 | $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh | 68 | $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh |
69 | 69 | ||
70 | During execution of the script, you choose the root location for the | 70 | During execution of the script, you choose the root location for the |
71 | toolchain. See the "`Installed Standard SDK Directory | 71 | toolchain. See the |
72 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" | 72 | ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" |
73 | section and the "`Installed Extensible SDK Directory | 73 | section and the |
74 | Structure <#sdk-installed-extensible-sdk-directory-structure>`__" | 74 | ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" |
75 | section for more information. | 75 | section for more information. |
76 | 76 | ||
77 | Building an SDK Installer | 77 | Building an SDK Installer |
@@ -177,10 +177,10 @@ build the SDK installer. Follow these steps: | |||
177 | $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh | 177 | $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh |
178 | 178 | ||
179 | During execution of the script, you choose the root location for the | 179 | During execution of the script, you choose the root location for the |
180 | toolchain. See the "`Installed Standard SDK Directory | 180 | toolchain. See the |
181 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" | 181 | ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" |
182 | section and the "`Installed Extensible SDK Directory | 182 | section and the |
183 | Structure <#sdk-installed-extensible-sdk-directory-structure>`__" | 183 | ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" |
184 | section for more information. | 184 | section for more information. |
185 | 185 | ||
186 | Extracting the Root Filesystem | 186 | Extracting the Root Filesystem |
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst index f1a114368a..baa432ef3b 100644 --- a/documentation/sdk-manual/extensible.rst +++ b/documentation/sdk-manual/extensible.rst | |||
@@ -21,8 +21,9 @@ hardware, and ease integration into the rest of the | |||
21 | 21 | ||
22 | In addition to the functionality available through ``devtool``, you can | 22 | In addition to the functionality available through ``devtool``, you can |
23 | alternatively make use of the toolchain directly, for example from | 23 | alternatively make use of the toolchain directly, for example from |
24 | Makefile and Autotools. See the "`Using the SDK Toolchain | 24 | Makefile and Autotools. See the |
25 | Directly <#sdk-working-projects>`__" chapter for more information. | 25 | ":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter |
26 | for more information. | ||
26 | 27 | ||
27 | Why use the Extensible SDK and What is in It? | 28 | Why use the Extensible SDK and What is in It? |
28 | ============================================= | 29 | ============================================= |
@@ -1087,12 +1088,12 @@ links created within the source tree: | |||
1087 | 1088 | ||
1088 | - ``sysroot-destdir/``: Contains a subset of files installed within | 1089 | - ``sysroot-destdir/``: Contains a subset of files installed within |
1089 | ``do_install`` that have been put into the shared sysroot. For | 1090 | ``do_install`` that have been put into the shared sysroot. For |
1090 | more information, see the "`Sharing Files Between | 1091 | more information, see the |
1091 | Recipes <#sdk-sharing-files-between-recipes>`__" section. | 1092 | ":ref:`dev-manual/common-tasks:sharing files between recipes`" section. |
1092 | 1093 | ||
1093 | - ``packages-split/``: Contains subdirectories for each package | 1094 | - ``packages-split/``: Contains subdirectories for each package |
1094 | produced by the recipe. For more information, see the | 1095 | produced by the recipe. For more information, see the |
1095 | "`Packaging <#sdk-packaging>`__" section. | 1096 | ":ref:`sdk-manual/extensible:packaging`" section. |
1096 | 1097 | ||
1097 | You can use these links to get more information on what is happening at | 1098 | You can use these links to get more information on what is happening at |
1098 | each build step. | 1099 | each build step. |
diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst index e4b9b05ba6..d966efea77 100644 --- a/documentation/sdk-manual/intro.rst +++ b/documentation/sdk-manual/intro.rst | |||
@@ -176,8 +176,8 @@ image. | |||
176 | You just need to follow these general steps: | 176 | You just need to follow these general steps: |
177 | 177 | ||
178 | 1. *Install the SDK for your target hardware:* For information on how to | 178 | 1. *Install the SDK for your target hardware:* For information on how to |
179 | install the SDK, see the "`Installing the | 179 | install the SDK, see the ":ref:`sdk-manual/using:installing the sdk`" |
180 | SDK <#sdk-installing-the-sdk>`__" section. | 180 | section. |
181 | 181 | ||
182 | 2. *Download or Build the Target Image:* The Yocto Project supports | 182 | 2. *Download or Build the Target Image:* The Yocto Project supports |
183 | several target architectures and has many pre-built kernel images and | 183 | several target architectures and has many pre-built kernel images and |
diff --git a/documentation/sdk-manual/using.rst b/documentation/sdk-manual/using.rst index 29fb50465f..62967f5572 100644 --- a/documentation/sdk-manual/using.rst +++ b/documentation/sdk-manual/using.rst | |||
@@ -16,8 +16,9 @@ standard SDK. | |||
16 | " section. | 16 | " section. |
17 | 17 | ||
18 | You can use a standard SDK to work on Makefile and Autotools-based | 18 | You can use a standard SDK to work on Makefile and Autotools-based |
19 | projects. See the "`Using the SDK Toolchain | 19 | projects. See the |
20 | Directly <#sdk-working-projects>`__" chapter for more information. | 20 | ":ref:`sdk-manual/working-projects:using the sdk toolchain directly`" chapter |
21 | for more information. | ||
21 | 22 | ||
22 | Why use the Standard SDK and What is in It? | 23 | Why use the Standard SDK and What is in It? |
23 | =========================================== | 24 | =========================================== |
@@ -31,9 +32,9 @@ the extensible SDK, which provides an internal build system and the | |||
31 | The installed Standard SDK consists of several files and directories. | 32 | The installed Standard SDK consists of several files and directories. |
32 | Basically, it contains an SDK environment setup script, some | 33 | Basically, it contains an SDK environment setup script, some |
33 | configuration files, and host and target root filesystems to support | 34 | configuration files, and host and target root filesystems to support |
34 | usage. You can see the directory structure in the "`Installed Standard | 35 | usage. You can see the directory structure in the |
35 | SDK Directory | 36 | ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" |
36 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" section. | 37 | section. |
37 | 38 | ||
38 | Installing the SDK | 39 | Installing the SDK |
39 | ================== | 40 | ================== |
@@ -120,9 +121,9 @@ architecture. The example assumes the SDK installer is located in | |||
120 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. | 121 | Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. |
121 | $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux | 122 | $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux |
122 | 123 | ||
123 | Again, reference the "`Installed Standard SDK Directory | 124 | Again, reference the |
124 | Structure <#sdk-installed-standard-sdk-directory-structure>`__" section | 125 | ":ref:`sdk-manual/appendix-obtain:installed standard sdk directory structure`" |
125 | for more details on the resulting directory structure of the installed | 126 | section for more details on the resulting directory structure of the installed |
126 | SDK. | 127 | SDK. |
127 | 128 | ||
128 | Running the SDK Environment Setup Script | 129 | Running the SDK Environment Setup Script |
@@ -147,7 +148,6 @@ script is for an IA-based target machine using i586 tuning: | |||
147 | 148 | ||
148 | When you run the | 149 | When you run the |
149 | setup script, the same environment variables are defined as are when you | 150 | setup script, the same environment variables are defined as are when you |
150 | run the setup script for an extensible SDK. See the "`Running the | 151 | run the setup script for an extensible SDK. See the |
151 | Extensible SDK Environment Setup | 152 | ":ref:`sdk-manual/appendix-obtain:installed extensible sdk directory structure`" |
152 | Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__" | ||
153 | section for more information. | 153 | section for more information. |
diff --git a/documentation/test-manual/test-process.rst b/documentation/test-manual/test-process.rst index 508ead5fad..4c3b32bfea 100644 --- a/documentation/test-manual/test-process.rst +++ b/documentation/test-manual/test-process.rst | |||
@@ -63,7 +63,7 @@ milestone releases (usually four) with the final one being stabilization | |||
63 | only along with point releases of our stable branches. | 63 | only along with point releases of our stable branches. |
64 | 64 | ||
65 | The build and release process for these project releases is similar to | 65 | The build and release process for these project releases is similar to |
66 | that in `Day to Day Development <#test-daily-devel>`__, in that the | 66 | that in :ref:`test-manual/test-process:day to day development`, in that the |
67 | a-full target of the Autobuilder is used but in addition the form is | 67 | a-full target of the Autobuilder is used but in addition the form is |
68 | configured to generate and publish artifacts and the milestone number, | 68 | configured to generate and publish artifacts and the milestone number, |
69 | version, release candidate number and other information is entered. The | 69 | version, release candidate number and other information is entered. The |