mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-30 12:29:55 +00:00
Code Issues Projects Releases Wiki Activity

sphinx: overview-manual: Various URL, code block and other fixes to imported data

Browse Source 
(From yocto-docs rev: 3325fe660dfea24fba2f964a0060664e3c67459a)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie
2020-09-16 10:57:16 +01:00
parent dd8c9b74d3
commit fc876832cb
4 changed files with 270 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/overview-manual/overview-manual-concepts.rst
+145 -100
View File
@@ -34,14 +34,14 @@ itself is of various types:
BitBake knows how to combine multiple data sources together and refers BitBake knows how to combine multiple data sources together and refers
to each data source as a layer. For information on layers, see the to each data source as a layer. For information on layers, see the
"`Understanding and Creating ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
section of the Yocto Project Development Tasks Manual. section of the Yocto Project Development Tasks Manual.
Following are some brief details on these core components. For Following are some brief details on these core components. For
additional information on how these components interact during a build, additional information on how these components interact during a build,
see the "`OpenEmbedded Build System see the
Concepts <#openembedded-build-system-build-concepts>`__" section. ":ref:`overview-manual/overview-manual-concepts:openembedded build system concepts`"
section.
.. _usingpoky-components-bitbake: .. _usingpoky-components-bitbake:
@@ -57,14 +57,23 @@ This section briefly introduces BitBake. If you want more information on
BitBake, see the :doc:`BitBake User Manual <bitbake:index>`. BitBake, see the :doc:`BitBake User Manual <bitbake:index>`.
To see a list of the options BitBake supports, use either of the To see a list of the options BitBake supports, use either of the
following commands: $ bitbake -h $ bitbake --help following commands:
::
$ bitbake -h
$ bitbake --help
The most common usage for BitBake is ``bitbake packagename``, where The most common usage for BitBake is ``bitbake packagename``, where
``packagename`` is the name of the package you want to build (referred ``packagename`` is the name of the package you want to build (referred
to as the "target"). The target often equates to the first part of a to as the "target"). The target often equates to the first part of a
recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``). recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``).
So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might
type the following: $ bitbake matchbox-desktop Several different type the following:
::
$ bitbake matchbox-desktop
Several different
versions of ``matchbox-desktop`` might exist. BitBake chooses the one versions of ``matchbox-desktop`` might exist. BitBake chooses the one
selected by the distribution configuration. You can get more details selected by the distribution configuration. You can get more details
about how BitBake chooses between different target versions and about how BitBake chooses between different target versions and
@@ -153,9 +162,8 @@ By convention, layers in the Yocto Project follow a specific form.
Conforming to a known structure allows BitBake to make assumptions Conforming to a known structure allows BitBake to make assumptions
during builds on where to find types of metadata. You can find during builds on where to find types of metadata. You can find
procedures and learn about tools (i.e. ``bitbake-layers``) for creating procedures and learn about tools (i.e. ``bitbake-layers``) for creating
layers suitable for the Yocto Project in the "`Understanding and layers suitable for the Yocto Project in the
Creating ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
section of the Yocto Project Development Tasks Manual. section of the Yocto Project Development Tasks Manual.
.. _openembedded-build-system-build-concepts: .. _openembedded-build-system-build-concepts:
@@ -225,7 +233,7 @@ reside as example files in the ``build/conf`` directory of the
:term:`Source Directory`. For simplicity, :term:`Source Directory`. For simplicity,
this section refers to the Source Directory as the "Poky Directory." this section refers to the Source Directory as the "Poky Directory."
When you clone the `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository When you clone the :term:`Poky` Git repository
or you download and unpack a Yocto Project release, you can set up the or you download and unpack a Yocto Project release, you can set up the
Source Directory to be named anything you want. For this discussion, the Source Directory to be named anything you want. For this discussion, the
cloned repository uses the default name ``poky``. cloned repository uses the default name ``poky``.
@@ -238,7 +246,7 @@ cloned repository uses the default name ``poky``.
The ``meta-poky`` layer inside Poky contains a ``conf`` directory that The ``meta-poky`` layer inside Poky contains a ``conf`` directory that
has example configuration files. These example files are used as a basis has example configuration files. These example files are used as a basis
for creating actual configuration files when you source for creating actual configuration files when you source
````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, which is the :ref:`structure-core-script`, which is the
build environment script. build environment script.
Sourcing the build environment script creates a 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
source the build environment setup script. source the build environment setup script.
Because the Poky repository is fundamentally an aggregation of existing Because the Poky repository is fundamentally an aggregation of existing
repositories, some users might be familiar with running the ```` script repositories, some users might be familiar with running the
in the context of separate :ref:`structure-core-script` script in the context of separate
:term:`OpenEmbedded-Core (OE-Core)` and BitBake :term:`OpenEmbedded-Core (OE-Core)` and BitBake
repositories rather than a single Poky repository. This discussion repositories rather than a single Poky repository. This discussion
assumes the script is executed from within a cloned or unpacked version 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
during the build. By default, the layers listed in this file include during the build. By default, the layers listed in this file include
layers minimally needed by the build system. However, you must manually layers minimally needed by the build system. However, you must manually
add any custom layers you have created. You can find more information on add any custom layers you have created. You can find more information on
working with the ``bblayers.conf`` file in the "`Enabling Your working with the ``bblayers.conf`` file in the
Layer <&YOCTO_DOCS_DEV_URL;#enabling-your-layer>`__" section in the ":ref:`dev-manual/dev-manual-common-tasks:enabling your layer`"
Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
The files ``site.conf`` and ``auto.conf`` are not created by the The files ``site.conf`` and ``auto.conf`` are not created by the
environment initialization script. If you want the ``site.conf`` file, environment initialization script. If you want the ``site.conf`` file,
you need to create that yourself. The ``auto.conf`` file is typically you need to create that yourself. The ``auto.conf`` file is typically
created by an autobuilder: created by an autobuilder:
- *``site.conf``:* You can use the ``conf/site.conf`` configuration - *site.conf:* You can use the ``conf/site.conf`` configuration
file to configure multiple build directories. For example, suppose file to configure multiple build directories. For example, suppose
you had several build environments and they shared some common you had several build environments and they shared some common
features. You can set these default build properties here. A good features. You can set these default build properties here. A good
@@ -346,7 +354,7 @@ created by an autobuilder:
configurations within that build directory's ``conf/local.conf`` configurations within that build directory's ``conf/local.conf``
file. file.
- *``auto.conf``:* The file is usually created and written to by an - *auto.conf:* The file is usually created and written to by an
autobuilder. The settings put into the file are typically the same as autobuilder. The settings put into the file are typically the same as
you would find in the ``conf/local.conf`` or the ``conf/site.conf`` you would find in the ``conf/local.conf`` or the ``conf/site.conf``
files. files.
@@ -382,10 +390,10 @@ In general, three types of layer input exists. You can see them below
the "User Configuration" box in the `general workflow the "User Configuration" box in the `general workflow
figure <#general-workflow-figure>`__: figure <#general-workflow-figure>`__:
- *Metadata (``.bb`` + Patches):* Software layers containing - *Metadata (.bb + Patches):* Software layers containing
user-supplied recipe files, patches, and append files. A good example user-supplied recipe files, patches, and append files. A good example
of a software layer might be the of a software layer might be the
```meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from `meta-qt5 layer <https://github.com/meta-qt5/meta-qt5>`__ from
the `OpenEmbedded Layer the `OpenEmbedded Layer
Index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__. Index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__.
This layer is for version 5.0 of the popular 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,
a ``README`` file as good practice and especially if the layer is to be a ``README`` file as good practice and especially if the layer is to be
distributed, a configuration directory, and recipe directories. You can distributed, a configuration directory, and recipe directories. You can
learn about the general structure for layers used with the Yocto Project learn about the general structure for layers used with the Yocto Project
in the "`Creating Your Own in the
Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in the ":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`"
section in the
Yocto Project Development Tasks Manual. For a general discussion on Yocto Project Development Tasks Manual. For a general discussion on
layers and the many layers from which you can draw, see the layers and the many layers from which you can draw, see the
"`Layers <#overview-layers>`__" and "`The Yocto Project Layer "`Layers <#overview-layers>`__" and "`The Yocto Project Layer
@@ -485,8 +494,7 @@ The BSP Layer provides machine configurations that target specific
hardware. Everything in this layer is specific to the machine for which hardware. Everything in this layer is specific to the machine for which
you are building the image or the SDK. A common structure or form is you are building the image or the SDK. A common structure or form is
defined for BSP layers. You can learn more about this structure in the defined for BSP layers. You can learn more about this structure in the
`Yocto Project Board Support Package (BSP) Developer's :doc:`../bsp-guide/bsp-guide`.
Guide <&YOCTO_DOCS_BSP_URL;>`__.
.. note:: .. note::
@@ -704,8 +712,8 @@ architecture are placed in ``build/tmp/deploy/ipk/qemux86``.
.. _bitbake-dev-environment: .. _bitbake-dev-environment:
BitBake BitBake Tool
------- ------------
The OpenEmbedded build system uses The OpenEmbedded build system uses
:term:`BitBake` to produce images and :term:`BitBake` to produce images and
@@ -751,8 +759,7 @@ the source files and unpack them into the
By default, everything is accomplished in the Build Directory, which has By default, everything is accomplished in the Build Directory, which has
a defined structure. For additional general information on the Build a defined structure. For additional general information on the Build
Directory, see the Directory, see the ":ref:`structure-core-build`" section in
"```build/`` <&YOCTO_DOCS_REF_URL;#structure-core-build>`__" section in
the Yocto Project Reference Manual. the Yocto Project Reference Manual.
Each recipe has an area in the Build Directory where the unpacked source Each recipe has an area in the Build Directory where the unpacked source
@@ -769,8 +776,7 @@ Build Directory's hierarchy:
- :term:`PACKAGE_ARCH`: The - :term:`PACKAGE_ARCH`: The
architecture of the built package or packages. Depending on the architecture of the built package or packages. Depending on the
eventual destination of the package or packages (i.e. machine eventual destination of the package or packages (i.e. machine
architecture, `build architecture, :term:`Build Host`, SDK, or
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, SDK, or
specific machine), ``PACKAGE_ARCH`` varies. See the variable's specific machine), ``PACKAGE_ARCH`` varies. See the variable's
description for details. description for details.
@@ -846,15 +852,14 @@ source files, which are located in the
For more information on how the source directories are created, see the For more information on how the source directories are created, see the
"`Source Fetching <#source-fetching-dev-environment>`__" section. For "`Source Fetching <#source-fetching-dev-environment>`__" section. For
more information on how to create patches and how the build system more information on how to create patches and how the build system
processes patches, see the "`Patching processes patches, see the
Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in the ":ref:`dev-manual/dev-manual-common-tasks:patching code`"
Yocto Project Development Tasks Manual. You can also see the "`Use section in the
``devtool modify`` to Modify the Source of an Existing Yocto Project Development Tasks Manual. You can also see the
Component <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component>`__" ":ref:`sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component`"
section in the Yocto Project Application Development and the Extensible section in the Yocto Project Application Development and the Extensible
Software Development Kit (SDK) manual and the "`Using Traditional Kernel Software Development Kit (SDK) manual and the
Development to Patch the ":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#using-traditional-kernel-development-to-patch-the-kernel>`__"
section in the Yocto Project Linux Kernel Development Manual. section in the Yocto Project Linux Kernel Development Manual.
.. _configuration-compilation-and-staging-dev-environment: .. _configuration-compilation-and-staging-dev-environment:
@@ -882,7 +887,7 @@ This step in the build process consists of the following tasks:
depends. A sysroot exists for both the target and for the native depends. A sysroot exists for both the target and for the native
binaries, which run on the host system. binaries, which run on the host system.
- *``do_configure``*: This task configures the source by enabling and - *do_configure*: This task configures the source by enabling and
disabling any build-time and configuration options for the software disabling any build-time and configuration options for the software
being built. Configurations can come from the recipe itself as well being built. Configurations can come from the recipe itself as well
as from an inherited class. Additionally, the software itself might 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:
:ref:`autotools <ref-classes-autotools>` class :ref:`autotools <ref-classes-autotools>` class
:yocto_git:`here </cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`. :yocto_git:`here </cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`.
- *``do_compile``*: Once a configuration task has been satisfied, - *do_compile*: Once a configuration task has been satisfied,
BitBake compiles the source using the BitBake compiles the source using the
:ref:`ref-tasks-compile` task. :ref:`ref-tasks-compile` task.
Compilation occurs in the directory pointed to by the Compilation occurs in the directory pointed to by the
@@ -911,7 +916,7 @@ This step in the build process consists of the following tasks:
``B`` directory is, by default, the same as the ``B`` directory is, by default, the same as the
:term:`S` directory. :term:`S` directory.
- *``do_install``*: After compilation completes, BitBake executes the - *do_install*: After compilation completes, BitBake executes the
:ref:`ref-tasks-install` task. :ref:`ref-tasks-install` task.
This task copies files from the ``B`` directory and places them in a This task copies files from the ``B`` directory and places them in a
holding area pointed to by the :term:`D` 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
stage of package installation, post installation scripts that are part stage of package installation, post installation scripts that are part
of the packages are run. Any scripts that fail to run on the build host of the packages are run. Any scripts that fail to run on the build host
are run on the target when the target system is first booted. If you are are run on the target when the target system is first booted. If you are
using a `read-only root using a
filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__, :ref:`read-only root filesystem <dev-manual/dev-manual-common-tasks:creating a read-only root filesystem>`,
all the post installation scripts must succeed on the build host during all the post installation scripts must succeed on the build host during
the package installation phase since the root filesystem on the target the package installation phase since the root filesystem on the target
is read-only. is read-only.
@@ -1097,9 +1102,17 @@ the image. The formats used for the root filesystem depend on the
support compression. support compression.
As an example, a dynamically created task when creating a particular As an example, a dynamically created task when creating a particular
image type would take the following form: do_image_type So, if the type image type would take the following form:
::
do_image_type
So, if the type
as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically
generated task would be as follows: do_image_ext4 generated task would be as follows:
::
do_image_ext4
The final task involved in image creation is the The final task involved in image creation is the
:ref:`do_image_complete <ref-tasks-image-complete>` :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
also always be considered out of date, which might not be what you want. also always be considered out of date, which might not be what you want.
For details on how to view information about a task's signature, see the For details on how to view information about a task's signature, see the
"`Viewing Task Variable ":ref:`dev-manual/dev-manual-common-tasks:viewing task variable dependencies`"
Dependencies <&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
Setscene Tasks and Shared State Setscene Tasks and Shared State
@@ -1397,8 +1409,7 @@ can initialize the environment before using the tools.
section. section.
- For information on setting up a cross-development environment, see - For information on setting up a cross-development environment, see
the `Yocto Project Application Development and the Extensible the :doc:`../sdk-manual/sdk-manual` manual.
Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
All the output files for an SDK are written to the ``deploy/sdk`` folder All the output files for an SDK are written to the ``deploy/sdk`` folder
inside the :term:`Build Directory` as inside the :term:`Build Directory` as
@@ -1475,13 +1486,10 @@ Cross-Development Toolchain Generation
====================================== ======================================
The Yocto Project does most of the work for you when it comes to The Yocto Project does most of the work for you when it comes to
creating `cross-development creating :ref:`sdk-manual/sdk-intro:the cross-development toolchain`. This
toolchains <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__. This
section provides some technical background on how cross-development section provides some technical background on how cross-development
toolchains are created and used. For more information on toolchains, you toolchains are created and used. For more information on toolchains, you
can also see the `Yocto Project Application Development and the can also see the :doc:`../sdk-manual/sdk-manual` manual.
Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__
manual.
In the Yocto Project development environment, cross-development In the Yocto Project development environment, cross-development
toolchains are used to build images and applications that run on the 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.
. .
The chain of events that occurs when ``gcc-cross`` is bootstrapped is as The chain of events that occurs when ``gcc-cross`` is bootstrapped is as
follows: gcc -> binutils-cross -> gcc-cross-initial -> follows:
linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime ::
gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
- ``gcc``: The build host's GNU Compiler Collection (GCC). - ``gcc``: The build host's GNU Compiler Collection (GCC).
@@ -1571,9 +1581,10 @@ might not be the same machine as the Build Host.
can take advantage of pre-built images that ship with the Yocto can take advantage of pre-built images that ship with the Yocto
Project and already contain cross-development toolchain installers. Project and already contain cross-development toolchain installers.
Here is the bootstrap process for the relocatable toolchain: gcc -> Here is the bootstrap process for the relocatable toolchain:
binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> ::
glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
- ``gcc``: The build host's GNU Compiler Collection (GCC). - ``gcc``: The build host's GNU Compiler Collection (GCC).
@@ -1668,18 +1679,15 @@ them if they are deemed to be valid.
the shared state packages. Consequently, considerations exist that the shared state packages. Consequently, considerations exist that
affect maintaining shared state feeds. For information on how the affect maintaining shared state feeds. For information on how the
build system works with packages and can track incrementing ``PR`` build system works with packages and can track incrementing ``PR``
information, see the "`Automatically Incrementing a Binary Package information, see the ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`"
Revision
Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
- The code in the build system that supports incremental builds is - The code in the build system that supports incremental builds is
not simple code. For techniques that help you work around issues not simple code. For techniques that help you work around issues
related to shared state code, see the "`Viewing Metadata Used to related to shared state code, see the
Create the Input Signature of a Shared State ":ref:`dev-manual/dev-manual-common-tasks:viewing metadata used to create the input signature of a shared state task`"
Task <&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task>`__" and
and "`Invalidating Shared State to Force a Task to ":ref:`dev-manual/dev-manual-common-tasks:invalidating shared state to force a task to run`"
Run <&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run>`__"
sections both in the Yocto Project Development Tasks Manual. sections both in the Yocto Project Development Tasks Manual.
The rest of this section goes into detail about the overall incremental The rest of this section goes into detail about the overall incremental
@@ -1754,15 +1762,22 @@ to the task.
Like the ``WORKDIR`` case, situations exist where dependencies should be Like the ``WORKDIR`` case, situations exist where dependencies should be
ignored. For these situations, you can instruct the build process to ignored. For these situations, you can instruct the build process to
ignore a dependency by using a line like the following: ignore a dependency by using a line like the following:
PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the ::
:term:`PACKAGE_ARCHS` variable
does not depend on the value of PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
:term:`MACHINE`, even if it does
This example ensures that the :term:`PACKAGE_ARCHS` variable
does not depend on the value of :term:`MACHINE`, even if it does
reference it. reference it.
Equally, there are cases where you need to add dependencies BitBake is Equally, there are cases where you need to add dependencies BitBake is
not able to find. You can accomplish this by using a line like the not able to find. You can accomplish this by using a line like the
following: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly following:
::
PACKAGE_ARCHS[vardeps] = "MACHINE"
This example explicitly
adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``. adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``.
As an example, consider a case with in-line Python where BitBake is not 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
configuration file, you can give BitBake some extra information to help configuration file, you can give BitBake some extra information to help
it construct the basehash. The following statement effectively results it construct the basehash. The following statement effectively results
in a list of global variable dependency excludes (i.e. variables never in a list of global variable dependency excludes (i.e. variables never
included in any checksum): BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH included in any checksum):
PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS ::
FILE_DIRNAME HOME LOGNAME SHELL TERM \\ USER FILESPATH STAGING_DIR_HOST
STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\
PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\
EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \\
PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\
CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
The
previous example excludes previous example excludes
:term:`WORKDIR` since that variable :term:`WORKDIR` since that variable
is actually constructed as a path within is actually constructed as a path within
@@ -1810,8 +1829,12 @@ desired. This file defines the two basic signature generators
"OEBasicHash". By default, a dummy "noop" signature handler is enabled "OEBasicHash". By default, a dummy "noop" signature handler is enabled
in BitBake. This means that behavior is unchanged from previous in BitBake. This means that behavior is unchanged from previous
versions. OE-Core uses the "OEBasicHash" signature handler by default versions. OE-Core uses the "OEBasicHash" signature handler by default
through this setting in the ``bitbake.conf`` file: BB_SIGNATURE_HANDLER through this setting in the ``bitbake.conf`` file:
?= "OEBasicHash" The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same ::
BB_SIGNATURE_HANDLER ?= "OEBasicHash"
The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same
as the "OEBasic" version but adds the task hash to the `stamp as the "OEBasic" version but adds the task hash to the `stamp
files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any
metadata change that changes the task hash, automatically causing the metadata change that changes the task hash, automatically causing the
@@ -1862,12 +1885,21 @@ implementation hidden in ``sstate`` class. From a user's perspective,
adding shared state wrapping to a task is as simple as this adding shared state wrapping to a task is as simple as this
:ref:`ref-tasks-deploy` example taken :ref:`ref-tasks-deploy` example taken
from the :ref:`deploy <ref-classes-deploy>` class: from the :ref:`deploy <ref-classes-deploy>` class:
DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy" ::
do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" python DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
do_deploy_setscene () { sstate_setscene(d) } addtask do_deploy_setscene SSTATETASKS += "do_deploy"
do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] = do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
"${MACHINE_ARCH}" The following list explains the previous example: do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
python do_deploy_setscene () {
sstate_setscene(d)
}
addtask do_deploy_setscene
do_deploy[dirs] = "${DEPLOYDIR} ${B}"
do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"
The following list explains the previous example:
- Adding "do_deploy" to ``SSTATETASKS`` adds some required - Adding "do_deploy" to ``SSTATETASKS`` adds some required
sstate-related processing, which is implemented in the sstate-related processing, which is implemented in the
@@ -1907,9 +1939,15 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
task. task.
- The following task definition is glue logic needed to make the - The following task definition is glue logic needed to make the
previous settings effective: python do_deploy_setscene () { previous settings effective:
sstate_setscene(d) } addtask do_deploy_setscene ``sstate_setscene()`` ::
takes the flags above as input and accelerates the ``do_deploy`` task
python do_deploy_setscene () {
sstate_setscene(d)
}
addtask do_deploy_setscene
``sstate_setscene()`` takes the flags above as input and accelerates the ``do_deploy`` task
through the shared state cache if possible. If the task was through the shared state cache if possible. If the task was
accelerated, ``sstate_setscene()`` returns True. Otherwise, it accelerated, ``sstate_setscene()`` returns True. Otherwise, it
returns False, and the normal ``do_deploy`` task runs. For more returns False, and the normal ``do_deploy`` task runs. For more
@@ -1956,20 +1994,27 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories, ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories,
which populates the shared state cache, and ``PKGDATA_DIR`` and which populates the shared state cache, and ``PKGDATA_DIR`` and
``SHLIBSDIR`` as the corresponding shared state output directories: ``SHLIBSDIR`` as the corresponding shared state output directories:
do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" ::
do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
- These methods also include the ability to take a lockfile when - These methods also include the ability to take a lockfile when
manipulating shared state directory structures, for cases where file manipulating shared state directory structures, for cases where file
additions or removals are sensitive: do_package[sstate-lockfile] = additions or removals are sensitive:
"${PACKAGELOCK}" ::
do_package[sstate-lockfile] = "${PACKAGELOCK}"
Behind the scenes, the shared state code works by looking in Behind the scenes, the shared state code works by looking in
:term:`SSTATE_DIR` and :term:`SSTATE_DIR` and
:term:`SSTATE_MIRRORS` for :term:`SSTATE_MIRRORS` for
shared state files. Here is an example: SSTATE_MIRRORS ?= "\\ file://.\* shared state files. Here is an example:
http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\ ::
file://.\* file:///some/local/dir/sstate/PATH"
SSTATE_MIRRORS ?= "\
file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
file://.\* file:///some/local/dir/sstate/PATH"
.. note:: .. note::
@@ -2164,10 +2209,10 @@ accomplished using fakeroot.
, giving the following: , giving the following:
:: ::
fakeroot do_mytask () { fakeroot do_mytask () {
... ...
} }
do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
For more information, see the For more information, see the
documentation/overview-manual/overview-manual-development-environment.rst
+77 -74
View File
@@ -50,8 +50,7 @@ Community
The Development Host The Development Host
==================== ====================
A development host or `build A development host or :term:`Build Host` is key to
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ is key to
using the Yocto Project. Because the goal of the Yocto Project is to using the Yocto Project. Because the goal of the Yocto Project is to
develop images or applications that run on embedded hardware, develop images or applications that run on embedded hardware,
development of those images and applications generally takes place on a development of those images and applications generally takes place on a
@@ -68,8 +67,9 @@ set it up as the development host by using
to set up a CROPS machine, you effectively have access to a shell to set up a CROPS machine, you effectively have access to a shell
environment that is similar to what you see when using a Linux-based environment that is similar to what you see when using a Linux-based
development host. For the steps needed to set up a system using CROPS, development host. For the steps needed to set up a system using CROPS,
see the "`Setting Up to Use CROss PlatformS see the
(CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section in ":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`"
section in
the Yocto Project Development Tasks Manual. the Yocto Project Development Tasks Manual.
If your development host is going to be a system that runs a Linux If your development host is going to be a system that runs a Linux
@@ -78,8 +78,8 @@ for use with the Yocto Project. You need to be sure that the Linux
distribution on the system is one that supports the Yocto Project. You distribution on the system is one that supports the Yocto Project. You
also need to be sure that the correct set of host packages are installed also need to be sure that the correct set of host packages are installed
that allow development using the Yocto Project. For the steps needed to that allow development using the Yocto Project. For the steps needed to
set up a development host that runs Linux, see the "`Setting Up a Native set up a development host that runs Linux, see the
Linux Host <&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host>`__" ":ref:`dev-manual/dev-manual-start:setting up a native linux host`"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
Once your development host is set up to use the Yocto Project, several Once your development host is set up to use the Yocto Project, several
@@ -95,8 +95,8 @@ methods exist for you to do work in the Yocto Project environment:
within a shell-based environment using components and tools available within a shell-based environment using components and tools available
through your Linux distribution and the Yocto Project. through your Linux distribution and the Yocto Project.
For a general flow of the build procedures, see the "`Building a For a general flow of the build procedures, see the
Simple Image <&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image>`__" ":ref:`dev-manual/dev-manual-common-tasks:building a simple image`"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
- *Board Support Package (BSP) Development:* Development of BSPs - *Board Support Package (BSP) Development:* Development of BSPs
@@ -105,11 +105,9 @@ methods exist for you to do work in the Yocto Project environment:
hardware. To development BSPs, you need to take some additional steps hardware. To development BSPs, you need to take some additional steps
beyond what was described in setting up a development host. beyond what was described in setting up a development host.
The `Yocto Project Board Support Package (BSP) Developer's The :doc:`../bsp-guide/bsp-guide` provides BSP-related development
Guide <&YOCTO_DOCS_BSP_URL;>`__ provides BSP-related development
information. For specifics on development host preparation, see the information. For specifics on development host preparation, see the
"`Preparing Your Build Host to Work With BSP ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
Layers <&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers>`__"
section in the Yocto Project Board Support Package (BSP) Developer's section in the Yocto Project Board Support Package (BSP) Developer's
Guide. Guide.
@@ -118,11 +116,10 @@ methods exist for you to do work in the Yocto Project environment:
using ``devtool`` makes kernel development quicker by reducing using ``devtool`` makes kernel development quicker by reducing
iteration cycle times. iteration cycle times.
The `Yocto Project Linux Kernel Development The :doc:`../kernel-dev/kernel-dev` provides kernel-related
Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__ provides kernel-related
development information. For specifics on development host development information. For specifics on development host
preparation, see the "`Preparing the Build Host to Work on the preparation, see the
Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel>`__" ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
section in the Yocto Project Linux Kernel Development Manual. section in the Yocto Project Linux Kernel Development Manual.
- *Using Toaster:* The other Yocto Project development method that - *Using Toaster:* The other Yocto Project development method that
@@ -134,8 +131,8 @@ methods exist for you to do work in the Yocto Project environment:
multiple remote build servers. multiple remote build servers.
For steps that show you how to set up your development host to use For steps that show you how to set up your development host to use
Toaster and on how to use Toaster in general, see the `Toaster User Toaster and on how to use Toaster in general, see the
Manual <&YOCTO_DOCS_TOAST_URL;>`__. :doc:`../toaster-manual/toaster-manual`.
.. _yocto-project-repositories: .. _yocto-project-repositories:
@@ -185,8 +182,7 @@ development:
:align: center :align: center
For steps on how to view and access these upstream Git repositories, For steps on how to view and access these upstream Git repositories,
see the "`Accessing Source see the ":ref:`dev-manual/dev-manual-start:accessing source repositories`"
Repositories <&YOCTO_DOCS_DEV_URL;#accessing-source-repositories>`__"
Section in the Yocto Project Development Tasks Manual. Section in the Yocto Project Development Tasks Manual.
- :yocto_dl:`Index of /releases: <releases>` This is an index - :yocto_dl:`Index of /releases: <releases>` This is an index
@@ -199,9 +195,8 @@ development:
.. image:: figures/index-downloads.png .. image:: figures/index-downloads.png
:align: center :align: center
For steps on how to view and access these files, see the "`Accessing For steps on how to view and access these files, see the
Index of ":ref:`dev-manual/dev-manual-start:accessing index of releases`"
Releases <&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
- *"DOWNLOADS" page for the* :yocto_home:`Yocto Project Website <>` *:* - *"DOWNLOADS" page for the* :yocto_home:`Yocto Project Website <>` *:*
@@ -215,8 +210,8 @@ development:
.. image:: figures/yp-download.png .. image:: figures/yp-download.png
:align: center :align: center
For steps on how to use the "DOWNLOADS" page, see the "`Using the For steps on how to use the "DOWNLOADS" page, see the
Downloads Page <&YOCTO_DOCS_DEV_URL;#using-the-downloads-page>`__" ":ref:`dev-manual/dev-manual-start:using the downloads page`"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
.. _gs-git-workflows-and-the-yocto-project: .. _gs-git-workflows-and-the-yocto-project:
@@ -252,9 +247,9 @@ and so forth.
.. note:: .. note::
For information on finding out who is responsible for (maintains) a For information on finding out who is responsible for (maintains) a
particular area of code in the Yocto Project, see the " particular area of code in the Yocto Project, see the
Submitting a Change to the Yocto Project ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
" section of the Yocto Project Development Tasks Manual. section of the Yocto Project Development Tasks Manual.
The Yocto Project ``poky`` Git repository also has an upstream The Yocto Project ``poky`` Git repository also has an upstream
contribution Git repository named ``poky-contrib``. You can see all the contribution Git repository named ``poky-contrib``. You can see all the
@@ -284,9 +279,9 @@ A somewhat formal method exists by which developers commit changes and
push them into the "contrib" area and subsequently request that the push them into the "contrib" area and subsequently request that the
maintainer include them into an upstream branch. This process is called maintainer include them into an upstream branch. This process is called
“submitting a patch” or "submitting a change." For information on “submitting a patch” or "submitting a change." For information on
submitting patches and changes, see the "`Submitting a Change to the submitting patches and changes, see the
Yocto Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
In summary, a single point of entry exists for changes into a "master" In summary, a single point of entry exists for changes into a "master"
or development branch of the Git repository, which is controlled by the or development branch of the Git repository, which is controlled by the
@@ -351,20 +346,18 @@ Book <http://book.git-scm.com>`__.
release to facilitate this workflow. You can find these scripts in release to facilitate this workflow. You can find these scripts in
the ``scripts`` folder of the the ``scripts`` folder of the
:term:`Source Directory`. For information :term:`Source Directory`. For information
on how to use these scripts, see the "`Using Scripts to Push a Change on how to use these scripts, see the
Upstream and Request a ":ref:`dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull`"
Pull <&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream>`__" section in section in the Yocto Project Development Tasks Manual.
the Yocto Project Development Tasks Manual.
- *Patch Workflow:* This workflow allows you to notify the maintainer - *Patch Workflow:* This workflow allows you to notify the maintainer
through an email that you have a change (or patch) you would like through an email that you have a change (or patch) you would like
considered for the "master" branch of the Git repository. To send considered for the "master" branch of the Git repository. To send
this type of change, you format the patch and then send the email this type of change, you format the patch and then send the email
using the Git commands ``git format-patch`` and ``git send-email``. using the Git commands ``git format-patch`` and ``git send-email``.
For information on how to use these scripts, see the "`Submitting a For information on how to use these scripts, see the
Change to the Yocto ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section in section in the Yocto Project Development Tasks Manual.
the Yocto Project Development Tasks Manual.
Git Git
=== ===
@@ -389,8 +382,7 @@ commands.
page, see http://git-scm.com/download. page, see http://git-scm.com/download.
- For information beyond the introductory nature in this section, - For information beyond the introductory nature in this section,
see the "`Locating Yocto Project Source see the ":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
Repositories, Tags, and Branches Repositories, Tags, and Branches
@@ -422,14 +414,13 @@ You can create a local copy of any repository by "cloning" it with the
an identical copy of the repository on your development system. Once you an identical copy of the repository on your development system. Once you
have a local copy of a repository, you can take steps to develop have a local copy of a repository, you can take steps to develop
locally. For examples on how to clone Git repositories, see the locally. For examples on how to clone Git repositories, see the
"`Locating Yocto Project Source ":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
It is important to understand that Git tracks content change and not It is important to understand that Git tracks content change and not
files. Git uses "branches" to organize different development efforts. files. Git uses "branches" to organize different development efforts.
For example, the ``poky`` repository has several branches that include For example, the ``poky`` repository has several branches that include
the current "DISTRO_NAME_NO_CAP" branch, the "master" branch, and many the current "&DISTRO_NAME_NO_CAP;" branch, the "master" branch, and many
branches for past Yocto Project releases. You can see all the branches branches for past Yocto Project releases. You can see all the branches
by going to https://git.yoctoproject.org/cgit.cgi/poky/ and clicking on the by going to https://git.yoctoproject.org/cgit.cgi/poky/ and clicking on the
``[...]`` link beneath the "Branch" heading. ``[...]`` link beneath the "Branch" heading.
@@ -444,17 +435,23 @@ local working area (also called a branch) that tracks a specific
development branch from the upstream source Git repository. in other development branch from the upstream source Git repository. in other
words, you can define your local Git environment to work on any words, you can define your local Git environment to work on any
development branch in the repository. To help illustrate, consider the development branch in the repository. To help illustrate, consider the
following example Git commands: $ cd ~ $ git clone following example Git commands:
git://git.yoctoproject.org/poky $ cd poky $ git checkout -b ::
DISTRO_NAME_NO_CAP origin/DISTRO_NAME_NO_CAP In the previous example
$ cd ~
$ git clone git://git.yoctoproject.org/poky
$ cd poky
$ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
In the previous example
after moving to the home directory, the ``git clone`` command creates a after moving to the home directory, the ``git clone`` command creates a
local copy of the upstream ``poky`` Git repository. By default, Git local copy of the upstream ``poky`` Git repository. By default, Git
checks out the "master" branch for your work. After changing the working checks out the "master" branch for your work. After changing the working
directory to the new local repository (i.e. ``poky``), the directory to the new local repository (i.e. ``poky``), the
``git checkout`` command creates and checks out a local branch named ``git checkout`` command creates and checks out a local branch named
"DISTRO_NAME_NO_CAP", which tracks the upstream "&DISTRO_NAME_NO_CAP;", which tracks the upstream
"origin/DISTRO_NAME_NO_CAP" branch. Changes you make while in this "origin/&DISTRO_NAME_NO_CAP;" branch. Changes you make while in this
branch would ultimately affect the upstream "DISTRO_NAME_NO_CAP" branch branch would ultimately affect the upstream "&DISTRO_NAME_NO_CAP;" branch
of the ``poky`` repository. of the ``poky`` repository.
It is important to understand that when you create and checkout a local It is important to understand that when you create and checkout a local
@@ -462,7 +459,7 @@ working branch based on a branch name, your local environment matches
the "tip" of that particular development branch at the time you created the "tip" of that particular development branch at the time you created
your local branch, which could be different from the files in the your local branch, which could be different from the files in the
"master" branch of the upstream repository. In other words, creating and "master" branch of the upstream repository. In other words, creating and
checking out a local branch based on the "DISTRO_NAME_NO_CAP" branch checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch
name is not the same as checking out the "master" branch in the name is not the same as checking out the "master" branch in the
repository. Keep reading to see how you create a local snapshot of a repository. Keep reading to see how you create a local snapshot of a
Yocto Project Release. Yocto Project Release.
@@ -476,7 +473,7 @@ beneath the "Tag" heading.
Some key tags for the ``poky`` repository are ``jethro-14.0.3``, Some key tags for the ``poky`` repository are ``jethro-14.0.3``,
``morty-16.0.1``, ``pyro-17.0.0``, and ``morty-16.0.1``, ``pyro-17.0.0``, and
``DISTRO_NAME_NO_CAP-POKYVERSION``. These tags represent Yocto Project ``&DISTRO_NAME_NO_CAP;-&POKYVERSION;``. These tags represent Yocto Project
releases. releases.
When you create a local copy of the Git repository, you also have access When you create a local copy of the Git repository, you also have access
@@ -485,9 +482,16 @@ create and checkout a local working Git branch based on a tag name. When
you do this, you get a snapshot of the Git repository that reflects the you do this, you get a snapshot of the Git repository that reflects the
state of the files when the change was made associated with that tag. state of the files when the change was made associated with that tag.
The most common use is to checkout a working branch that matches a The most common use is to checkout a working branch that matches a
specific Yocto Project release. Here is an example: $ cd ~ $ git clone specific Yocto Project release. Here is an example:
git://git.yoctoproject.org/poky $ cd poky $ git fetch --tags $ git ::
checkout tags/rocko-18.0.0 -b my_rocko-18.0.0 In this example, the name
$ cd ~
$ git clone git://git.yoctoproject.org/poky
$ cd poky
$ git fetch --tags
$ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
In this example, the name
of the top-level directory of your local Yocto Project repository is of the top-level directory of your local Yocto Project repository is
``poky``. After moving to the ``poky`` directory, the ``git fetch`` ``poky``. After moving to the ``poky`` directory, the ``git fetch``
command makes all the upstream tags available locally in your command makes all the upstream tags available locally in your
@@ -518,62 +522,62 @@ list (in most cases) simply shows the base command and omits the many
arguments it supports. See the Git documentation for complete arguments it supports. See the Git documentation for complete
descriptions and strategies on how to use these commands: descriptions and strategies on how to use these commands:
- *``git init``:* Initializes an empty Git repository. You cannot use - *git init:* Initializes an empty Git repository. You cannot use
Git commands unless you have a ``.git`` repository. Git commands unless you have a ``.git`` repository.
- *``git clone``:* Creates a local clone of a Git repository that is on - *git clone:* Creates a local clone of a Git repository that is on
equal footing with a fellow developer’s Git repository or an upstream equal footing with a fellow developer’s Git repository or an upstream
repository. repository.
- *``git add``:* Locally stages updated file contents to the index that - *git add:* Locally stages updated file contents to the index that
Git uses to track changes. You must stage all files that have changed Git uses to track changes. You must stage all files that have changed
before you can commit them. before you can commit them.
- *``git commit``:* Creates a local "commit" that documents the changes - *git commit:* Creates a local "commit" that documents the changes
you made. Only changes that have been staged can be committed. you made. Only changes that have been staged can be committed.
Commits are used for historical purposes, for determining if a Commits are used for historical purposes, for determining if a
maintainer of a project will allow the change, and for ultimately maintainer of a project will allow the change, and for ultimately
pushing the change from your local Git repository into the project’s pushing the change from your local Git repository into the project’s
upstream repository. upstream repository.
- *``git status``:* Reports any modified files that possibly need to be - *git status:* Reports any modified files that possibly need to be
staged and gives you a status of where you stand regarding local staged and gives you a status of where you stand regarding local
commits as compared to the upstream repository. commits as compared to the upstream repository.
- *``git checkout`` branch-name:* Changes your local working branch and - *git checkout branch-name:* Changes your local working branch and
in this form assumes the local branch already exists. This command is in this form assumes the local branch already exists. This command is
analogous to "cd". analogous to "cd".
- *``git checkout –b`` working-branch upstream-branch:* Creates and - *git checkout –b working-branch upstream-branch:* Creates and
checks out a working branch on your local machine. The local branch checks out a working branch on your local machine. The local branch
tracks the upstream branch. You can use your local branch to isolate tracks the upstream branch. You can use your local branch to isolate
your work. It is a good idea to use local branches when adding your work. It is a good idea to use local branches when adding
specific features or changes. Using isolated branches facilitates specific features or changes. Using isolated branches facilitates
easy removal of changes if they do not work out. easy removal of changes if they do not work out.
- *``git branch``:* Displays the existing local branches associated - *git branch:* Displays the existing local branches associated
with your local repository. The branch that you have currently with your local repository. The branch that you have currently
checked out is noted with an asterisk character. checked out is noted with an asterisk character.
- *``git branch -D`` branch-name:* Deletes an existing local branch. - *git branch -D branch-name:* Deletes an existing local branch.
You need to be in a local branch other than the one you are deleting You need to be in a local branch other than the one you are deleting
in order to delete branch-name. in order to delete branch-name.
- *``git pull --rebase``:* Retrieves information from an upstream Git - *git pull --rebase:* Retrieves information from an upstream Git
repository and places it in your local Git repository. You use this repository and places it in your local Git repository. You use this
command to make sure you are synchronized with the repository from command to make sure you are synchronized with the repository from
which you are basing changes (.e.g. the "master" branch). The which you are basing changes (.e.g. the "master" branch). The
"--rebase" option ensures that any local commits you have in your "--rebase" option ensures that any local commits you have in your
branch are preserved at the top of your local branch. branch are preserved at the top of your local branch.
- *``git push`` repo-name local-branch\ ``:``\ upstream-branch:* Sends - *git push repo-name local-branch:upstream-branch:* Sends
all your committed local changes to the upstream Git repository that all your committed local changes to the upstream Git repository that
your local repository is tracking (e.g. a contribution repository). your local repository is tracking (e.g. a contribution repository).
The maintainer of the project draws from these repositories to merge The maintainer of the project draws from these repositories to merge
changes (commits) into the appropriate branch of project's upstream changes (commits) into the appropriate branch of project's upstream
repository. repository.
- *``git merge``:* Combines or adds changes from one local branch of - *git merge:* Combines or adds changes from one local branch of
your repository with another branch. When you create a local Git your repository with another branch. When you create a local Git
repository, the default branch is named "master". A typical workflow repository, the default branch is named "master". A typical workflow
is to create a temporary branch that is based off "master" that you is to create a temporary branch that is based off "master" that you
@@ -585,12 +589,12 @@ descriptions and strategies on how to use these commands:
done with working in that isolated branch, you can safely delete the done with working in that isolated branch, you can safely delete the
isolated branch. isolated branch.
- *``git cherry-pick`` commits:* Choose and apply specific commits from - *git cherry-pick commits:* Choose and apply specific commits from
one branch into another branch. There are times when you might not be one branch into another branch. There are times when you might not be
able to merge all the changes in one branch with another but need to able to merge all the changes in one branch with another but need to
pick out certain ones. pick out certain ones.
- *``gitk``:* Provides a GUI view of the branches and changes in your - *gitk:* Provides a GUI view of the branches and changes in your
local Git repository. This command is a good way to graphically see local Git repository. This command is a good way to graphically see
where things have diverged in your local repository. where things have diverged in your local repository.
@@ -600,11 +604,11 @@ descriptions and strategies on how to use these commands:
gitk gitk
package on your development system to use this command. package on your development system to use this command.
- *``git log``:* Reports a history of your commits to the repository. - *git log:* Reports a history of your commits to the repository.
This report lists all commits regardless of whether you have pushed This report lists all commits regardless of whether you have pushed
them upstream or not. them upstream or not.
- *``git diff``:* Displays line-by-line differences between a local - *git diff:* Displays line-by-line differences between a local
working file and the same file as understood by Git. This command is working file and the same file as understood by Git. This command is
useful to see what you have changed in any given file. useful to see what you have changed in any given file.
@@ -663,7 +667,6 @@ Project uses in the ``meta/files/common-licenses`` directory in your
For information that can help you maintain compliance with various open For information that can help you maintain compliance with various open
source licensing during the lifecycle of a product created using the source licensing during the lifecycle of a product created using the
Yocto Project, see the "`Maintaining Open Source License Compliance Yocto Project, see the
During Your Product's ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
documentation/overview-manual/overview-manual-intro.rst
+11 -13
View File
@@ -20,7 +20,7 @@ The following list describes what you can get from this manual:
provides an introduction to the Yocto Project. You will learn about provides an introduction to the Yocto Project. You will learn about
features and challenges of the Yocto Project, the layer model, features and challenges of the Yocto Project, the layer model,
components and tools, development methods, the components and tools, development methods, the
`Poky <&YOCTO_DOCS_REF_URL;#poky>`__ reference distribution, the :term:`Poky` reference distribution, the
OpenEmbedded build system workflow, and some basic Yocto terms. OpenEmbedded build system workflow, and some basic Yocto terms.
- `The Yocto Project Development - `The Yocto Project Development
@@ -30,7 +30,7 @@ The following list describes what you can get from this manual:
Yocto Project source repositories, workflows using Git and the Yocto Yocto Project source repositories, workflows using Git and the Yocto
Project, a Git primer, and information about licensing. Project, a Git primer, and information about licensing.
- `Yocto Project Concepts <#overview-manual-concepts>`__\ *:* This - :doc:`overview-manual-concepts` *:* This
chapter presents various concepts regarding the Yocto Project. You chapter presents various concepts regarding the Yocto Project. You
can find conceptual information about components, development, can find conceptual information about components, development,
cross-toolchains, and so forth. cross-toolchains, and so forth.
@@ -39,19 +39,17 @@ This manual does not give you the following:
- *Step-by-step Instructions for Development Tasks:* Instructional - *Step-by-step Instructions for Development Tasks:* Instructional
procedures reside in other manuals within the Yocto Project procedures reside in other manuals within the Yocto Project
documentation set. For example, the `Yocto Project Development Tasks documentation set. For example, the :doc:`../dev-manual/dev-manual`
Manual <&YOCTO_DOCS_DEV_URL;>`__ provides examples on how to perform provides examples on how to perform
various development tasks. As another example, the `Yocto Project various development tasks. As another example, the
Application Development and the Extensible Software Development Kit :doc:`../sdk-manual/sdk-manual` manual contains detailed
(eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual contains detailed
instructions on how to install an SDK, which is used to develop instructions on how to install an SDK, which is used to develop
applications for target hardware. applications for target hardware.
- *Reference Material:* This type of material resides in an appropriate - *Reference Material:* This type of material resides in an appropriate
reference manual. For example, system variables are documented in the reference manual. For example, system variables are documented in the
`Yocto Project Reference Manual <&YOCTO_DOCS_REF_URL;>`__. As another :doc:`../ref-manual/ref-manual`. As another
example, the `Yocto Project Board Support Package (BSP) Developer's example, the :doc:`../bsp-guide/bsp-guide` contains reference information on
Guide <&YOCTO_DOCS_BSP_URL;>`__ contains reference information on
BSPs. BSPs.
- *Detailed Public Information Not Specific to the Yocto Project:* For - *Detailed Public Information Not Specific to the Yocto Project:* For
@@ -69,8 +67,8 @@ supplemental information is recommended for full comprehension. For
additional introductory information on the Yocto Project, see the additional introductory information on the Yocto Project, see the
:yocto_home:`Yocto Project Website <>`. If you want to build an image :yocto_home:`Yocto Project Website <>`. If you want to build an image
with no knowledge of Yocto Project as a way of quickly testing it out, with no knowledge of Yocto Project as a way of quickly testing it out,
see the `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. see the :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document.
For a comprehensive list of links and other documentation, see the For a comprehensive list of links and other documentation, see the
"`Links and Related ":ref:`Links and Related
Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__" Documentation <resources-links-and-related-documentation>`"
section in the Yocto Project Reference Manual. section in the Yocto Project Reference Manual.
documentation/overview-manual/overview-manual-yp-intro.rst
+35 -47
View File
@@ -113,7 +113,7 @@ Project:
development. development.
- *Releases According to a Strict Schedule:* Major releases occur on a - *Releases According to a Strict Schedule:* Major releases occur on a
`six-month cycle <&YOCTO_DOCS_REF_URL;#ref-release-process>`__ :doc:`six-month cycle <../ref-manual/ref-release-process>`
predictably in October and April. The most recent two releases predictably in October and April. The most recent two releases
support point releases to address common vulnerabilities and support point releases to address common vulnerabilities and
exposures. This predictability is crucial for projects based on the exposures. This predictability is crucial for projects based on the
@@ -131,8 +131,8 @@ Project:
in what order to support dependencies, other build systems can in what order to support dependencies, other build systems can
arbitrarily include packages. arbitrarily include packages.
- *License Manifest:* The Yocto Project provides a `license - *License Manifest:* The Yocto Project provides a :ref:`license
manifest <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__ manifest <dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle>`
for review by people who need to track the use of open source for review by people who need to track the use of open source
licenses (e.g.legal teams). licenses (e.g.legal teams).
@@ -154,10 +154,8 @@ developing using the Yocto Project:
changes need to be made for your particular design can require a changes need to be made for your particular design can require a
significant amount of research and investigation. For information significant amount of research and investigation. For information
that helps you transition from trying out the Yocto Project to using that helps you transition from trying out the Yocto Project to using
it for your project, see the "`What I wish I'd it for your project, see the ":ref:`what-i-wish-id-known:what i wish i'd known about yocto project`" and
Known <&YOCTO_DOCS_URL;/what-i-wish-id-known/>`__" and ":ref:`transitioning-to-a-custom-environment:transitioning to a custom environment for systems development`"
"`Transitioning to a Custom Environment for Systems
Development <&YOCTO_DOCS_URL;/transitioning-to-a-custom-environment/>`__"
documents on the Yocto Project website. documents on the Yocto Project website.
- *Project Workflow Could Be Confusing:* The `Yocto Project - *Project Workflow Could Be Confusing:* The `Yocto Project
@@ -233,8 +231,8 @@ your Metadata, the easier it is to cope with future changes.
validated. validated.
- Layers support the inclusion of technologies, hardware components, - Layers support the inclusion of technologies, hardware components,
and software components. The `Yocto Project and software components. The :ref:`Yocto Project
Compatible <&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project>`__ Compatible <dev-manual/dev-manual-common-tasks:making sure your layer is compatible with yocto project>`
designation provides a minimum level of standardization that designation provides a minimum level of standardization that
contributes to a strong ecosystem. "YP Compatible" is applied to contributes to a strong ecosystem. "YP Compatible" is applied to
appropriate products and software components such as BSPs, other appropriate products and software components such as BSPs, other
@@ -280,9 +278,8 @@ view <https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/>`__ of the
``meta-yocto-bsp``. Each of these repositories represents a distinct ``meta-yocto-bsp``. Each of these repositories represents a distinct
layer. layer.
For procedures on how to create layers, see the "`Understanding and For procedures on how to create layers, see the
Creating ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
Components and Tools Components and Tools
@@ -292,7 +289,7 @@ The Yocto Project employs a collection of components and tools used by
the project itself, by project developers, and by those using the Yocto the project itself, by project developers, and by those using the Yocto
Project. These components and tools are open source projects and Project. These components and tools are open source projects and
metadata that are separate from the reference distribution metadata that are separate from the reference distribution
(`Poky <&YOCTO_DOCS_REF_URL;#poky>`__) and the (:term:`Poky`) and the
:term:`OpenEmbedded Build System`. Most of the :term:`OpenEmbedded Build System`. Most of the
components and tools are downloaded separately. components and tools are downloaded separately.
@@ -336,8 +333,8 @@ applications using the Yocto Project:
You can read about the ``devtool`` workflow in the Yocto Project You can read about the ``devtool`` workflow in the Yocto Project
Application Development and Extensible Software Development Kit Application Development and Extensible Software Development Kit
(eSDK) Manual in the "`Using ``devtool`` in Your SDK (eSDK) Manual in the
Workflow' <&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow>`__" ":ref:`sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow`"
section. section.
- *Extensible Software Development Kit (eSDK):* The eSDK provides a - *Extensible Software Development Kit (eSDK):* The eSDK provides a
@@ -349,14 +346,12 @@ applications using the Yocto Project:
experience supplemented with the powerful set of ``devtool`` commands experience supplemented with the powerful set of ``devtool`` commands
tailored for the Yocto Project environment. tailored for the Yocto Project environment.
For information on the eSDK, see the `Yocto Project Application For information on the eSDK, see the :doc:`../sdk-manual/sdk-manual` Manual.
Development and the Extensible Software Development Kit
(eSDK) <&YOCTO_DOCS_SDK_URL;>`__ Manual.
- *Toaster:* Toaster is a web interface to the Yocto Project - *Toaster:* Toaster is a web interface to the Yocto Project
OpenEmbedded build system. Toaster allows you to configure, run, and OpenEmbedded build system. Toaster allows you to configure, run, and
view information about builds. For information on Toaster, see the view information about builds. For information on Toaster, see the
`Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__. :doc:`../toaster-manual/toaster-manual`.
.. _gs-production-tools: .. _gs-production-tools:
@@ -406,7 +401,7 @@ activities using the Yocto Project:
benefit of the development community. benefit of the development community.
You can learn more about the AutoBuilder used by the Yocto Project You can learn more about the AutoBuilder used by the Yocto Project
`here <&YOCTO_AB_URL;>`__. Autobuilder :doc:`here <../test-manual/test-manual-understand-autobuilder>`.
- *Cross-Prelink:* Prelinking is the process of pre-computing the load - *Cross-Prelink:* Prelinking is the process of pre-computing the load
addresses and link tables generated by the dynamic linker as compared addresses and link tables generated by the dynamic linker as compared
@@ -595,8 +590,8 @@ Linux.
Development Methods Development Methods
=================== ===================
The Yocto Project development environment usually involves a `Build The Yocto Project development environment usually involves a
Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ and target :term:`Build Host` and target
hardware. You use the Build Host to build images and develop hardware. You use the Build Host to build images and develop
applications, while you use the target hardware to test deployed applications, while you use the target hardware to test deployed
software. software.
@@ -622,8 +617,8 @@ Project.
supported Linux distribution. supported Linux distribution.
For information on how to set up a Build Host on a system running For information on how to set up a Build Host on a system running
Linux as its native operating system, see the "`Setting Up a Native Linux as its native operating system, see the
Linux Host <&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host>`__" ":ref:`dev-manual/dev-manual-start:setting up a native linux host`"
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
- *CROss PlatformS (CROPS):* Typically, you use - *CROss PlatformS (CROPS):* Typically, you use
@@ -643,9 +638,8 @@ Project.
system natively running Linux. system natively running Linux.
For information on how to set up a Build Host with CROPS, see the For information on how to set up a Build Host with CROPS, see the
"`Setting Up to Use CROss PlatformS ":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`"
(CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section in section in the Yocto Project Development Tasks Manual.
the Yocto Project Development Tasks Manual.
- *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem - *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem
For Linux v2 to set up a build host using Windows 10. For Linux v2 to set up a build host using Windows 10.
@@ -661,9 +655,8 @@ Project.
virtualization technology. virtualization technology.
For information on how to set up a Build Host with WSLv2, see the For information on how to set up a Build Host with WSLv2, see the
"`Setting Up to Use Windows Subsystem For ":ref:dev-manual/dev-manual-start:setting up to use windows subsystem for linux (wslv2)`"
Linux <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl>`__" section in the section in the Yocto Project Development Tasks Manual.
Yocto Project Development Tasks Manual.
- *Toaster:* Regardless of what your Build Host is running, you can use - *Toaster:* Regardless of what your Build Host is running, you can use
Toaster to develop software using the Yocto Project. Toaster is a web Toaster to develop software using the Yocto Project. Toaster is a web
@@ -673,8 +666,8 @@ Project.
builds is collected and stored in a database. You can use Toaster to builds is collected and stored in a database. You can use Toaster to
configure and start builds on multiple remote build servers. configure and start builds on multiple remote build servers.
For information about and how to use Toaster, see the `Toaster User For information about and how to use Toaster, see the
Manual <&YOCTO_DOCS_TOAST_URL;>`__. :doc:`../toaster-manual/toaster-manual`.
.. _reference-embedded-distribution: .. _reference-embedded-distribution:
@@ -686,7 +679,7 @@ Project's reference distribution or Reference OS Kit. Poky contains the
:term:`OpenEmbedded Build System` :term:`OpenEmbedded Build System`
(:term:`BitBake` and (:term:`BitBake` and
:term:`OpenEmbedded-Core (OE-Core)`) as well as a set :term:`OpenEmbedded-Core (OE-Core)`) as well as a set
of `metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ to get you started of :term:`Metadata` to get you started
building your own distro. In other words, Poky is a base specification building your own distro. In other words, Poky is a base specification
of the functionality needed for a typical embedded system as well as the of the functionality needed for a typical embedded system as well as the
components from the Yocto Project that allow you to build a distribution components from the Yocto Project that allow you to build a distribution
@@ -747,8 +740,7 @@ Poky has a regular, well established, six-month release cycle under its
own version. Major releases occur at the same time major releases (point own version. Major releases occur at the same time major releases (point
releases) occur for the Yocto Project, which are typically in the Spring releases) occur for the Yocto Project, which are typically in the Spring
and Fall. For more information on the Yocto Project release schedule and and Fall. For more information on the Yocto Project release schedule and
cadence, see the "`Yocto Project Releases and the Stable Release cadence, see the ":doc:`../ref-manual/ref-release-process`" chapter in the
Process <&YOCTO_DOCS_REF_URL;#ref-release-process>`__" chapter in the
Yocto Project Reference Manual. Yocto Project Reference Manual.
Much has been said about Poky being a "default configuration." A default Much has been said about Poky being a "default configuration." A default
@@ -827,8 +819,8 @@ Some Basic Terms
================ ================
It helps to understand some basic fundamental terms when learning the It helps to understand some basic fundamental terms when learning the
Yocto Project. Although a list of terms exists in the "`Yocto Project Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project
Terms <&YOCTO_DOCS_REF_URL;#ref-terms>`__" section of the Yocto Project Terms <../ref-manual/ref-terms>`" section of the Yocto Project
Reference Manual, this section provides the definitions of some terms Reference Manual, this section provides the definitions of some terms
helpful for getting started: helpful for getting started:
@@ -842,9 +834,7 @@ helpful for getting started:
application developers. This eSDK allows developers to incorporate application developers. This eSDK allows developers to incorporate
their library and programming changes back into the image to make their library and programming changes back into the image to make
their code available to other application developers. For information their code available to other application developers. For information
on the eSDK, see the `Yocto Project Application Development and the on the eSDK, see the :doc:`../sdk-manual/sdk-manual` manual.
Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__
manual.
- *Layer:* A collection of related recipes. Layers allow you to - *Layer:* A collection of related recipes. Layers allow you to
consolidate related metadata to customize your build. Layers also consolidate related metadata to customize your build. Layers also
@@ -855,12 +845,11 @@ helpful for getting started:
them. You can search the Layer Index for layers used within Yocto them. You can search the Layer Index for layers used within Yocto
Project. Project.
For more detailed information on layers, see the "`Understanding and For more detailed information on layers, see the
Creating ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
section in the Yocto Project Development Tasks Manual. For a section in the Yocto Project Development Tasks Manual. For a
discussion specifically on BSP Layers, see the "`BSP discussion specifically on BSP Layers, see the
Layers <&YOCTO_DOCS_BSP_URL;#bsp-layers>`__" section in the Yocto ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto
Project Board Support Packages (BSP) Developer's Guide. Project Board Support Packages (BSP) Developer's Guide.
- *Metadata:* A key element of the Yocto Project is the Metadata that - *Metadata:* A key element of the Yocto Project is the Metadata that
@@ -913,8 +902,7 @@ helpful for getting started:
It is worth noting that the term "package" can, in general, have It is worth noting that the term "package" can, in general, have
subtle meanings. For example, the packages referred to in the subtle meanings. For example, the packages referred to in the
"`Required Packages for the Build ":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
Host <&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host>`__"
section in the Yocto Project Reference Manual are compiled binaries section in the Yocto Project Reference Manual are compiled binaries
that, when installed, add functionality to your Linux distribution. that, when installed, add functionality to your Linux distribution.