summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-structure.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-structure.rst')
-rw-r--r--documentation/ref-manual/ref-structure.rst110
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
11and directories. 11and directories.
12 12
13For information on how to establish a local Source Directory on your 13For information on how to establish a local Source Directory on your
14development system, see the "`Locating Yocto Project Source 14development system, see the
15Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" 15":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
16section in the Yocto Project Development Tasks Manual. 16section 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
43When you run the ``bitbake`` command, the main BitBake executable (which 43When you run the ``bitbake`` command, the main BitBake executable (which
44resides in the ``bitbake/bin/`` directory) starts. Sourcing the 44resides in the ``bitbake/bin/`` directory) starts. Sourcing the
45environment setup script (i.e. ````` <#structure-core-script>`__) places 45environment setup script (i.e. :ref:`structure-core-script`) places
46the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into 46the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into
47the shell's ``PATH`` environment variable. 47the shell's ``PATH`` environment variable.
48 48
@@ -59,14 +59,14 @@ generated by the OpenEmbedded build system in its standard configuration
59where the source tree is combined with the output. The :term:`Build Directory` 59where the source tree is combined with the output. The :term:`Build Directory`
60is created initially when you ``source`` 60is created initially when you ``source``
61the OpenEmbedded build environment setup script (i.e. 61the OpenEmbedded build environment setup script (i.e.
62````` <#structure-core-script>`__). 62:ref:`structure-core-script`).
63 63
64It is also possible to place output and configuration files in a 64It is also possible to place output and configuration files in a
65directory separate from the :term:`Source Directory` by 65directory separate from the :term:`Source Directory` by
66providing a directory name when you ``source`` the setup script. For 66providing a directory name when you ``source`` the setup script. For
67information on separating output from your local Source Directory files 67information 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
105This directory contains the Yocto Project reference hardware Board 105This directory contains the Yocto Project reference hardware Board
106Support Packages (BSPs). For more information on BSPs, see the `Yocto 106Support Packages (BSPs). For more information on BSPs, see the
107Project Board Support Package (BSP) Developer's 107:doc:`../bsp-guide/bsp-guide`.
108Guide <&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
132This directory contains various integration scripts that implement extra 131This directory contains various integration scripts that implement extra
133functionality in the Yocto Project environment (e.g. QEMU scripts). The 132functionality 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
135shell's ``PATH`` environment variable. 134shell's ``PATH`` environment variable.
136 135
137The ``scripts`` directory has useful scripts that assist in contributing 136The ``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
155directory becomes the Build Directory, and you are presented with some 154directory becomes the Build Directory, and you are presented with some
156simple suggestions as to what to do next, including a list of some 155simple suggestions as to what to do next, including a list of some
157possible targets to build. Here is an example: $ source 156possible targets to build. Here is an example:
158oe-init-build-env ### Shell environment set up for builds. ### You can 157::
159now run 'bitbake <target>' Common targets are: core-image-minimal 158
160core-image-sato meta-toolchain meta-ide-support You can also run 159 $ source oe-init-build-env
161generated qemu images with a command like 'runqemu qemux86-64' The 160
162default 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
173The 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
164within the :term:`Source Directory`. If you design a 175within the :term:`Source Directory`. If you design a
165custom distribution, you can include your own version of this 176custom distribution, you can include your own version of this
166configuration file to mention the targets defined by your distribution. 177configuration file to mention the targets defined by your distribution.
167See the "`Creating a Custom Template Configuration 178See the
168Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__" 179":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
169section in the Yocto Project Development Tasks Manual for more 180section in the Yocto Project Development Tasks Manual for more
170information. 181information.
171 182
@@ -175,11 +186,14 @@ you provide a Build Directory argument when you ``source`` the script,
175you direct the OpenEmbedded build system to create a Build Directory of 186you direct the OpenEmbedded build system to create a Build Directory of
176your choice. For example, the following command creates a Build 187your choice. For example, the following command creates a Build
177Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: 188Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
178$ source OE_INIT_FILE ~/mybuilds The 189::
179OpenEmbedded build system uses the template configuration files, which 190
191 $ source OE_INIT_FILE ~/mybuilds
192
193The OpenEmbedded build system uses the template configuration files, which
180are found by default in the ``meta-poky/conf/`` directory in the Source 194are found by default in the ``meta-poky/conf/`` directory in the Source
181Directory. See the "`Creating a Custom Template Configuration 195Directory. See the
182Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__" 196":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
183section in the Yocto Project Development Tasks Manual for more 197section in the Yocto Project Development Tasks Manual for more
184information. 198information.
185 199
@@ -207,7 +221,7 @@ The Build Directory - ``build/``
207 221
208The OpenEmbedded build system creates the :term:`Build Directory` 222The OpenEmbedded build system creates the :term:`Build Directory`
209when you run the build environment setup 223when you run the build environment setup
210script ````` <#structure-core-script>`__. If you do not give the Build 224script :ref:`structure-core-script`. If you do not give the Build
211Directory a specific name when you run the setup script, the name 225Directory a specific name when you run the setup script, the name
212defaults to ``build/``. 226defaults to ``build/``.
213 227
@@ -223,8 +237,7 @@ The OpenEmbedded build system creates this directory when you enable
223build history via the ``buildhistory`` class file. The directory 237build history via the ``buildhistory`` class file. The directory
224organizes build information into image, packages, and SDK 238organizes build information into image, packages, and SDK
225subdirectories. For information on the build history feature, see the 239subdirectories. 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`"
227Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
228section in the Yocto Project Development Tasks Manual. 241section 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``).
248If ``local.conf`` is not present when you start the build, the 261If ``local.conf`` is not present when you start the build, the
249OpenEmbedded build system creates it from ``local.conf.sample`` when you 262OpenEmbedded 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
253The source ``local.conf.sample`` file used depends on the 266The 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
259build environment from any layer by setting the variable in the 272build environment from any layer by setting the variable in the
260top-level build environment setup script as follows: 273top-level build environment setup script as follows:
261TEMPLATECONF=your_layer/conf Once the build process gets the sample 274::
275
276 TEMPLATECONF=your_layer/conf
277
278Once the build process gets the sample
262file, it uses ``sed`` to substitute final 279file, 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
285This configuration file defines 302This 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>`,
287which are directory trees, traversed (or walked) by BitBake. The 304which 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`
289variable to list the layers BitBake tries to find. 306variable to list the layers BitBake tries to find.
@@ -291,7 +308,7 @@ variable to list the layers BitBake tries to find.
291If ``bblayers.conf`` is not present when you start the build, the 308If ``bblayers.conf`` is not present when you start the build, the
292OpenEmbedded build system creates it from ``bblayers.conf.sample`` when 309OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
293you ``source`` the top-level build environment setup script (i.e. 310you ``source`` the top-level build environment setup script (i.e.
294````` <#structure-core-script>`__). 311:ref:`structure-core-script`).
295 312
296As with the ``local.conf`` file, the source ``bblayers.conf.sample`` 313As with the ``local.conf`` file, the source ``bblayers.conf.sample``
297file used depends on the ``$TEMPLATECONF`` script variable, which 314file used depends on the ``$TEMPLATECONF`` script variable, which
@@ -301,10 +318,12 @@ building from the OpenEmbedded-Core environment. Because the script
301variable points to the source of the ``bblayers.conf.sample`` file, this 318variable points to the source of the ``bblayers.conf.sample`` file, this
302implies that you can base your build from any layer by setting the 319implies that you can base your build from any layer by setting the
303variable in the top-level build environment setup script as follows: 320variable in the top-level build environment setup script as follows:
304TEMPLATECONF=your_layer/conf Once the build process gets the sample 321::
305file, it uses ``sed`` to substitute final 322
306``${``\ :term:`OEROOT`\ ``}`` values for all 323 TEMPLATECONF=your_layer/conf
307``##OEROOT##`` values. 324
325Once 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
395build process. The :term:`DEPLOY_DIR` variable points 414build process. The :term:`DEPLOY_DIR` variable points
396to this directory. For more detail on the contents of the ``deploy`` 415to this directory. For more detail on the contents of the ``deploy``
397directory, see the 416directory, 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
400SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections in the Yocto
401Project Overview and Concepts Manual. 419Project 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
434directory contains sub-directories for ``bash``, ``busybox``, and 452directory 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``
436license files with other licensing information. For information on 454license files with other licensing information. For information on
437licensing, see the "`Maintaining Open Source License Compliance During 455licensing, see the
438Your Product's 456":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
439Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
440section in the Yocto Project Development Tasks Manual. 457section 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.
461If you do accidentally delete files here, you will need to force them to 478If you do accidentally delete files here, you will need to force them to
462be re-created. In order to do that, you will need to know the target 479be re-created. In order to do that, you will need to know the target
463that produced them. For example, these commands rebuild and re-create 480that produced them. For example, these commands rebuild and re-create
464the kernel files: $ bitbake -c clean virtual/kernel $ bitbake 481the kernel files:
465virtual/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
472The OpenEmbedded build system creates this directory to hold toolchain 492The OpenEmbedded build system creates this directory to hold toolchain
473installer scripts which, when executed, install the sysroot that matches 493installer scripts which, when executed, install the sysroot that matches
474your target hardware. You can find out more about these installers in 494your target hardware. You can find out more about these installers in
475the "`Building an SDK 495the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
476Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
477section in the Yocto Project Application Development and the Extensible 496section in the Yocto Project Application Development and the Extensible
478Software Development Kit (eSDK) manual. 497Software Development Kit (eSDK) manual.
479 498
@@ -540,8 +559,8 @@ the files in the directory are empty of data, BitBake uses the filenames
540and timestamps for tracking purposes. 559and timestamps for tracking purposes.
541 560
542For information on how BitBake uses stamp files to determine if a task 561For information on how BitBake uses stamp files to determine if a task
543should be rerun, see the "`Stamp Files and the Rerunning of 562should be rerun, see the
544Tasks <&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`"
545section in the Yocto Project Overview and Concepts Manual. 564section 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
574to as the ``WORKDIR``, is created. Within this directory, the source is 593to as the ``WORKDIR``, is created. Within this directory, the source is
575unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. 594unpacked 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
577Workflow <&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow>`__" section in
578the Yocto Project Development Tasks Manual for more information.) Within 596the Yocto Project Development Tasks Manual for more information.) Within
579the ``linux-qemux86-standard-build`` directory, standard Quilt 597the ``linux-qemux86-standard-build`` directory, standard Quilt
580directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and 598directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and