diff options
author | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-16 10:57:16 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2020-09-17 10:09:35 +0100 |
commit | fc876832cb57a1a3e61150778a9cfd7acffbc2b6 (patch) | |
tree | 2219c8a646dd205f0f3e515f1a7c7e4e78b8a6ed /documentation/overview-manual/overview-manual-concepts.rst | |
parent | dd8c9b74d3b46aed6d1315af83769ff29109b65a (diff) | |
download | poky-fc876832cb57a1a3e61150778a9cfd7acffbc2b6.tar.gz |
sphinx: overview-manual: Various URL, code block and other fixes to imported data
(From yocto-docs rev: 3325fe660dfea24fba2f964a0060664e3c67459a)
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/overview-manual/overview-manual-concepts.rst')
-rw-r--r-- | documentation/overview-manual/overview-manual-concepts.rst | 249 |
1 files changed, 147 insertions, 102 deletions
diff --git a/documentation/overview-manual/overview-manual-concepts.rst b/documentation/overview-manual/overview-manual-concepts.rst index 7f8f735b37..695984ff1e 100644 --- a/documentation/overview-manual/overview-manual-concepts.rst +++ b/documentation/overview-manual/overview-manual-concepts.rst | |||
@@ -34,14 +34,14 @@ itself is of various types: | |||
34 | 34 | ||
35 | BitBake knows how to combine multiple data sources together and refers | 35 | BitBake knows how to combine multiple data sources together and refers |
36 | to each data source as a layer. For information on layers, see the | 36 | to each data source as a layer. For information on layers, see the |
37 | "`Understanding and Creating | 37 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" |
38 | Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" | ||
39 | section of the Yocto Project Development Tasks Manual. | 38 | section of the Yocto Project Development Tasks Manual. |
40 | 39 | ||
41 | Following are some brief details on these core components. For | 40 | Following are some brief details on these core components. For |
42 | additional information on how these components interact during a build, | 41 | additional information on how these components interact during a build, |
43 | see the "`OpenEmbedded Build System | 42 | see the |
44 | Concepts <#openembedded-build-system-build-concepts>`__" section. | 43 | ":ref:`overview-manual/overview-manual-concepts:openembedded build system concepts`" |
44 | section. | ||
45 | 45 | ||
46 | .. _usingpoky-components-bitbake: | 46 | .. _usingpoky-components-bitbake: |
47 | 47 | ||
@@ -57,14 +57,23 @@ This section briefly introduces BitBake. If you want more information on | |||
57 | BitBake, see the :doc:`BitBake User Manual <bitbake:index>`. | 57 | BitBake, see the :doc:`BitBake User Manual <bitbake:index>`. |
58 | 58 | ||
59 | To see a list of the options BitBake supports, use either of the | 59 | To see a list of the options BitBake supports, use either of the |
60 | following commands: $ bitbake -h $ bitbake --help | 60 | following commands: |
61 | :: | ||
62 | |||
63 | $ bitbake -h | ||
64 | $ bitbake --help | ||
61 | 65 | ||
62 | The most common usage for BitBake is ``bitbake packagename``, where | 66 | The most common usage for BitBake is ``bitbake packagename``, where |
63 | ``packagename`` is the name of the package you want to build (referred | 67 | ``packagename`` is the name of the package you want to build (referred |
64 | to as the "target"). The target often equates to the first part of a | 68 | to as the "target"). The target often equates to the first part of a |
65 | recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``). | 69 | recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``). |
66 | So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might | 70 | So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might |
67 | type the following: $ bitbake matchbox-desktop Several different | 71 | type the following: |
72 | :: | ||
73 | |||
74 | $ bitbake matchbox-desktop | ||
75 | |||
76 | Several different | ||
68 | versions of ``matchbox-desktop`` might exist. BitBake chooses the one | 77 | versions of ``matchbox-desktop`` might exist. BitBake chooses the one |
69 | selected by the distribution configuration. You can get more details | 78 | selected by the distribution configuration. You can get more details |
70 | about how BitBake chooses between different target versions and | 79 | about how BitBake chooses between different target versions and |
@@ -153,9 +162,8 @@ By convention, layers in the Yocto Project follow a specific form. | |||
153 | Conforming to a known structure allows BitBake to make assumptions | 162 | Conforming to a known structure allows BitBake to make assumptions |
154 | during builds on where to find types of metadata. You can find | 163 | during builds on where to find types of metadata. You can find |
155 | procedures and learn about tools (i.e. ``bitbake-layers``) for creating | 164 | procedures and learn about tools (i.e. ``bitbake-layers``) for creating |
156 | layers suitable for the Yocto Project in the "`Understanding and | 165 | layers suitable for the Yocto Project in the |
157 | Creating | 166 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" |
158 | Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" | ||
159 | section of the Yocto Project Development Tasks Manual. | 167 | section of the Yocto Project Development Tasks Manual. |
160 | 168 | ||
161 | .. _openembedded-build-system-build-concepts: | 169 | .. _openembedded-build-system-build-concepts: |
@@ -225,7 +233,7 @@ reside as example files in the ``build/conf`` directory of the | |||
225 | :term:`Source Directory`. For simplicity, | 233 | :term:`Source Directory`. For simplicity, |
226 | this section refers to the Source Directory as the "Poky Directory." | 234 | this section refers to the Source Directory as the "Poky Directory." |
227 | 235 | ||
228 | When you clone the `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository | 236 | When you clone the :term:`Poky` Git repository |
229 | or you download and unpack a Yocto Project release, you can set up the | 237 | or you download and unpack a Yocto Project release, you can set up the |
230 | Source Directory to be named anything you want. For this discussion, the | 238 | Source Directory to be named anything you want. For this discussion, the |
231 | cloned repository uses the default name ``poky``. | 239 | cloned repository uses the default name ``poky``. |
@@ -238,7 +246,7 @@ cloned repository uses the default name ``poky``. | |||
238 | The ``meta-poky`` layer inside Poky contains a ``conf`` directory that | 246 | The ``meta-poky`` layer inside Poky contains a ``conf`` directory that |
239 | has example configuration files. These example files are used as a basis | 247 | has example configuration files. These example files are used as a basis |
240 | for creating actual configuration files when you source | 248 | for creating actual configuration files when you source |
241 | ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, which is the | 249 | :ref:`structure-core-script`, which is the |
242 | build environment script. | 250 | build environment script. |
243 | 251 | ||
244 | Sourcing the build environment script creates a | 252 | Sourcing the build environment script creates a |
@@ -251,8 +259,8 @@ if versions do not already exist in the Build Directory at the time you | |||
251 | source the build environment setup script. | 259 | source the build environment setup script. |
252 | 260 | ||
253 | Because the Poky repository is fundamentally an aggregation of existing | 261 | Because the Poky repository is fundamentally an aggregation of existing |
254 | repositories, some users might be familiar with running the ```` script | 262 | repositories, some users might be familiar with running the |
255 | in the context of separate | 263 | :ref:`structure-core-script` script in the context of separate |
256 | :term:`OpenEmbedded-Core (OE-Core)` and BitBake | 264 | :term:`OpenEmbedded-Core (OE-Core)` and BitBake |
257 | repositories rather than a single Poky repository. This discussion | 265 | repositories rather than a single Poky repository. This discussion |
258 | assumes the script is executed from within a cloned or unpacked version | 266 | assumes the script is executed from within a cloned or unpacked version |
@@ -320,16 +328,16 @@ The ``bblayers.conf`` file tells BitBake what layers you want considered | |||
320 | during the build. By default, the layers listed in this file include | 328 | during the build. By default, the layers listed in this file include |
321 | layers minimally needed by the build system. However, you must manually | 329 | layers minimally needed by the build system. However, you must manually |
322 | add any custom layers you have created. You can find more information on | 330 | add any custom layers you have created. You can find more information on |
323 | working with the ``bblayers.conf`` file in the "`Enabling Your | 331 | working with the ``bblayers.conf`` file in the |
324 | Layer <&YOCTO_DOCS_DEV_URL;#enabling-your-layer>`__" section in the | 332 | ":ref:`dev-manual/dev-manual-common-tasks:enabling your layer`" |
325 | Yocto Project Development Tasks Manual. | 333 | section in the Yocto Project Development Tasks Manual. |
326 | 334 | ||
327 | The files ``site.conf`` and ``auto.conf`` are not created by the | 335 | The files ``site.conf`` and ``auto.conf`` are not created by the |
328 | environment initialization script. If you want the ``site.conf`` file, | 336 | environment initialization script. If you want the ``site.conf`` file, |
329 | you need to create that yourself. The ``auto.conf`` file is typically | 337 | you need to create that yourself. The ``auto.conf`` file is typically |
330 | created by an autobuilder: | 338 | created by an autobuilder: |
331 | 339 | ||
332 | - *``site.conf``:* You can use the ``conf/site.conf`` configuration | 340 | - *site.conf:* You can use the ``conf/site.conf`` configuration |
333 | file to configure multiple build directories. For example, suppose | 341 | file to configure multiple build directories. For example, suppose |
334 | you had several build environments and they shared some common | 342 | you had several build environments and they shared some common |
335 | features. You can set these default build properties here. A good | 343 | features. You can set these default build properties here. A good |
@@ -346,7 +354,7 @@ created by an autobuilder: | |||
346 | configurations within that build directory's ``conf/local.conf`` | 354 | configurations within that build directory's ``conf/local.conf`` |
347 | file. | 355 | file. |
348 | 356 | ||
349 | - *``auto.conf``:* The file is usually created and written to by an | 357 | - *auto.conf:* The file is usually created and written to by an |
350 | autobuilder. The settings put into the file are typically the same as | 358 | autobuilder. The settings put into the file are typically the same as |
351 | you would find in the ``conf/local.conf`` or the ``conf/site.conf`` | 359 | you would find in the ``conf/local.conf`` or the ``conf/site.conf`` |
352 | files. | 360 | files. |
@@ -382,10 +390,10 @@ In general, three types of layer input exists. You can see them below | |||
382 | the "User Configuration" box in the `general workflow | 390 | the "User Configuration" box in the `general workflow |
383 | figure <#general-workflow-figure>`__: | 391 | figure <#general-workflow-figure>`__: |
384 | 392 | ||
385 | - *Metadata (``.bb`` + Patches):* Software layers containing | 393 | - *Metadata (.bb + Patches):* Software layers containing |
386 | user-supplied recipe files, patches, and append files. A good example | 394 | user-supplied recipe files, patches, and append files. A good example |
387 | of a software layer might be the | 395 | of a software layer might be the |
388 | ```meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from | 396 | `meta-qt5 layer <https://github.com/meta-qt5/meta-qt5>`__ from |
389 | the `OpenEmbedded Layer | 397 | the `OpenEmbedded Layer |
390 | Index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__. | 398 | Index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__. |
391 | This layer is for version 5.0 of the popular | 399 | This layer is for version 5.0 of the popular |
@@ -421,8 +429,9 @@ licensing file (e.g. ``COPYING.MIT``) if the layer is to be distributed, | |||
421 | a ``README`` file as good practice and especially if the layer is to be | 429 | a ``README`` file as good practice and especially if the layer is to be |
422 | distributed, a configuration directory, and recipe directories. You can | 430 | distributed, a configuration directory, and recipe directories. You can |
423 | learn about the general structure for layers used with the Yocto Project | 431 | learn about the general structure for layers used with the Yocto Project |
424 | in the "`Creating Your Own | 432 | in the |
425 | Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in the | 433 | ":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`" |
434 | section in the | ||
426 | Yocto Project Development Tasks Manual. For a general discussion on | 435 | Yocto Project Development Tasks Manual. For a general discussion on |
427 | layers and the many layers from which you can draw, see the | 436 | layers and the many layers from which you can draw, see the |
428 | "`Layers <#overview-layers>`__" and "`The Yocto Project Layer | 437 | "`Layers <#overview-layers>`__" and "`The Yocto Project Layer |
@@ -485,8 +494,7 @@ The BSP Layer provides machine configurations that target specific | |||
485 | hardware. Everything in this layer is specific to the machine for which | 494 | hardware. Everything in this layer is specific to the machine for which |
486 | you are building the image or the SDK. A common structure or form is | 495 | you are building the image or the SDK. A common structure or form is |
487 | defined for BSP layers. You can learn more about this structure in the | 496 | defined for BSP layers. You can learn more about this structure in the |
488 | `Yocto Project Board Support Package (BSP) Developer's | 497 | :doc:`../bsp-guide/bsp-guide`. |
489 | Guide <&YOCTO_DOCS_BSP_URL;>`__. | ||
490 | 498 | ||
491 | .. note:: | 499 | .. note:: |
492 | 500 | ||
@@ -704,8 +712,8 @@ architecture are placed in ``build/tmp/deploy/ipk/qemux86``. | |||
704 | 712 | ||
705 | .. _bitbake-dev-environment: | 713 | .. _bitbake-dev-environment: |
706 | 714 | ||
707 | BitBake | 715 | BitBake Tool |
708 | ------- | 716 | ------------ |
709 | 717 | ||
710 | The OpenEmbedded build system uses | 718 | The OpenEmbedded build system uses |
711 | :term:`BitBake` to produce images and | 719 | :term:`BitBake` to produce images and |
@@ -751,8 +759,7 @@ the source files and unpack them into the | |||
751 | 759 | ||
752 | By default, everything is accomplished in the Build Directory, which has | 760 | By default, everything is accomplished in the Build Directory, which has |
753 | a defined structure. For additional general information on the Build | 761 | a defined structure. For additional general information on the Build |
754 | Directory, see the | 762 | Directory, see the ":ref:`structure-core-build`" section in |
755 | "```build/`` <&YOCTO_DOCS_REF_URL;#structure-core-build>`__" section in | ||
756 | the Yocto Project Reference Manual. | 763 | the Yocto Project Reference Manual. |
757 | 764 | ||
758 | Each recipe has an area in the Build Directory where the unpacked source | 765 | Each recipe has an area in the Build Directory where the unpacked source |
@@ -769,8 +776,7 @@ Build Directory's hierarchy: | |||
769 | - :term:`PACKAGE_ARCH`: The | 776 | - :term:`PACKAGE_ARCH`: The |
770 | architecture of the built package or packages. Depending on the | 777 | architecture of the built package or packages. Depending on the |
771 | eventual destination of the package or packages (i.e. machine | 778 | eventual destination of the package or packages (i.e. machine |
772 | architecture, `build | 779 | architecture, :term:`Build Host`, SDK, or |
773 | host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, SDK, or | ||
774 | specific machine), ``PACKAGE_ARCH`` varies. See the variable's | 780 | specific machine), ``PACKAGE_ARCH`` varies. See the variable's |
775 | description for details. | 781 | description for details. |
776 | 782 | ||
@@ -846,15 +852,14 @@ source files, which are located in the | |||
846 | For more information on how the source directories are created, see the | 852 | For more information on how the source directories are created, see the |
847 | "`Source Fetching <#source-fetching-dev-environment>`__" section. For | 853 | "`Source Fetching <#source-fetching-dev-environment>`__" section. For |
848 | more information on how to create patches and how the build system | 854 | more information on how to create patches and how the build system |
849 | processes patches, see the "`Patching | 855 | processes patches, see the |
850 | Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in the | 856 | ":ref:`dev-manual/dev-manual-common-tasks:patching code`" |
851 | Yocto Project Development Tasks Manual. You can also see the "`Use | 857 | section in the |
852 | ``devtool modify`` to Modify the Source of an Existing | 858 | Yocto Project Development Tasks Manual. You can also see the |
853 | Component <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component>`__" | 859 | ":ref:`sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component`" |
854 | section in the Yocto Project Application Development and the Extensible | 860 | section in the Yocto Project Application Development and the Extensible |
855 | Software Development Kit (SDK) manual and the "`Using Traditional Kernel | 861 | Software Development Kit (SDK) manual and the |
856 | Development to Patch the | 862 | ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`" |
857 | Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
858 | section in the Yocto Project Linux Kernel Development Manual. | 863 | section in the Yocto Project Linux Kernel Development Manual. |
859 | 864 | ||
860 | .. _configuration-compilation-and-staging-dev-environment: | 865 | .. _configuration-compilation-and-staging-dev-environment: |
@@ -882,7 +887,7 @@ This step in the build process consists of the following tasks: | |||
882 | depends. A sysroot exists for both the target and for the native | 887 | depends. A sysroot exists for both the target and for the native |
883 | binaries, which run on the host system. | 888 | binaries, which run on the host system. |
884 | 889 | ||
885 | - *``do_configure``*: This task configures the source by enabling and | 890 | - *do_configure*: This task configures the source by enabling and |
886 | disabling any build-time and configuration options for the software | 891 | disabling any build-time and configuration options for the software |
887 | being built. Configurations can come from the recipe itself as well | 892 | being built. Configurations can come from the recipe itself as well |
888 | as from an inherited class. Additionally, the software itself might | 893 | as from an inherited class. Additionally, the software itself might |
@@ -903,7 +908,7 @@ This step in the build process consists of the following tasks: | |||
903 | :ref:`autotools <ref-classes-autotools>` class | 908 | :ref:`autotools <ref-classes-autotools>` class |
904 | :yocto_git:`here </cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`. | 909 | :yocto_git:`here </cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`. |
905 | 910 | ||
906 | - *``do_compile``*: Once a configuration task has been satisfied, | 911 | - *do_compile*: Once a configuration task has been satisfied, |
907 | BitBake compiles the source using the | 912 | BitBake compiles the source using the |
908 | :ref:`ref-tasks-compile` task. | 913 | :ref:`ref-tasks-compile` task. |
909 | Compilation occurs in the directory pointed to by the | 914 | Compilation occurs in the directory pointed to by the |
@@ -911,7 +916,7 @@ This step in the build process consists of the following tasks: | |||
911 | ``B`` directory is, by default, the same as the | 916 | ``B`` directory is, by default, the same as the |
912 | :term:`S` directory. | 917 | :term:`S` directory. |
913 | 918 | ||
914 | - *``do_install``*: After compilation completes, BitBake executes the | 919 | - *do_install*: After compilation completes, BitBake executes the |
915 | :ref:`ref-tasks-install` task. | 920 | :ref:`ref-tasks-install` task. |
916 | This task copies files from the ``B`` directory and places them in a | 921 | This task copies files from the ``B`` directory and places them in a |
917 | holding area pointed to by the :term:`D` | 922 | holding area pointed to by the :term:`D` |
@@ -1055,8 +1060,8 @@ data files are deleted from the root filesystem. As part of the final | |||
1055 | stage of package installation, post installation scripts that are part | 1060 | stage of package installation, post installation scripts that are part |
1056 | of the packages are run. Any scripts that fail to run on the build host | 1061 | of the packages are run. Any scripts that fail to run on the build host |
1057 | are run on the target when the target system is first booted. If you are | 1062 | are run on the target when the target system is first booted. If you are |
1058 | using a `read-only root | 1063 | using a |
1059 | filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__, | 1064 | :ref:`read-only root filesystem <dev-manual/dev-manual-common-tasks:creating a read-only root filesystem>`, |
1060 | all the post installation scripts must succeed on the build host during | 1065 | all the post installation scripts must succeed on the build host during |
1061 | the package installation phase since the root filesystem on the target | 1066 | the package installation phase since the root filesystem on the target |
1062 | is read-only. | 1067 | is read-only. |
@@ -1097,9 +1102,17 @@ the image. The formats used for the root filesystem depend on the | |||
1097 | support compression. | 1102 | support compression. |
1098 | 1103 | ||
1099 | As an example, a dynamically created task when creating a particular | 1104 | As an example, a dynamically created task when creating a particular |
1100 | image type would take the following form: do_image_type So, if the type | 1105 | image type would take the following form: |
1106 | :: | ||
1107 | |||
1108 | do_image_type | ||
1109 | |||
1110 | So, if the type | ||
1101 | as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically | 1111 | as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically |
1102 | generated task would be as follows: do_image_ext4 | 1112 | generated task would be as follows: |
1113 | :: | ||
1114 | |||
1115 | do_image_ext4 | ||
1103 | 1116 | ||
1104 | The final task involved in image creation is the | 1117 | The final task involved in image creation is the |
1105 | :ref:`do_image_complete <ref-tasks-image-complete>` | 1118 | :ref:`do_image_complete <ref-tasks-image-complete>` |
@@ -1217,8 +1230,7 @@ varflag. If some other task depends on such a task, then that task will | |||
1217 | also always be considered out of date, which might not be what you want. | 1230 | also always be considered out of date, which might not be what you want. |
1218 | 1231 | ||
1219 | For details on how to view information about a task's signature, see the | 1232 | For details on how to view information about a task's signature, see the |
1220 | "`Viewing Task Variable | 1233 | ":ref:`dev-manual/dev-manual-common-tasks:viewing task variable dependencies`" |
1221 | Dependencies <&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies>`__" | ||
1222 | section in the Yocto Project Development Tasks Manual. | 1234 | section in the Yocto Project Development Tasks Manual. |
1223 | 1235 | ||
1224 | Setscene Tasks and Shared State | 1236 | Setscene Tasks and Shared State |
@@ -1397,8 +1409,7 @@ can initialize the environment before using the tools. | |||
1397 | section. | 1409 | section. |
1398 | 1410 | ||
1399 | - For information on setting up a cross-development environment, see | 1411 | - For information on setting up a cross-development environment, see |
1400 | the `Yocto Project Application Development and the Extensible | 1412 | the :doc:`../sdk-manual/sdk-manual` manual. |
1401 | Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. | ||
1402 | 1413 | ||
1403 | All the output files for an SDK are written to the ``deploy/sdk`` folder | 1414 | All the output files for an SDK are written to the ``deploy/sdk`` folder |
1404 | inside the :term:`Build Directory` as | 1415 | inside the :term:`Build Directory` as |
@@ -1475,13 +1486,10 @@ Cross-Development Toolchain Generation | |||
1475 | ====================================== | 1486 | ====================================== |
1476 | 1487 | ||
1477 | The Yocto Project does most of the work for you when it comes to | 1488 | The Yocto Project does most of the work for you when it comes to |
1478 | creating `cross-development | 1489 | creating :ref:`sdk-manual/sdk-intro:the cross-development toolchain`. This |
1479 | toolchains <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__. This | ||
1480 | section provides some technical background on how cross-development | 1490 | section provides some technical background on how cross-development |
1481 | toolchains are created and used. For more information on toolchains, you | 1491 | toolchains are created and used. For more information on toolchains, you |
1482 | can also see the `Yocto Project Application Development and the | 1492 | can also see the :doc:`../sdk-manual/sdk-manual` manual. |
1483 | Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ | ||
1484 | manual. | ||
1485 | 1493 | ||
1486 | In the Yocto Project development environment, cross-development | 1494 | In the Yocto Project development environment, cross-development |
1487 | toolchains are used to build images and applications that run on the | 1495 | toolchains are used to build images and applications that run on the |
@@ -1514,8 +1522,10 @@ cross-compiler that is used internally within BitBake only. | |||
1514 | . | 1522 | . |
1515 | 1523 | ||
1516 | The chain of events that occurs when ``gcc-cross`` is bootstrapped is as | 1524 | The chain of events that occurs when ``gcc-cross`` is bootstrapped is as |
1517 | follows: gcc -> binutils-cross -> gcc-cross-initial -> | 1525 | follows: |
1518 | linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | 1526 | :: |
1527 | |||
1528 | gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime | ||
1519 | 1529 | ||
1520 | - ``gcc``: The build host's GNU Compiler Collection (GCC). | 1530 | - ``gcc``: The build host's GNU Compiler Collection (GCC). |
1521 | 1531 | ||
@@ -1571,9 +1581,10 @@ might not be the same machine as the Build Host. | |||
1571 | can take advantage of pre-built images that ship with the Yocto | 1581 | can take advantage of pre-built images that ship with the Yocto |
1572 | Project and already contain cross-development toolchain installers. | 1582 | Project and already contain cross-development toolchain installers. |
1573 | 1583 | ||
1574 | Here is the bootstrap process for the relocatable toolchain: gcc -> | 1584 | Here is the bootstrap process for the relocatable toolchain: |
1575 | binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> | 1585 | :: |
1576 | glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | 1586 | |
1587 | gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian | ||
1577 | 1588 | ||
1578 | - ``gcc``: The build host's GNU Compiler Collection (GCC). | 1589 | - ``gcc``: The build host's GNU Compiler Collection (GCC). |
1579 | 1590 | ||
@@ -1668,18 +1679,15 @@ them if they are deemed to be valid. | |||
1668 | the shared state packages. Consequently, considerations exist that | 1679 | the shared state packages. Consequently, considerations exist that |
1669 | affect maintaining shared state feeds. For information on how the | 1680 | affect maintaining shared state feeds. For information on how the |
1670 | build system works with packages and can track incrementing ``PR`` | 1681 | build system works with packages and can track incrementing ``PR`` |
1671 | information, see the "`Automatically Incrementing a Binary Package | 1682 | information, see the ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`" |
1672 | Revision | ||
1673 | Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__" | ||
1674 | section in the Yocto Project Development Tasks Manual. | 1683 | section in the Yocto Project Development Tasks Manual. |
1675 | 1684 | ||
1676 | - The code in the build system that supports incremental builds is | 1685 | - The code in the build system that supports incremental builds is |
1677 | not simple code. For techniques that help you work around issues | 1686 | not simple code. For techniques that help you work around issues |
1678 | related to shared state code, see the "`Viewing Metadata Used to | 1687 | related to shared state code, see the |
1679 | Create the Input Signature of a Shared State | 1688 | ":ref:`dev-manual/dev-manual-common-tasks:viewing metadata used to create the input signature of a shared state task`" |
1680 | Task <&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task>`__" | 1689 | and |
1681 | and "`Invalidating Shared State to Force a Task to | 1690 | ":ref:`dev-manual/dev-manual-common-tasks:invalidating shared state to force a task to run`" |
1682 | Run <&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run>`__" | ||
1683 | sections both in the Yocto Project Development Tasks Manual. | 1691 | sections both in the Yocto Project Development Tasks Manual. |
1684 | 1692 | ||
1685 | The rest of this section goes into detail about the overall incremental | 1693 | The rest of this section goes into detail about the overall incremental |
@@ -1754,15 +1762,22 @@ to the task. | |||
1754 | Like the ``WORKDIR`` case, situations exist where dependencies should be | 1762 | Like the ``WORKDIR`` case, situations exist where dependencies should be |
1755 | ignored. For these situations, you can instruct the build process to | 1763 | ignored. For these situations, you can instruct the build process to |
1756 | ignore a dependency by using a line like the following: | 1764 | ignore a dependency by using a line like the following: |
1757 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the | 1765 | :: |
1758 | :term:`PACKAGE_ARCHS` variable | 1766 | |
1759 | does not depend on the value of | 1767 | PACKAGE_ARCHS[vardepsexclude] = "MACHINE" |
1760 | :term:`MACHINE`, even if it does | 1768 | |
1769 | This example ensures that the :term:`PACKAGE_ARCHS` variable | ||
1770 | does not depend on the value of :term:`MACHINE`, even if it does | ||
1761 | reference it. | 1771 | reference it. |
1762 | 1772 | ||
1763 | Equally, there are cases where you need to add dependencies BitBake is | 1773 | Equally, there are cases where you need to add dependencies BitBake is |
1764 | not able to find. You can accomplish this by using a line like the | 1774 | not able to find. You can accomplish this by using a line like the |
1765 | following: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly | 1775 | following: |
1776 | :: | ||
1777 | |||
1778 | PACKAGE_ARCHS[vardeps] = "MACHINE" | ||
1779 | |||
1780 | This example explicitly | ||
1766 | adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. | 1781 | adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. |
1767 | 1782 | ||
1768 | As an example, consider a case with in-line Python where BitBake is not | 1783 | As an example, consider a case with in-line Python where BitBake is not |
@@ -1788,12 +1803,16 @@ and the dependent task hashes can be influenced. Within the BitBake | |||
1788 | configuration file, you can give BitBake some extra information to help | 1803 | configuration file, you can give BitBake some extra information to help |
1789 | it construct the basehash. The following statement effectively results | 1804 | it construct the basehash. The following statement effectively results |
1790 | in a list of global variable dependency excludes (i.e. variables never | 1805 | in a list of global variable dependency excludes (i.e. variables never |
1791 | included in any checksum): BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH | 1806 | included in any checksum): |
1792 | PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS | 1807 | :: |
1793 | FILE_DIRNAME HOME LOGNAME SHELL TERM \\ USER FILESPATH STAGING_DIR_HOST | 1808 | |
1794 | STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR | 1809 | BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\ |
1795 | PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR | 1810 | SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\ |
1796 | EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The | 1811 | USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ |
1812 | PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ | ||
1813 | CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" | ||
1814 | |||
1815 | The | ||
1797 | previous example excludes | 1816 | previous example excludes |
1798 | :term:`WORKDIR` since that variable | 1817 | :term:`WORKDIR` since that variable |
1799 | is actually constructed as a path within | 1818 | is actually constructed as a path within |
@@ -1810,8 +1829,12 @@ desired. This file defines the two basic signature generators | |||
1810 | "OEBasicHash". By default, a dummy "noop" signature handler is enabled | 1829 | "OEBasicHash". By default, a dummy "noop" signature handler is enabled |
1811 | in BitBake. This means that behavior is unchanged from previous | 1830 | in BitBake. This means that behavior is unchanged from previous |
1812 | versions. OE-Core uses the "OEBasicHash" signature handler by default | 1831 | versions. OE-Core uses the "OEBasicHash" signature handler by default |
1813 | through this setting in the ``bitbake.conf`` file: BB_SIGNATURE_HANDLER | 1832 | through this setting in the ``bitbake.conf`` file: |
1814 | ?= "OEBasicHash" The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same | 1833 | :: |
1834 | |||
1835 | BB_SIGNATURE_HANDLER ?= "OEBasicHash" | ||
1836 | |||
1837 | The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same | ||
1815 | as the "OEBasic" version but adds the task hash to the `stamp | 1838 | as the "OEBasic" version but adds the task hash to the `stamp |
1816 | files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any | 1839 | files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any |
1817 | metadata change that changes the task hash, automatically causing the | 1840 | metadata change that changes the task hash, automatically causing the |
@@ -1862,12 +1885,21 @@ implementation hidden in ``sstate`` class. From a user's perspective, | |||
1862 | adding shared state wrapping to a task is as simple as this | 1885 | adding shared state wrapping to a task is as simple as this |
1863 | :ref:`ref-tasks-deploy` example taken | 1886 | :ref:`ref-tasks-deploy` example taken |
1864 | from the :ref:`deploy <ref-classes-deploy>` class: | 1887 | from the :ref:`deploy <ref-classes-deploy>` class: |
1865 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy" | 1888 | :: |
1866 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" | 1889 | |
1867 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" python | 1890 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" |
1868 | do_deploy_setscene () { sstate_setscene(d) } addtask do_deploy_setscene | 1891 | SSTATETASKS += "do_deploy" |
1869 | do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = | 1892 | do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" |
1870 | "${MACHINE_ARCH}" The following list explains the previous example: | 1893 | do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" |
1894 | |||
1895 | python do_deploy_setscene () { | ||
1896 | sstate_setscene(d) | ||
1897 | } | ||
1898 | addtask do_deploy_setscene | ||
1899 | do_deploy[dirs] = "${DEPLOYDIR} ${B}" | ||
1900 | do_deploy[stamp-extra-info] = "${MACHINE_ARCH}" | ||
1901 | |||
1902 | The following list explains the previous example: | ||
1871 | 1903 | ||
1872 | - Adding "do_deploy" to ``SSTATETASKS`` adds some required | 1904 | - Adding "do_deploy" to ``SSTATETASKS`` adds some required |
1873 | sstate-related processing, which is implemented in the | 1905 | sstate-related processing, which is implemented in the |
@@ -1907,9 +1939,15 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = | |||
1907 | task. | 1939 | task. |
1908 | 1940 | ||
1909 | - The following task definition is glue logic needed to make the | 1941 | - The following task definition is glue logic needed to make the |
1910 | previous settings effective: python do_deploy_setscene () { | 1942 | previous settings effective: |
1911 | sstate_setscene(d) } addtask do_deploy_setscene ``sstate_setscene()`` | 1943 | :: |
1912 | takes the flags above as input and accelerates the ``do_deploy`` task | 1944 | |
1945 | python do_deploy_setscene () { | ||
1946 | sstate_setscene(d) | ||
1947 | } | ||
1948 | addtask do_deploy_setscene | ||
1949 | |||
1950 | ``sstate_setscene()`` takes the flags above as input and accelerates the ``do_deploy`` task | ||
1913 | through the shared state cache if possible. If the task was | 1951 | through the shared state cache if possible. If the task was |
1914 | accelerated, ``sstate_setscene()`` returns True. Otherwise, it | 1952 | accelerated, ``sstate_setscene()`` returns True. Otherwise, it |
1915 | returns False, and the normal ``do_deploy`` task runs. For more | 1953 | returns False, and the normal ``do_deploy`` task runs. For more |
@@ -1941,7 +1979,7 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = | |||
1941 | :: | 1979 | :: |
1942 | 1980 | ||
1943 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" | 1981 | do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" |
1944 | 1982 | ||
1945 | 1983 | ||
1946 | - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends | 1984 | - The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends |
1947 | extra metadata to the `stamp | 1985 | extra metadata to the `stamp |
@@ -1956,20 +1994,27 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = | |||
1956 | ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, | 1994 | ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, |
1957 | which populates the shared state cache, and ``PKGDATA_DIR`` and | 1995 | which populates the shared state cache, and ``PKGDATA_DIR`` and |
1958 | ``SHLIBSDIR`` as the corresponding shared state output directories: | 1996 | ``SHLIBSDIR`` as the corresponding shared state output directories: |
1959 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | 1997 | :: |
1960 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | 1998 | |
1999 | do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" | ||
2000 | do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" | ||
1961 | 2001 | ||
1962 | - These methods also include the ability to take a lockfile when | 2002 | - These methods also include the ability to take a lockfile when |
1963 | manipulating shared state directory structures, for cases where file | 2003 | manipulating shared state directory structures, for cases where file |
1964 | additions or removals are sensitive: do_package[sstate-lockfile] = | 2004 | additions or removals are sensitive: |
1965 | "${PACKAGELOCK}" | 2005 | :: |
2006 | |||
2007 | do_package[sstate-lockfile] = "${PACKAGELOCK}" | ||
1966 | 2008 | ||
1967 | Behind the scenes, the shared state code works by looking in | 2009 | Behind the scenes, the shared state code works by looking in |
1968 | :term:`SSTATE_DIR` and | 2010 | :term:`SSTATE_DIR` and |
1969 | :term:`SSTATE_MIRRORS` for | 2011 | :term:`SSTATE_MIRRORS` for |
1970 | shared state files. Here is an example: SSTATE_MIRRORS ?= "\\ file://.\* | 2012 | shared state files. Here is an example: |
1971 | http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\ | 2013 | :: |
1972 | file://.\* file:///some/local/dir/sstate/PATH" | 2014 | |
2015 | SSTATE_MIRRORS ?= "\ | ||
2016 | file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
2017 | file://.\* file:///some/local/dir/sstate/PATH" | ||
1973 | 2018 | ||
1974 | .. note:: | 2019 | .. note:: |
1975 | 2020 | ||
@@ -2164,11 +2209,11 @@ accomplished using fakeroot. | |||
2164 | , giving the following: | 2209 | , giving the following: |
2165 | :: | 2210 | :: |
2166 | 2211 | ||
2167 | fakeroot do_mytask () { | 2212 | fakeroot do_mytask () { |
2168 | ... | 2213 | ... |
2169 | } | 2214 | } |
2170 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" | 2215 | do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" |
2171 | 2216 | ||
2172 | 2217 | ||
2173 | For more information, see the | 2218 | For more information, see the |
2174 | :term:`FAKEROOT* <bitbake:FAKEROOT>` variables in the | 2219 | :term:`FAKEROOT* <bitbake:FAKEROOT>` variables in the |