diff options
Diffstat (limited to 'documentation/ref-manual/ref-structure.rst')
-rw-r--r-- | documentation/ref-manual/ref-structure.rst | 110 |
1 files changed, 64 insertions, 46 deletions
diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst index 1efb81414f..48a443331b 100644 --- a/documentation/ref-manual/ref-structure.rst +++ b/documentation/ref-manual/ref-structure.rst | |||
@@ -11,8 +11,8 @@ describes the Source Directory and gives information about those files | |||
11 | and directories. | 11 | and directories. |
12 | 12 | ||
13 | For information on how to establish a local Source Directory on your | 13 | For information on how to establish a local Source Directory on your |
14 | development system, see the "`Locating Yocto Project Source | 14 | development system, see the |
15 | Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" | 15 | ":ref:`dev-manual/dev-manual-start:locating yocto project source files`" |
16 | section in the Yocto Project Development Tasks Manual. | 16 | section in the Yocto Project Development Tasks Manual. |
17 | 17 | ||
18 | .. note:: | 18 | .. note:: |
@@ -42,7 +42,7 @@ itself; consequently, most users do not need to worry about BitBake. | |||
42 | 42 | ||
43 | When you run the ``bitbake`` command, the main BitBake executable (which | 43 | When you run the ``bitbake`` command, the main BitBake executable (which |
44 | resides in the ``bitbake/bin/`` directory) starts. Sourcing the | 44 | resides in the ``bitbake/bin/`` directory) starts. Sourcing the |
45 | environment setup script (i.e. ````` <#structure-core-script>`__) places | 45 | environment setup script (i.e. :ref:`structure-core-script`) places |
46 | the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into | 46 | the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into |
47 | the shell's ``PATH`` environment variable. | 47 | the shell's ``PATH`` environment variable. |
48 | 48 | ||
@@ -59,14 +59,14 @@ generated by the OpenEmbedded build system in its standard configuration | |||
59 | where the source tree is combined with the output. The :term:`Build Directory` | 59 | where the source tree is combined with the output. The :term:`Build Directory` |
60 | is created initially when you ``source`` | 60 | is created initially when you ``source`` |
61 | the OpenEmbedded build environment setup script (i.e. | 61 | the OpenEmbedded build environment setup script (i.e. |
62 | ````` <#structure-core-script>`__). | 62 | :ref:`structure-core-script`). |
63 | 63 | ||
64 | It is also possible to place output and configuration files in a | 64 | It is also possible to place output and configuration files in a |
65 | directory separate from the :term:`Source Directory` by | 65 | directory separate from the :term:`Source Directory` by |
66 | providing a directory name when you ``source`` the setup script. For | 66 | providing a directory name when you ``source`` the setup script. For |
67 | information on separating output from your local Source Directory files | 67 | information on separating output from your local Source Directory files |
68 | (commonly described as an "out of tree" build), see the | 68 | (commonly described as an "out of tree" build), see the |
69 | "````` <#structure-core-script>`__" section. | 69 | ":ref:`structure-core-script`" section. |
70 | 70 | ||
71 | .. _handbook: | 71 | .. _handbook: |
72 | 72 | ||
@@ -103,9 +103,8 @@ metadata to define the Poky reference distribution. | |||
103 | ------------------- | 103 | ------------------- |
104 | 104 | ||
105 | This directory contains the Yocto Project reference hardware Board | 105 | This directory contains the Yocto Project reference hardware Board |
106 | Support Packages (BSPs). For more information on BSPs, see the `Yocto | 106 | Support Packages (BSPs). For more information on BSPs, see the |
107 | Project Board Support Package (BSP) Developer's | 107 | :doc:`../bsp-guide/bsp-guide`. |
108 | Guide <&YOCTO_DOCS_BSP_URL;>`__. | ||
109 | 108 | ||
110 | .. _structure-meta-selftest: | 109 | .. _structure-meta-selftest: |
111 | 110 | ||
@@ -131,7 +130,7 @@ This directory contains template recipes for BSP and kernel development. | |||
131 | 130 | ||
132 | This directory contains various integration scripts that implement extra | 131 | This directory contains various integration scripts that implement extra |
133 | functionality in the Yocto Project environment (e.g. QEMU scripts). The | 132 | functionality in the Yocto Project environment (e.g. QEMU scripts). The |
134 | ````` <#structure-core-script>`__ script prepends this directory to the | 133 | :ref:`structure-core-script` script prepends this directory to the |
135 | shell's ``PATH`` environment variable. | 134 | shell's ``PATH`` environment variable. |
136 | 135 | ||
137 | The ``scripts`` directory has useful scripts that assist in contributing | 136 | The ``scripts`` directory has useful scripts that assist in contributing |
@@ -154,18 +153,30 @@ When you run this script, your Yocto Project environment is set up, a | |||
154 | :term:`Build Directory` is created, your working | 153 | :term:`Build Directory` is created, your working |
155 | directory becomes the Build Directory, and you are presented with some | 154 | directory becomes the Build Directory, and you are presented with some |
156 | simple suggestions as to what to do next, including a list of some | 155 | simple suggestions as to what to do next, including a list of some |
157 | possible targets to build. Here is an example: $ source | 156 | possible targets to build. Here is an example: |
158 | oe-init-build-env ### Shell environment set up for builds. ### You can | 157 | :: |
159 | now run 'bitbake <target>' Common targets are: core-image-minimal | 158 | |
160 | core-image-sato meta-toolchain meta-ide-support You can also run | 159 | $ source oe-init-build-env |
161 | generated qemu images with a command like 'runqemu qemux86-64' The | 160 | |
162 | default output of the ``oe-init-build-env`` script is from the | 161 | ### Shell environment set up for builds. ### |
162 | |||
163 | You can now run 'bitbake <target>' | ||
164 | |||
165 | Common targets are: | ||
166 | core-image-minimal | ||
167 | core-image-sato | ||
168 | meta-toolchain | ||
169 | meta-ide-support | ||
170 | |||
171 | You can also run generated qemu images with a command like 'runqemu qemux86-64' | ||
172 | |||
173 | The default output of the ``oe-init-build-env`` script is from the | ||
163 | ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory | 174 | ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory |
164 | within the :term:`Source Directory`. If you design a | 175 | within the :term:`Source Directory`. If you design a |
165 | custom distribution, you can include your own version of this | 176 | custom distribution, you can include your own version of this |
166 | configuration file to mention the targets defined by your distribution. | 177 | configuration file to mention the targets defined by your distribution. |
167 | See the "`Creating a Custom Template Configuration | 178 | See the |
168 | Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__" | 179 | ":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" |
169 | section in the Yocto Project Development Tasks Manual for more | 180 | section in the Yocto Project Development Tasks Manual for more |
170 | information. | 181 | information. |
171 | 182 | ||
@@ -175,11 +186,14 @@ you provide a Build Directory argument when you ``source`` the script, | |||
175 | you direct the OpenEmbedded build system to create a Build Directory of | 186 | you direct the OpenEmbedded build system to create a Build Directory of |
176 | your choice. For example, the following command creates a Build | 187 | your choice. For example, the following command creates a Build |
177 | Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: | 188 | Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: |
178 | $ source OE_INIT_FILE ~/mybuilds The | 189 | :: |
179 | OpenEmbedded build system uses the template configuration files, which | 190 | |
191 | $ source OE_INIT_FILE ~/mybuilds | ||
192 | |||
193 | The OpenEmbedded build system uses the template configuration files, which | ||
180 | are found by default in the ``meta-poky/conf/`` directory in the Source | 194 | are found by default in the ``meta-poky/conf/`` directory in the Source |
181 | Directory. See the "`Creating a Custom Template Configuration | 195 | Directory. See the |
182 | Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__" | 196 | ":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" |
183 | section in the Yocto Project Development Tasks Manual for more | 197 | section in the Yocto Project Development Tasks Manual for more |
184 | information. | 198 | information. |
185 | 199 | ||
@@ -207,7 +221,7 @@ The Build Directory - ``build/`` | |||
207 | 221 | ||
208 | The OpenEmbedded build system creates the :term:`Build Directory` | 222 | The OpenEmbedded build system creates the :term:`Build Directory` |
209 | when you run the build environment setup | 223 | when you run the build environment setup |
210 | script ````` <#structure-core-script>`__. If you do not give the Build | 224 | script :ref:`structure-core-script`. If you do not give the Build |
211 | Directory a specific name when you run the setup script, the name | 225 | Directory a specific name when you run the setup script, the name |
212 | defaults to ``build/``. | 226 | defaults to ``build/``. |
213 | 227 | ||
@@ -223,8 +237,7 @@ The OpenEmbedded build system creates this directory when you enable | |||
223 | build history via the ``buildhistory`` class file. The directory | 237 | build history via the ``buildhistory`` class file. The directory |
224 | organizes build information into image, packages, and SDK | 238 | organizes build information into image, packages, and SDK |
225 | subdirectories. For information on the build history feature, see the | 239 | subdirectories. For information on the build history feature, see the |
226 | "`Maintaining Build Output | 240 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" |
227 | Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__" | ||
228 | section in the Yocto Project Development Tasks Manual. | 241 | section in the Yocto Project Development Tasks Manual. |
229 | 242 | ||
230 | .. _structure-build-conf-local.conf: | 243 | .. _structure-build-conf-local.conf: |
@@ -248,7 +261,7 @@ which you want to access downloaded files (``DL_DIR``). | |||
248 | If ``local.conf`` is not present when you start the build, the | 261 | If ``local.conf`` is not present when you start the build, the |
249 | OpenEmbedded build system creates it from ``local.conf.sample`` when you | 262 | OpenEmbedded build system creates it from ``local.conf.sample`` when you |
250 | ``source`` the top-level build environment setup script | 263 | ``source`` the top-level build environment setup script |
251 | ````` <#structure-core-script>`__. | 264 | :ref:`structure-core-script`. |
252 | 265 | ||
253 | The source ``local.conf.sample`` file used depends on the | 266 | The source ``local.conf.sample`` file used depends on the |
254 | ``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` | 267 | ``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` |
@@ -258,7 +271,11 @@ environment. Because the script variable points to the source of the | |||
258 | ``local.conf.sample`` file, this implies that you can configure your | 271 | ``local.conf.sample`` file, this implies that you can configure your |
259 | build environment from any layer by setting the variable in the | 272 | build environment from any layer by setting the variable in the |
260 | top-level build environment setup script as follows: | 273 | top-level build environment setup script as follows: |
261 | TEMPLATECONF=your_layer/conf Once the build process gets the sample | 274 | :: |
275 | |||
276 | TEMPLATECONF=your_layer/conf | ||
277 | |||
278 | Once the build process gets the sample | ||
262 | file, it uses ``sed`` to substitute final | 279 | file, it uses ``sed`` to substitute final |
263 | ``${``\ :term:`OEROOT`\ ``}`` values for all | 280 | ``${``\ :term:`OEROOT`\ ``}`` values for all |
264 | ``##OEROOT##`` values. | 281 | ``##OEROOT##`` values. |
@@ -283,7 +300,7 @@ file, it uses ``sed`` to substitute final | |||
283 | ---------------------------- | 300 | ---------------------------- |
284 | 301 | ||
285 | This configuration file defines | 302 | This configuration file defines |
286 | `layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__, | 303 | :ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`, |
287 | which are directory trees, traversed (or walked) by BitBake. The | 304 | which are directory trees, traversed (or walked) by BitBake. The |
288 | ``bblayers.conf`` file uses the :term:`BBLAYERS` | 305 | ``bblayers.conf`` file uses the :term:`BBLAYERS` |
289 | variable to list the layers BitBake tries to find. | 306 | variable to list the layers BitBake tries to find. |
@@ -291,7 +308,7 @@ variable to list the layers BitBake tries to find. | |||
291 | If ``bblayers.conf`` is not present when you start the build, the | 308 | If ``bblayers.conf`` is not present when you start the build, the |
292 | OpenEmbedded build system creates it from ``bblayers.conf.sample`` when | 309 | OpenEmbedded build system creates it from ``bblayers.conf.sample`` when |
293 | you ``source`` the top-level build environment setup script (i.e. | 310 | you ``source`` the top-level build environment setup script (i.e. |
294 | ````` <#structure-core-script>`__). | 311 | :ref:`structure-core-script`). |
295 | 312 | ||
296 | As with the ``local.conf`` file, the source ``bblayers.conf.sample`` | 313 | As with the ``local.conf`` file, the source ``bblayers.conf.sample`` |
297 | file used depends on the ``$TEMPLATECONF`` script variable, which | 314 | file used depends on the ``$TEMPLATECONF`` script variable, which |
@@ -301,10 +318,12 @@ building from the OpenEmbedded-Core environment. Because the script | |||
301 | variable points to the source of the ``bblayers.conf.sample`` file, this | 318 | variable points to the source of the ``bblayers.conf.sample`` file, this |
302 | implies that you can base your build from any layer by setting the | 319 | implies that you can base your build from any layer by setting the |
303 | variable in the top-level build environment setup script as follows: | 320 | variable in the top-level build environment setup script as follows: |
304 | TEMPLATECONF=your_layer/conf Once the build process gets the sample | 321 | :: |
305 | file, it uses ``sed`` to substitute final | 322 | |
306 | ``${``\ :term:`OEROOT`\ ``}`` values for all | 323 | TEMPLATECONF=your_layer/conf |
307 | ``##OEROOT##`` values. | 324 | |
325 | Once the build process gets the sample file, it uses ``sed`` to substitute final | ||
326 | ``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. | ||
308 | 327 | ||
309 | .. note:: | 328 | .. note:: |
310 | 329 | ||
@@ -395,9 +414,8 @@ This directory contains any "end result" output from the OpenEmbedded | |||
395 | build process. The :term:`DEPLOY_DIR` variable points | 414 | build process. The :term:`DEPLOY_DIR` variable points |
396 | to this directory. For more detail on the contents of the ``deploy`` | 415 | to this directory. For more detail on the contents of the ``deploy`` |
397 | directory, see the | 416 | directory, see the |
398 | "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and | 417 | ":ref:`images-dev-environment`" and |
399 | "`Application Development | 418 | ":ref:`sdk-dev-environment`" sections in the Yocto |
400 | SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections in the Yocto | ||
401 | Project Overview and Concepts Manual. | 419 | Project Overview and Concepts Manual. |
402 | 420 | ||
403 | .. _structure-build-tmp-deploy-deb: | 421 | .. _structure-build-tmp-deploy-deb: |
@@ -434,9 +452,8 @@ This directory receives package licensing information. For example, the | |||
434 | directory contains sub-directories for ``bash``, ``busybox``, and | 452 | directory contains sub-directories for ``bash``, ``busybox``, and |
435 | ``glibc`` (among others) that in turn contain appropriate ``COPYING`` | 453 | ``glibc`` (among others) that in turn contain appropriate ``COPYING`` |
436 | license files with other licensing information. For information on | 454 | license files with other licensing information. For information on |
437 | licensing, see the "`Maintaining Open Source License Compliance During | 455 | licensing, see the |
438 | Your Product's | 456 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" |
439 | Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" | ||
440 | section in the Yocto Project Development Tasks Manual. | 457 | section in the Yocto Project Development Tasks Manual. |
441 | 458 | ||
442 | .. _structure-build-tmp-deploy-images: | 459 | .. _structure-build-tmp-deploy-images: |
@@ -461,8 +478,11 @@ image again. | |||
461 | If you do accidentally delete files here, you will need to force them to | 478 | If you do accidentally delete files here, you will need to force them to |
462 | be re-created. In order to do that, you will need to know the target | 479 | be re-created. In order to do that, you will need to know the target |
463 | that produced them. For example, these commands rebuild and re-create | 480 | that produced them. For example, these commands rebuild and re-create |
464 | the kernel files: $ bitbake -c clean virtual/kernel $ bitbake | 481 | the kernel files: |
465 | virtual/kernel | 482 | :: |
483 | |||
484 | $ bitbake -c clean virtual/kernel | ||
485 | $ bitbake virtual/kernel | ||
466 | 486 | ||
467 | .. _structure-build-tmp-deploy-sdk: | 487 | .. _structure-build-tmp-deploy-sdk: |
468 | 488 | ||
@@ -472,8 +492,7 @@ virtual/kernel | |||
472 | The OpenEmbedded build system creates this directory to hold toolchain | 492 | The OpenEmbedded build system creates this directory to hold toolchain |
473 | installer scripts which, when executed, install the sysroot that matches | 493 | installer scripts which, when executed, install the sysroot that matches |
474 | your target hardware. You can find out more about these installers in | 494 | your target hardware. You can find out more about these installers in |
475 | the "`Building an SDK | 495 | the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" |
476 | Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__" | ||
477 | section in the Yocto Project Application Development and the Extensible | 496 | section in the Yocto Project Application Development and the Extensible |
478 | Software Development Kit (eSDK) manual. | 497 | Software Development Kit (eSDK) manual. |
479 | 498 | ||
@@ -540,8 +559,8 @@ the files in the directory are empty of data, BitBake uses the filenames | |||
540 | and timestamps for tracking purposes. | 559 | and timestamps for tracking purposes. |
541 | 560 | ||
542 | For information on how BitBake uses stamp files to determine if a task | 561 | For information on how BitBake uses stamp files to determine if a task |
543 | should be rerun, see the "`Stamp Files and the Rerunning of | 562 | should be rerun, see the |
544 | Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__" | 563 | ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" |
545 | section in the Yocto Project Overview and Concepts Manual. | 564 | section in the Yocto Project Overview and Concepts Manual. |
546 | 565 | ||
547 | .. _structure-build-tmp-log: | 566 | .. _structure-build-tmp-log: |
@@ -573,8 +592,7 @@ built within the Yocto Project. For this package, a work directory of | |||
573 | ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred | 592 | ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred |
574 | to as the ``WORKDIR``, is created. Within this directory, the source is | 593 | to as the ``WORKDIR``, is created. Within this directory, the source is |
575 | unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. | 594 | unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. |
576 | (See the "`Using Quilt in Your | 595 | (See the ":ref:`using-a-quilt-workflow`" section in |
577 | Workflow <&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow>`__" section in | ||
578 | the Yocto Project Development Tasks Manual for more information.) Within | 596 | the Yocto Project Development Tasks Manual for more information.) Within |
579 | the ``linux-qemux86-standard-build`` directory, standard Quilt | 597 | the ``linux-qemux86-standard-build`` directory, standard Quilt |
580 | directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and | 598 | directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and |