mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-07-26 07:07:08 +00:00
Code Issues Projects Releases Wiki Activity

sphinx: ref-manual links fixes and many other cleanups to import

Browse Source 
(From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie
2020-09-14 22:48:44 +02:00
parent d313d972bf
commit 292598164a
16 changed files with 4883 additions and 3436 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/ref-manual/ref-structure.rst
+64 -46
View File
@@ -11,8 +11,8 @@ describes the Source Directory and gives information about those files
and directories.
For information on how to establish a local Source Directory on your
development system, see the "`Locating Yocto Project Source
Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
development system, see the
":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
section in the Yocto Project Development Tasks Manual.
.. note::
@@ -42,7 +42,7 @@ itself; consequently, most users do not need to worry about BitBake.
When you run the ``bitbake`` command, the main BitBake executable (which
resides in the ``bitbake/bin/`` directory) starts. Sourcing the
environment setup script (i.e. ````` <#structure-core-script>`__) places
environment setup script (i.e. :ref:`structure-core-script`) places
the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into
the shell's ``PATH`` environment variable.
@@ -59,14 +59,14 @@ generated by the OpenEmbedded build system in its standard configuration
where the source tree is combined with the output. The :term:`Build Directory`
is created initially when you ``source``
the OpenEmbedded build environment setup script (i.e.
````` <#structure-core-script>`__).
:ref:`structure-core-script`).
It is also possible to place output and configuration files in a
directory separate from the :term:`Source Directory` by
providing a directory name when you ``source`` the setup script. For
information on separating output from your local Source Directory files
(commonly described as an "out of tree" build), see the
"````` <#structure-core-script>`__" section.
":ref:`structure-core-script`" section.
.. _handbook:
@@ -103,9 +103,8 @@ metadata to define the Poky reference distribution.
-------------------
This directory contains the Yocto Project reference hardware Board
Support Packages (BSPs). For more information on BSPs, see the `Yocto
Project Board Support Package (BSP) Developer's
Guide <&YOCTO_DOCS_BSP_URL;>`__.
Support Packages (BSPs). For more information on BSPs, see the
:doc:`../bsp-guide/bsp-guide`.
.. _structure-meta-selftest:
@@ -131,7 +130,7 @@ This directory contains template recipes for BSP and kernel development.
This directory contains various integration scripts that implement extra
functionality in the Yocto Project environment (e.g. QEMU scripts). The
````` <#structure-core-script>`__ script prepends this directory to the
:ref:`structure-core-script` script prepends this directory to the
shell's ``PATH`` environment variable.
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
:term:`Build Directory` is created, your working
directory becomes the Build Directory, and you are presented with some
simple suggestions as to what to do next, including a list of some
possible targets to build. Here is an example: $ source
oe-init-build-env ### Shell environment set up for builds. ### You can
now run 'bitbake <target>' Common targets are: core-image-minimal
core-image-sato meta-toolchain meta-ide-support You can also run
generated qemu images with a command like 'runqemu qemux86-64' The
default output of the ``oe-init-build-env`` script is from the
possible targets to build. Here is an example:
::
$ source oe-init-build-env
### Shell environment set up for builds. ###
You can now run 'bitbake <target>'
Common targets are:
core-image-minimal
core-image-sato
meta-toolchain
meta-ide-support
You can also run generated qemu images with a command like 'runqemu qemux86-64'
The default output of the ``oe-init-build-env`` script is from the
``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
within the :term:`Source Directory`. If you design a
custom distribution, you can include your own version of this
configuration file to mention the targets defined by your distribution.
See the "`Creating a Custom Template Configuration
Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__"
See the
":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
section in the Yocto Project Development Tasks Manual for more
information.
@@ -175,11 +186,14 @@ you provide a Build Directory argument when you ``source`` the script,
you direct the OpenEmbedded build system to create a Build Directory of
your choice. For example, the following command creates a Build
Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
$ source OE_INIT_FILE ~/mybuilds The
OpenEmbedded build system uses the template configuration files, which
::
$ source OE_INIT_FILE ~/mybuilds
The OpenEmbedded build system uses the template configuration files, which
are found by default in the ``meta-poky/conf/`` directory in the Source
Directory. See the "`Creating a Custom Template Configuration
Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__"
Directory. See the
":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
section in the Yocto Project Development Tasks Manual for more
information.
@@ -207,7 +221,7 @@ The Build Directory - ``build/``
The OpenEmbedded build system creates the :term:`Build Directory`
when you run the build environment setup
script ````` <#structure-core-script>`__. If you do not give the Build
script :ref:`structure-core-script`. If you do not give the Build
Directory a specific name when you run the setup script, the name
defaults to ``build/``.
@@ -223,8 +237,7 @@ The OpenEmbedded build system creates this directory when you enable
build history via the ``buildhistory`` class file. The directory
organizes build information into image, packages, and SDK
subdirectories. For information on the build history feature, see the
"`Maintaining Build Output
Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
section in the Yocto Project Development Tasks Manual.
.. _structure-build-conf-local.conf:
@@ -248,7 +261,7 @@ which you want to access downloaded files (``DL_DIR``).
If ``local.conf`` is not present when you start the build, the
OpenEmbedded build system creates it from ``local.conf.sample`` when you
``source`` the top-level build environment setup script
````` <#structure-core-script>`__.
:ref:`structure-core-script`.
The source ``local.conf.sample`` file used depends on the
``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
@@ -258,7 +271,11 @@ environment. Because the script variable points to the source of the
``local.conf.sample`` file, this implies that you can configure your
build environment from any layer by setting the variable in the
top-level build environment setup script as follows:
TEMPLATECONF=your_layer/conf Once the build process gets the sample
::
TEMPLATECONF=your_layer/conf
Once the build process gets the sample
file, it uses ``sed`` to substitute final
``${``\ :term:`OEROOT`\ ``}`` values for all
``##OEROOT##`` values.
@@ -283,7 +300,7 @@ file, it uses ``sed`` to substitute final
----------------------------
This configuration file defines
`layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__,
:ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`,
which are directory trees, traversed (or walked) by BitBake. The
``bblayers.conf`` file uses the :term:`BBLAYERS`
variable to list the layers BitBake tries to find.
@@ -291,7 +308,7 @@ variable to list the layers BitBake tries to find.
If ``bblayers.conf`` is not present when you start the build, the
OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
you ``source`` the top-level build environment setup script (i.e.
````` <#structure-core-script>`__).
:ref:`structure-core-script`).
As with the ``local.conf`` file, the source ``bblayers.conf.sample``
file used depends on the ``$TEMPLATECONF`` script variable, which
@@ -301,10 +318,12 @@ building from the OpenEmbedded-Core environment. Because the script
variable points to the source of the ``bblayers.conf.sample`` file, this
implies that you can base your build from any layer by setting the
variable in the top-level build environment setup script as follows:
TEMPLATECONF=your_layer/conf Once the build process gets the sample
file, it uses ``sed`` to substitute final
``${``\ :term:`OEROOT`\ ``}`` values for all
``##OEROOT##`` values.
::
TEMPLATECONF=your_layer/conf
Once the build process gets the sample file, it uses ``sed`` to substitute final
``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
.. note::
@@ -395,9 +414,8 @@ This directory contains any "end result" output from the OpenEmbedded
build process. The :term:`DEPLOY_DIR` variable points
to this directory. For more detail on the contents of the ``deploy``
directory, see the
"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and
"`Application Development
SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections in the Yocto
":ref:`images-dev-environment`" and
":ref:`sdk-dev-environment`" sections in the Yocto
Project Overview and Concepts Manual.
.. _structure-build-tmp-deploy-deb:
@@ -434,9 +452,8 @@ This directory receives package licensing information. For example, the
directory contains sub-directories for ``bash``, ``busybox``, and
``glibc`` (among others) that in turn contain appropriate ``COPYING``
license files with other licensing information. For information on
licensing, see the "`Maintaining Open Source License Compliance During
Your Product's
Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
licensing, see the
":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
section in the Yocto Project Development Tasks Manual.
.. _structure-build-tmp-deploy-images:
@@ -461,8 +478,11 @@ image again.
If you do accidentally delete files here, you will need to force them to
be re-created. In order to do that, you will need to know the target
that produced them. For example, these commands rebuild and re-create
the kernel files: $ bitbake -c clean virtual/kernel $ bitbake
virtual/kernel
the kernel files:
::
$ bitbake -c clean virtual/kernel
$ bitbake virtual/kernel
.. _structure-build-tmp-deploy-sdk:
@@ -472,8 +492,7 @@ virtual/kernel
The OpenEmbedded build system creates this directory to hold toolchain
installer scripts which, when executed, install the sysroot that matches
your target hardware. You can find out more about these installers in
the "`Building an SDK
Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
section in the Yocto Project Application Development and the Extensible
Software Development Kit (eSDK) manual.
@@ -540,8 +559,8 @@ the files in the directory are empty of data, BitBake uses the filenames
and timestamps for tracking purposes.
For information on how BitBake uses stamp files to determine if a task
should be rerun, see the "`Stamp Files and the Rerunning of
Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__"
should be rerun, see the
":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`"
section in the Yocto Project Overview and Concepts Manual.
.. _structure-build-tmp-log:
@@ -573,8 +592,7 @@ built within the Yocto Project. For this package, a work directory of
``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
to as the ``WORKDIR``, is created. Within this directory, the source is
unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
(See the "`Using Quilt in Your
Workflow <&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow>`__" section in
(See the ":ref:`using-a-quilt-workflow`" section in
the Yocto Project Development Tasks Manual for more information.) Within
the ``linux-qemux86-standard-build`` directory, standard Quilt
directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and