MIRRORS/poky
1
0
Fork 0
mirror of git://git.yoctoproject.org/poky.git synced 2025-07-19 12:59:02 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

manuals: code insertion simplification over two lines

Browse Source 
This simplifies paragraphs ending with a colon and followed
by code insertion.

Automatically substituted through the command:
sed -i -z "s/:\n\s*::/::/g" file.rst

This generates identical HTML output.

(From yocto-docs rev: 28e2192a7c12d64b68061138a9f6c796453eebb1)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Michael Opdenacker 2021-04-16 18:27:05 +02:00 committed by Richard Purdie
parent 773536c333
commit c3c6de2187
38 changed files with 974 additions and 1949 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1020
documentation/dev-manual/common-tasks.rst
View File

File diff suppressed because it is too large Load Diff

24
documentation/dev-manual/qemu.rst
View File

@ -55,16 +55,14 @@ available. Follow these general steps to run QEMU:
- If you cloned the ``poky`` repository or you downloaded and
unpacked a Yocto Project release tarball, you can source the build
environment script (i.e. :ref:`structure-core-script`):
::
environment script (i.e. :ref:`structure-core-script`)::
$ cd poky
$ source oe-init-build-env
- If you installed a cross-toolchain, you can run the script that
initializes the toolchain. For example, the following commands run
the initialization script from the default ``poky_sdk`` directory:
::
the initialization script from the default ``poky_sdk`` directory::
. poky_sdk/environment-setup-core2-64-poky-linux
@ -86,8 +84,7 @@ available. Follow these general steps to run QEMU:
Extensible Software Development Kit (eSDK) manual for information on
how to extract a root filesystem.
4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:
::
4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows::
$ runqemu [option ] [...]
@ -222,18 +219,15 @@ using an NFS server.
Should you need to start, stop, or restart the NFS share, you can use
the following commands:
- The following command starts the NFS share:
::
- The following command starts the NFS share::
runqemu-export-rootfs start file-system-location
- The following command stops the NFS share:
::
- The following command stops the NFS share::
runqemu-export-rootfs stop file-system-location
- The following command restarts the NFS share:
::
- The following command restarts the NFS share::
runqemu-export-rootfs restart file-system-location
@ -313,8 +307,7 @@ present, the toolchain is also automatically used.
QEMU Command-Line Syntax
========================
The basic ``runqemu`` command syntax is as follows:
::
The basic ``runqemu`` command syntax is as follows::
$ runqemu [option ] [...]
@ -325,8 +318,7 @@ timestamp when it needs to look for an image. Minimally, through the use
of options, you must provide either a machine name, a virtual machine
image (``*wic.vmdk``), or a kernel image (``*.bin``).
Following is the command-line help output for the ``runqemu`` command:
::
Following is the command-line help output for the ``runqemu`` command::
$ runqemu --help

30
documentation/dev-manual/start.rst
View File

@ -486,8 +486,7 @@ your Yocto Project build host:
distribution.
3. *Check your Linux distribution is using WSLv2:* Open a Windows
PowerShell and run:
::
PowerShell and run::
C:\WINDOWS\system32> wsl -l -v
NAME STATE VERSION
@ -514,8 +513,7 @@ your Yocto Project build host:
1. *Find the location of your VHDX file:* First you need to find the
distro app package directory, to achieve this open a Windows
Powershell as Administrator and run:
::
Powershell as Administrator and run::
C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
PackageFamilyName
@ -525,8 +523,7 @@ your Yocto Project build host:
You should now
replace the PackageFamilyName and your user on the following path
to find your VHDX file:
::
to find your VHDX file::
ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
Mode LastWriteTime Length Name
@ -536,8 +533,7 @@ your Yocto Project build host:
``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx``
2. *Optimize your VHDX file:* Open a Windows Powershell as
Administrator to optimize your VHDX file, shutting down WSL first:
::
Administrator to optimize your VHDX file, shutting down WSL first::
C:\WINDOWS\system32> wsl --shutdown
C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
@ -741,8 +737,7 @@ Follow these steps to create a local version of the upstream
2. *Clone the Repository:* The following example command clones the
``poky`` repository and uses the default name "poky" for your local
repository:
::
repository::
$ git clone git://git.yoctoproject.org/poky
Cloning into 'poky'...
@ -764,8 +759,7 @@ Follow these steps to create a local version of the upstream
Once the local repository is created, you can change to that
directory and check its status. Here, the single "master" branch
exists on your system and by default, it is checked out:
::
exists on your system and by default, it is checked out::
$ cd poky
$ git status
@ -826,8 +820,7 @@ and then specifically check out that development branch.
3. *Check out the Branch:* Check out the development branch in which you
want to work. For example, to access the files for the Yocto Project
&DISTRO; Release (&DISTRO_NAME;), use the following command:
::
&DISTRO; Release (&DISTRO_NAME;), use the following command::
$ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
@ -839,8 +832,7 @@ and then specifically check out that development branch.
The following command displays the branches that are now part of your
local poky repository. The asterisk character indicates the branch
that is currently checked out for work:
::
that is currently checked out for work::
$ git branch
master
@ -867,14 +859,12 @@ similar to checking out by branch name except you use tag names.
section.
2. *Fetch the Tag Names:* To checkout the branch based on a tag name,
you need to fetch the upstream tags into your local repository:
::
you need to fetch the upstream tags into your local repository::
$ git fetch --tags
$
3. *List the Tag Names:* You can list the tag names now:
::
3. *List the Tag Names:* You can list the tag names now::
$ git tag
1.1_M1.final

87
documentation/kernel-dev/advanced.rst
View File

@ -67,8 +67,7 @@ to indicate the branch.
.. note::
You can use the ``KBRANCH`` value to define an alternate branch typically
with a machine override as shown here from the ``meta-yocto-bsp`` layer:
::
with a machine override as shown here from the ``meta-yocto-bsp`` layer::
KBRANCH_edgerouter = "standard/edgerouter"
@ -106,15 +105,13 @@ You can use the
variable to include features (configuration fragments, patches, or both)
that are not already included by the ``KMACHINE`` and
``LINUX_KERNEL_TYPE`` variable combination. For example, to include a
feature specified as "features/netfilter/netfilter.scc", specify:
::
feature specified as "features/netfilter/netfilter.scc", specify::
KERNEL_FEATURES += "features/netfilter/netfilter.scc"
To include a
feature called "cfg/sound.scc" just for the ``qemux86`` machine,
specify:
::
specify::
KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc"
@ -157,8 +154,7 @@ types to form the final description of what will be assembled and built.
While the kernel Metadata syntax does not enforce any logical separation
of configuration fragments, patches, features or kernel types, best
practices dictate a logical separation of these types of Metadata. The
following Metadata file hierarchy is recommended:
::
following Metadata file hierarchy is recommended::
base/
bsp/
@ -222,8 +218,7 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the
recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
``cfg`` directory of the ``yocto-4.12`` branch in the
``yocto-kernel-cache`` Git repository:
::
``yocto-kernel-cache`` Git repository::
cfg/smp.scc:
define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
@ -265,8 +260,7 @@ non-hardware fragment.
As described in the
":ref:`kernel-dev/common:validating configuration`" section, you can
use the following BitBake command to audit your configuration:
::
use the following BitBake command to audit your configuration::
$ bitbake linux-yocto -c kernel_configcheck -f
@ -287,8 +281,7 @@ in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
``yocto-kernel-cache`` Git repository.
The following listings show the ``build.scc`` file and part of the
``modpost-mask-trivial-warnings.patch`` file:
::
``modpost-mask-trivial-warnings.patch`` file::
patches/build/build.scc:
patch arm-serialize-build-targets.patch
@ -334,8 +327,7 @@ Features
Features are complex kernel Metadata types that consist of configuration
fragments, patches, and possibly other feature description files. As an
example, consider the following generic listing:
::
example, consider the following generic listing::
features/myfeature.scc
define KFEATURE_DESCRIPTION "Enable myfeature"
@ -371,15 +363,13 @@ the ``linux-yocto_4.12.bb`` kernel recipe found in
``poky/meta/recipes-kernel/linux``, a
:ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive
includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file,
which has the following statement that defines the default kernel type:
::
which has the following statement that defines the default kernel type::
LINUX_KERNEL_TYPE ??= "standard"
Another example would be the real-time kernel (i.e.
``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
type as follows:
::
type as follows::
LINUX_KERNEL_TYPE = "preempt-rt"
@ -412,8 +402,7 @@ for Linux Yocto kernels:
For any given kernel type, the Metadata is defined by the ``.scc`` (e.g.
``standard.scc``). Here is a partial listing for the ``standard.scc``
file, which is found in the ``ktypes/standard`` directory of the
``yocto-kernel-cache`` Git repository:
::
``yocto-kernel-cache`` Git repository::
# Include this kernel type fragment to get the standard features and
# configuration values.
@ -482,15 +471,13 @@ Description Overview
For simplicity, consider the following root BSP layer description files
for the BeagleBone board. These files employ both a structure and naming
convention for consistency. The naming convention for the file is as
follows:
::
follows::
bsp_root_name-kernel_type.scc
Here are some example root layer
BSP filenames for the BeagleBone Board BSP, which is supported by the
Yocto Project:
::
Yocto Project::
beaglebone-standard.scc
beaglebone-preempt-rt.scc
@ -498,8 +485,7 @@ Yocto Project:
Each file uses the root name (i.e "beaglebone") BSP name followed by the
kernel type.
Examine the ``beaglebone-standard.scc`` file:
::
Examine the ``beaglebone-standard.scc`` file::
define KMACHINE beaglebone
define KTYPE standard
@ -533,8 +519,7 @@ description file match.
To separate your kernel policy from your hardware configuration, you
include a kernel type (``ktype``), such as "standard". In the previous
example, this is done using the following:
::
example, this is done using the following::
include ktypes/standard/standard.scc
@ -544,13 +529,11 @@ policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
information.
To aggregate common configurations and features specific to the kernel
for `mybsp`, use the following:
::
for `mybsp`, use the following::
include mybsp.scc
You can see that in the BeagleBone example with the following:
::
You can see that in the BeagleBone example with the following::
include beaglebone.scc
@ -558,15 +541,13 @@ For information on how to break a complete ``.config`` file into the various
configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section.
Finally, if you have any configurations specific to the hardware that
are not in a ``*.scc`` file, you can include them as follows:
::
are not in a ``*.scc`` file, you can include them as follows::
kconf hardware mybsp-extra.cfg
The BeagleBone example does not include these
types of configurations. However, the Malta 32-bit board does
("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:
::
("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file::
define KMACHINE mti-malta32-le
define KMACHINE qemumipsel
@ -623,8 +604,7 @@ found on the machine. This ``minnow.scc`` description file is then
included in each of the three "minnow" description files for the
supported kernel types (i.e. "standard", "preempt-rt", and "tiny").
Consider the "minnow" description for the "standard" kernel type (i.e.
``minnow-standard.scc``):
::
``minnow-standard.scc``)::
define KMACHINE minnow
define KTYPE standard
@ -656,8 +636,7 @@ that defines all enabled hardware for the BSP that is common to all
kernel types. Using this command significantly reduces duplication.
Now consider the "minnow" description for the "tiny" kernel type (i.e.
``minnow-tiny.scc``):
::
``minnow-tiny.scc``)::
define KMACHINE minnow
define KTYPE tiny
@ -720,8 +699,7 @@ See the ":ref:`kernel-dev/common:modifying an existing recipe`"
section for more information.
Here is an example that shows a trivial tree of kernel Metadata stored
in recipe-space within a BSP layer:
::
in recipe-space within a BSP layer::
meta-my_bsp_layer/
`-- recipes-kernel
@ -744,8 +722,7 @@ value when changing the content of files not explicitly listed in the
If the BSP description is in recipe space, you cannot simply list the
``*.scc`` in the ``SRC_URI`` statement. You need to use the following
form from your kernel append file:
::
form from your kernel append file::
SRC_URI_append_myplatform = " \
file://myplatform;type=kmeta;destsuffix=myplatform \
@ -759,8 +736,7 @@ reside in a separate repository. The OpenEmbedded build system adds the
Metadata to the build as a "type=kmeta" repository through the
:term:`SRC_URI` variable. As an
example, consider the following ``SRC_URI`` statement from the
``linux-yocto_4.12.bb`` kernel recipe:
::
``linux-yocto_4.12.bb`` kernel recipe::
SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \
git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
@ -844,14 +820,12 @@ patches into a feature.
Once you have a new branch, you can set up your kernel Metadata to use
the branch a couple different ways. In the recipe, you can specify the
new branch as the ``KBRANCH`` to use for the board as follows:
::
new branch as the ``KBRANCH`` to use for the board as follows::
KBRANCH = "mynewbranch"
Another method is to use the ``branch`` command in the BSP
description:
::
description::
mybsp.scc:
define KMACHINE mybsp
@ -865,15 +839,13 @@ description:
If you find yourself with numerous branches, you might consider using a
hierarchical branching system similar to what the Yocto Linux Kernel Git
repositories use:
::
repositories use::
common/kernel_type/machine
If you had two kernel types, "standard" and "small" for instance, three
machines, and common as ``mydir``, the branches in your Git repository
might look like this:
::
might look like this::
mydir/base
mydir/standard/base
@ -905,8 +877,7 @@ that have to be regularly updated. The Yocto Project Linux kernel tools
provide for this with the ``git merge`` command.
To merge a feature branch into a BSP, insert the ``git merge`` command
after any ``branch`` commands:
::
after any ``branch`` commands::
mybsp.scc:
define KMACHINE mybsp

225
documentation/kernel-dev/common.rst
View File

@ -54,8 +54,7 @@ section:
1. *Initialize the BitBake Environment:* Before building an extensible
SDK, you need to initialize the BitBake build environment by sourcing
the build environment script (i.e. :ref:`structure-core-script`):
::
the build environment script (i.e. :ref:`structure-core-script`)::
$ cd poky
$ source oe-init-build-env
@ -83,16 +82,14 @@ section:
In this example we wish to build for qemux86 so we must set the
``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
As described we do this by appending to ``conf/local.conf``:
::
As described we do this by appending to ``conf/local.conf``::
MACHINE = "qemux86"
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
3. *Create a Layer for Patches:* You need to create a layer to hold
patches created for the kernel image. You can use the
``bitbake-layers create-layer`` command as follows:
::
``bitbake-layers create-layer`` command as follows::
$ cd poky/build
$ bitbake-layers create-layer ../../meta-mylayer
@ -116,8 +113,7 @@ section:
4. *Inform the BitBake Build Environment About Your Layer:* As directed
when you created your layer, you need to add the layer to the
:term:`BBLAYERS` variable in the
``bblayers.conf`` file as follows:
::
``bblayers.conf`` file as follows::
$ cd poky/build
$ bitbake-layers add-layer ../../meta-mylayer
@ -125,16 +121,14 @@ section:
$
5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK
specifically for use with images to be run using QEMU:
::
specifically for use with images to be run using QEMU::
$ cd poky/build
$ bitbake core-image-minimal -c populate_sdk_ext
Once
the build finishes, you can find the SDK installer file (i.e.
``*.sh`` file) in the following directory:
::
``*.sh`` file) in the following directory::
poky/build/tmp/deploy/sdk
@ -143,8 +137,7 @@ section:
6. *Install the Extensible SDK:* Use the following command to install
the SDK. For this example, install the SDK in the default
``poky_sdk`` directory:
::
``poky_sdk`` directory::
$ cd poky/build/tmp/deploy/sdk
$ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
@ -172,8 +165,7 @@ section:
BitBake shell used to build the installer.
After opening a new shell, run the SDK environment setup script as
directed by the output from installing the SDK:
::
directed by the output from installing the SDK::
$ source poky_sdk/environment-setup-i586-poky-linux
"SDK environment now set up; additionally you may now run devtool to perform development tasks.
@ -186,8 +178,7 @@ section:
8. *Build the Clean Image:* The final step in preparing to work on the
kernel is to build an initial image using ``devtool`` in the new
terminal you just set up and initialized for SDK work:
::
terminal you just set up and initialized for SDK work::
$ devtool build-image
Parsing recipes: 100% |##########################################| Time: 0:00:05
@ -269,16 +260,14 @@ section:
In this example we wish to build for qemux86 so we must set the
``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
As described we do this by appending to ``conf/local.conf``:
::
As described we do this by appending to ``conf/local.conf``::
MACHINE = "qemux86"
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
3. *Create a Layer for Patches:* You need to create a layer to hold
patches created for the kernel image. You can use the
``bitbake-layers create-layer`` command as follows:
::
``bitbake-layers create-layer`` command as follows::
$ cd poky/build
$ bitbake-layers create-layer ../../meta-mylayer
@ -301,8 +290,7 @@ section:
4. *Inform the BitBake Build Environment About Your Layer:* As directed
when you created your layer, you need to add the layer to the
:term:`BBLAYERS` variable in the
``bblayers.conf`` file as follows:
::
``bblayers.conf`` file as follows::
$ cd poky/build
$ bitbake-layers add-layer ../../meta-mylayer
@ -350,8 +338,7 @@ section:
the ``yocto-4.12`` branch.
The following commands show how to create a local copy of the
``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch:
::
``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch::
$ cd ~
$ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
@ -394,8 +381,7 @@ following section describes how to create a layer without the aid of
tools. These steps assume creation of a layer named ``mylayer`` in your
home directory:
1. *Create Structure*: Create the layer's structure:
::
1. *Create Structure*: Create the layer's structure::
$ mkdir meta-mylayer
$ mkdir meta-mylayer/conf
@ -409,8 +395,7 @@ home directory:
2. *Create the Layer Configuration File*: Move to the
``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
follows:
::
follows::
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"
@ -429,8 +414,7 @@ home directory:
``meta-mylayer/recipes-kernel/linux`` directory and create the
kernel's append file. This example uses the ``linux-yocto-4.12``
kernel. Thus, the name of the append file is
``linux-yocto_4.12.bbappend``:
::
``linux-yocto_4.12.bbappend``::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@ -483,8 +467,7 @@ The append file should initially extend the
:term:`FILESPATH` search path by
prepending the directory that contains your files to the
:term:`FILESEXTRAPATHS`
variable as follows:
::
variable as follows::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
@ -492,8 +475,7 @@ The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``
expands to "linux-yocto" in the current directory for this example. If
you add any new files that modify the kernel recipe and you have
extended ``FILESPATH`` as described above, you must place the files in
your layer in the following area:
::
your layer in the following area::
your-layer/recipes-kernel/linux/linux-yocto/
@ -582,8 +564,7 @@ To group related configurations into multiple files, you perform a
similar procedure. Here is an example that groups separate
configurations specifically for Ethernet and graphics into their own
files and adds the configurations by using a ``SRC_URI`` statement like
the following in your append file:
::
the following in your append file::
SRC_URI += "file://myconfig.cfg \
file://eth.cfg \
@ -627,8 +608,7 @@ reference them in :term:`SRC_URI`
statements.
For example, you can apply a three-patch series by adding the following
lines to your linux-yocto ``.bbappend`` file in your layer:
::
lines to your linux-yocto ``.bbappend`` file in your layer::
SRC_URI += "file://0001-first-change.patch"
SRC_URI += "file://0002-second-change.patch"
@ -658,8 +638,7 @@ If you have a complete, working Linux kernel ``.config`` file you want
to use for the configuration, as before, copy that file to the
appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
directory, and rename the copied file to "defconfig". Then, add the
following lines to the linux-yocto ``.bbappend`` file in your layer:
::
following lines to the linux-yocto ``.bbappend`` file in your layer::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://defconfig"
@ -685,8 +664,7 @@ Generally speaking, the preferred approach is to determine the
incremental change you want to make and add that as a configuration
fragment. For example, if you want to add support for a basic serial
console, create a file named ``8250.cfg`` in the ``${PN}`` directory
with the following content (without indentation):
::
with the following content (without indentation)::
CONFIG_SERIAL_8250=y
CONFIG_SERIAL_8250_CONSOLE=y
@ -698,8 +676,7 @@ with the following content (without indentation):
Next, include this
configuration fragment and extend the ``FILESPATH`` variable in your
``.bbappend`` file:
::
``.bbappend`` file::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://8250.cfg"
@ -718,8 +695,7 @@ It might be desirable to have kernel configuration fragment support
through a ``defconfig`` file that is pulled from the kernel source tree
for the configured machine. By default, the OpenEmbedded build system
looks for ``defconfig`` files in the layer used for Metadata, which is
"out-of-tree", and then configures them using the following:
::
"out-of-tree", and then configures them using the following::
SRC_URI += "file://defconfig"
@ -732,16 +708,14 @@ append files, you can direct the OpenEmbedded build system to use a
``defconfig`` file that is "in-tree".
To specify an "in-tree" ``defconfig`` file, use the following statement
form:
::
form::
KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file"
Here is an example
that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2"
and provides the path to the "in-tree" ``defconfig`` file to be used for
a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:
::
a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset::
KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
@ -792,8 +766,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
section for more information.
Use the following ``devtool`` command to check out the code:
::
Use the following ``devtool`` command to check out the code::
$ devtool modify linux-yocto
@ -819,14 +792,12 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
noted where you can find the source files (e.g.
``poky_sdk/workspace/sources/linux-yocto``). Change to where the
kernel source code is before making your edits to the
``calibrate.c`` file:
::
``calibrate.c`` file::
$ cd poky_sdk/workspace/sources/linux-yocto
2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
the following changes:
::
the following changes::
void calibrate_delay(void)
{
@ -846,8 +817,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
.
3. *Build the Updated Kernel Source:* To build the updated kernel
source, use ``devtool``:
::
source, use ``devtool``::
$ devtool build linux-yocto
@ -872,8 +842,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
using QEMU to verify your changes:
1. *Boot the image*: Boot the modified image in the QEMU emulator
using this command:
::
using this command::
$ runqemu qemux86
@ -891,8 +860,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
6. *Stage and commit your changes*: Within your eSDK terminal, change
your working directory to where you modified the ``calibrate.c`` file
and use these Git commands to stage and commit your changes:
::
and use these Git commands to stage and commit your changes::
$ cd poky_sdk/workspace/sources/linux-yocto
$ git status
@ -921,8 +889,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se
image that includes your kernel patches. Execute the following
command from your
:term:`Build Directory` in the terminal
set up to run BitBake:
::
set up to run BitBake::
$ cd poky/build
$ bitbake core-image-minimal
@ -966,14 +933,12 @@ Section.
1. *Change the working directory*: You need to locate the source
files in the local copy of the kernel Git repository. Change to
where the kernel source code is before making your edits to the
``calibrate.c`` file:
::
``calibrate.c`` file::
$ cd ~/linux-yocto-4.12/init
2. *Edit the source file*: Edit the ``calibrate.c`` file to have the
following changes:
::
following changes::
void calibrate_delay(void)
{
@ -993,8 +958,7 @@ Section.
.
2. *Stage and Commit Your Changes:* Use standard Git commands to stage
and commit the changes you just made:
::
and commit the changes you just made::
$ git add calibrate.c
$ git commit -m "calibrate.c - Added some printk statements"
@ -1009,13 +973,11 @@ Section.
updated kernel source files. Add
:term:`SRC_URI` and
:term:`SRCREV` statements similar
to the following to your ``local.conf``:
::
to the following to your ``local.conf``::
$ cd poky/build/conf
Add the following to the ``local.conf``:
::
Add the following to the ``local.conf``::
SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
@ -1031,16 +993,14 @@ Section.
4. *Build the Image:* With the source modified, your changes staged and
committed, and the ``local.conf`` file pointing to the kernel files,
you can now use BitBake to build the image:
::
you can now use BitBake to build the image::
$ cd poky/build
$ bitbake core-image-minimal
5. *Boot the image*: Boot the modified image in the QEMU emulator using
this command. When prompted to login to the QEMU console, use "root"
with no password:
::
with no password::
$ cd poky/build
$ runqemu qemux86
@ -1059,8 +1019,7 @@ Section.
7. *Generate the Patch File:* Once you are sure that your patch works
correctly, you can generate a ``*.patch`` file in the kernel source
repository:
::
repository::
$ cd ~/linux-yocto-4.12/init
$ git format-patch -1
@ -1073,8 +1032,7 @@ Section.
``meta-mylayer``. When the layer was created using the
``yocto-create`` script, no additional hierarchy was created to
support patches. Before moving the patch file, you need to add
additional structure to your layer using the following commands:
::
additional structure to your layer using the following commands::
$ cd ~/meta-mylayer
$ mkdir recipes-kernel
@ -1083,8 +1041,7 @@ Section.
Once you have created this
hierarchy in your layer, you can move the patch file using the
following command:
::
following command::
$ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto
@ -1093,8 +1050,7 @@ Section.
the OpenEmbedded build system to find the patch. The append file
needs to be in your layer's ``recipes-kernel/linux`` directory and it
must be named ``linux-yocto_4.12.bbappend`` and have the following
contents:
::
contents::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch"
@ -1113,8 +1069,7 @@ Section.
To build ``core-image-minimal`` again and see the effects of your patch,
you can essentially eliminate the temporary source files saved in
``poky/build/tmp/work/...`` and residual effects of the build by entering
the following sequence of commands:
::
the following sequence of commands::
$ cd poky/build
$ bitbake -c cleanall yocto-linux
@ -1160,8 +1115,7 @@ environment, you must do the following:
- You must be sure of the state of your build's configuration in the
:term:`Source Directory`.
- Your build host must have the following two packages installed:
::
- Your build host must have the following two packages installed::
libncurses5-dev
libtinfo-dev
@ -1169,8 +1123,7 @@ environment, you must do the following:
The following commands initialize the BitBake environment, run the
:ref:`ref-tasks-kernel_configme`
task, and launch ``menuconfig``. These commands assume the Source
Directory's top-level folder is ``poky``:
::
Directory's top-level folder is ``poky``::
$ cd poky
$ source oe-init-build-env
@ -1232,8 +1185,7 @@ the ``.config`` file would be:
Within the ``.config`` file, you can see the kernel settings. For
example, the following entry shows that symmetric multi-processor
support is not set:
::
support is not set::
# CONFIG_SMP is not set
@ -1274,8 +1226,7 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied
file to "defconfig" (e.g.
``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
add the following lines to the linux-yocto ``.bbappend`` file in your
layer:
::
layer::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://defconfig"
@ -1323,8 +1274,7 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`.
It is simple to create a configuration fragment. One method is to use
shell commands. For example, issuing the following from the shell
creates a configuration fragment file named ``my_smp.cfg`` that enables
multi-processor support within the kernel:
::
multi-processor support within the kernel::
$ echo "CONFIG_SMP=y" >> my_smp.cfg
@ -1342,8 +1292,7 @@ To create a configuration fragment using this method, follow these
steps:
1. *Complete a Build Through Kernel Configuration:* Complete a build at
least through the kernel configuration task as follows:
::
least through the kernel configuration task as follows::
$ bitbake linux-yocto -c kernel_configme -f
@ -1352,8 +1301,7 @@ steps:
your build state might become unknown, it is best to run this task
prior to starting ``menuconfig``.
2. *Launch menuconfig:* Run the ``menuconfig`` command:
::
2. *Launch menuconfig:* Run the ``menuconfig`` command::
$ bitbake linux-yocto -c menuconfig
@ -1361,8 +1309,7 @@ steps:
to prepare a configuration fragment. The resulting file
``fragment.cfg`` is placed in the
``${``\ :term:`WORKDIR`\ ``}``
directory:
::
directory::
$ bitbake linux-yocto -c diffconfig
@ -1387,8 +1334,7 @@ options in a file called ``myconfig.cfg``. If you put that file inside a
directory named ``linux-yocto`` that resides in the same directory as
the kernel's append file within your layer and then add the following
statements to the kernel's append file, those configuration options will
be picked up and applied when the kernel is built:
::
be picked up and applied when the kernel is built::
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://myconfig.cfg"
@ -1397,8 +1343,7 @@ As mentioned earlier, you can group related configurations into multiple
files and name them all in the ``SRC_URI`` statement as well. For
example, you could group separate configurations specifically for
Ethernet and graphics into their own files and add those by using a
``SRC_URI`` statement like the following in your append file:
::
``SRC_URI`` statement like the following in your append file::
SRC_URI += "file://myconfig.cfg \
file://eth.cfg \
@ -1409,8 +1354,7 @@ Validating Configuration
You can use the
:ref:`ref-tasks-kernel_configcheck`
task to provide configuration validation:
::
task to provide configuration validation::
$ bitbake linux-yocto -c kernel_configcheck -f
@ -1537,8 +1481,7 @@ To streamline the configuration, do the following:
successfully. Use this configuration file as your baseline.
2. *Run Configure and Check Tasks:* Separately run the
``do_kernel_configme`` and ``do_kernel_configcheck`` tasks:
::
``do_kernel_configme`` and ``do_kernel_configcheck`` tasks::
$ bitbake linux-yocto -c kernel_configme -f
$ bitbake linux-yocto -c kernel_configcheck -f
@ -1572,8 +1515,7 @@ Expanding Variables
Sometimes it is helpful to determine what a variable expands to during a
build. You can examine the values of variables by examining the
output of the ``bitbake -e`` command. The output is long and is more
easily managed in a text file, which allows for easy searches:
::
easily managed in a text file, which allows for easy searches::
$ bitbake -e virtual/kernel > some_text_file
@ -1590,15 +1532,13 @@ source directory. Follow these steps to clean up the version string:
1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
Git repository (source directory) and use the following Git command
to list the files that have been changed, added, or removed:
::
to list the files that have been changed, added, or removed::
$ git status
2. *Commit the Changes:* You should commit those changes to the kernel
source tree regardless of whether or not you will save, export, or
use the changes:
::
use the changes::
$ git add
$ git commit -s -a -m "getting rid of -dirty"
@ -1633,8 +1573,7 @@ linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses
``kernel.org`` sources and the Yocto Project Linux kernel tools for
managing kernel Metadata. You can find this recipe in the ``poky`` Git
repository of the Yocto Project :yocto_git:`Source Repository <>`
at:
::
at::
poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
@ -1655,8 +1594,7 @@ Here are some basic steps you can use to work with your own sources:
``defconfig`` file or configuration fragment files in your layer.
When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
configuration. If you do not have a ``defconfig`` file, you can run
the following:
::
the following::
$ make defconfig
@ -1708,8 +1646,7 @@ Here are some basic steps you can use to work with your own sources:
``LINUX_VERSION`` with the Source Control Manager (SCM) revision
as derived from the :term:`SRCPV`
variable. The combined results are a string with the following
form:
::
form::
3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
@ -1723,8 +1660,7 @@ Here are some basic steps you can use to work with your own sources:
triggers an explicit build failure. You must change it to match a
list of the machines that your new recipe supports. For example,
to support the ``qemux86`` and ``qemux86-64`` machines, use the
following form:
::
following form::
COMPATIBLE_MACHINE = "qemux86|qemux86-64"
@ -1807,8 +1743,7 @@ Typically, you will need to set the following variables:
Depending on the build system used by the module sources, you might need
to make some adjustments. For example, a typical module ``Makefile``
looks much like the one provided with the ``hello-mod`` template:
::
looks much like the one provided with the ``hello-mod`` template::
obj-m := hello.o
@ -1845,8 +1780,7 @@ them appropriately for your machine configuration file:
- :term:`MACHINE_EXTRA_RRECOMMENDS`
Modules are often not required for boot and can be excluded from certain
build configurations. The following allows for the most flexibility:
::
build configurations. The following allows for the most flexibility::
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
@ -1895,26 +1829,22 @@ branch.
$ git whatchanged origin/standard/base..origin/standard/emenlow
To see short, one line summaries of changes use the ``git log`` command:
::
To see short, one line summaries of changes use the ``git log`` command::
$ git log --oneline origin/standard/base..origin/standard/emenlow
Use this command to see code differences for the changes:
::
Use this command to see code differences for the changes::
$ git diff origin/standard/base..origin/standard/emenlow
Use this command to see the commit log messages and the text
differences:
::
differences::
$ git show origin/standard/base..origin/standard/emenlow
Use this command to create individual patches for each change. Here is
an example that creates patch files for each commit and places them
in your ``Documents`` directory:
::
in your ``Documents`` directory::
$ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
@ -1923,15 +1853,13 @@ Showing a Particular Feature or Branch Change
Tags in the Yocto Project kernel tree divide changes for significant
features or branches. The ``git show`` tag command shows changes based
on a tag. Here is an example that shows ``systemtap`` changes:
::
on a tag. Here is an example that shows ``systemtap`` changes::
$ git show systemtap
You can use the ``git branch --contains`` tag command to
show the branches that contain a particular feature. This command shows
the branches that contain the ``systemtap`` feature:
::
the branches that contain the ``systemtap`` feature::
$ git branch --contains systemtap
@ -1986,8 +1914,7 @@ build.
searched during the build as potential feature directories.
Continuing with the example, suppose the "test.scc" feature you are
adding has a ``test.scc`` file in the following directory:
::
adding has a ``test.scc`` file in the following directory::
my_recipe
|
@ -2001,8 +1928,7 @@ build.
a similarly named configuration fragment file ``test.cfg``.
2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
recipe's ``SRC_URI`` statement:
::
recipe's ``SRC_URI`` statement::
SRC_URI_append = " file://test.scc"
@ -2011,8 +1937,7 @@ build.
3. *Specify the Feature as a Kernel Feature:* Use the
``KERNEL_FEATURES`` statement to specify the feature as a kernel
feature:
::
feature::
KERNEL_FEATURES_append = " test.scc"

6
documentation/kernel-dev/concepts-appx.rst
View File

@ -359,8 +359,7 @@ To determine whether or not a given option is "hardware" or
"non-hardware", the kernel Metadata in ``yocto-kernel-cache`` contains
files that classify individual or groups of options as either hardware
or non-hardware. To better show this, consider a situation where the
``yocto-kernel-cache`` contains the following files:
::
``yocto-kernel-cache`` contains the following files::
yocto-kernel-cache/features/drm-psb/hardware.cfg
yocto-kernel-cache/features/kgdb/hardware.cfg
@ -400,8 +399,7 @@ provides explanations for the various files:
(i.e. ``hardware.kcf`` or ``non-hardware.kcf``).
Here is a specific example using the
``kernel-cache/bsp/mti-malta32/hardware.cfg``:
::
``kernel-cache/bsp/mti-malta32/hardware.cfg``::
CONFIG_SERIAL_8250
CONFIG_SERIAL_8250_CONSOLE

6
documentation/kernel-dev/faq.rst
View File

@ -57,8 +57,7 @@ These other variables are useful for installing specific modules:
For example, set the following in the ``qemux86.conf`` file to include
the ``ab123`` kernel modules with images built for the ``qemux86``
machine:
::
machine::
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
@ -71,8 +70,7 @@ How do I change the Linux kernel command line?
The Linux kernel command line is
typically specified in the machine config using the ``APPEND`` variable.
For example, you can add some helpful debug information doing the
following:
::
following::
APPEND += "printk.time=y initcall_debug debug"

15
documentation/kernel-dev/maint-appx.rst
View File

@ -28,8 +28,7 @@ in the Yocto Project Linux kernel in any clone of the Yocto Project
Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For
example, the following commands clone the Yocto Project baseline Linux
kernel that branches off ``linux.org`` version 4.12 and the
``yocto-kernel-cache``, which contains stores of kernel Metadata:
::
``yocto-kernel-cache``, which contains stores of kernel Metadata::
$ git clone git://git.yoctoproject.org/linux-yocto-4.12
$ git clone git://git.yoctoproject.org/linux-kernel-cache
@ -42,16 +41,14 @@ section.
Once you have cloned the kernel Git repository and the cache of Metadata
on your local machine, you can discover the branches that are available
in the repository using the following Git command:
::
in the repository using the following Git command::
$ git branch -a
Checking out a branch allows you to work with a particular Yocto Linux
kernel. For example, the following commands check out the
"standard/beagleboard" branch of the Yocto Linux kernel repository and
the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:
::
the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository::
$ cd ~/linux-yocto-4.12
$ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
@ -111,8 +108,7 @@ patch, or BSP:
For a typical build, the target of the search is a feature
description in an ``.scc`` file whose name follows this format (e.g.
``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):
::
``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``)::
bsp_root_name-kernel_type.scc
@ -222,8 +218,7 @@ build process generates a build tree that is separate from your kernel's
local Git source repository tree. This build tree has a name that uses
the following form, where ``${MACHINE}`` is the metadata name of the
machine (BSP) and "kernel_type" is one of the Yocto Project supported
kernel types (e.g. "standard"):
::
kernel types (e.g. "standard")::
linux-${MACHINE}-kernel_type-build

51
documentation/overview-manual/concepts.rst
View File

@ -55,8 +55,7 @@ This section briefly introduces BitBake. If you want more information on
BitBake, see the :doc:`BitBake User Manual <bitbake:index>`.
To see a list of the options BitBake supports, use either of the
following commands:
::
following commands::
$ bitbake -h
$ bitbake --help
@ -66,8 +65,7 @@ The most common usage for BitBake is ``bitbake recipename``, where
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``).
So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might
type the following:
::
type the following::
$ bitbake matchbox-desktop
@ -1068,15 +1066,13 @@ the image. The formats used for the root filesystem depend on the
support compression.
As an example, a dynamically created task when creating a particular
image type would take the following form:
::
image type would take the following form::
do_image_type
So, if the type
as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically
generated task would be as follows:
::
generated task would be as follows::
do_image_ext4
@ -1478,8 +1474,7 @@ cross-compiler that is used internally within BitBake only.
gcc-cross
.
The chain of events that occurs when the standard toolchain is bootstrapped:
::
The chain of events that occurs when the standard toolchain is bootstrapped::
binutils-cross -> linux-libc-headers -> gcc-cross -> libgcc-initial -> glibc -> libgcc -> gcc-runtime
@ -1528,8 +1523,7 @@ might not be the same machine as the Build Host.
can take advantage of pre-built images that ship with the Yocto
Project and already contain cross-development toolchain installers.
Here is the bootstrap process for the relocatable toolchain:
::
Here is the bootstrap process for the relocatable toolchain::
gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
@ -1703,8 +1697,7 @@ to the task.
Like the ``WORKDIR`` case, situations exist where dependencies should be
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"
@ -1714,8 +1707,7 @@ reference it.
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
following:
::
following::
PACKAGE_ARCHS[vardeps] = "MACHINE"
@ -1745,8 +1737,7 @@ and the dependent task hashes can be influenced. Within the BitBake
configuration file, you can give BitBake some extra information to help
it construct the basehash. The following statement effectively results
in a list of global variable dependency excludes (i.e. variables never
included in any checksum):
::
included in any checksum)::
BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\
SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\
@ -1771,8 +1762,7 @@ desired. This file defines the two basic signature generators
"OEBasicHash". By default, a dummy "noop" signature handler is enabled
in BitBake. This means that behavior is unchanged from previous
versions. OE-Core uses the "OEBasicHash" signature handler by default
through this setting in the ``bitbake.conf`` file:
::
through this setting in the ``bitbake.conf`` file::
BB_SIGNATURE_HANDLER ?= "OEBasicHash"
@ -1826,8 +1816,7 @@ The Yocto Project team has tried to keep the details of the
implementation hidden in ``sstate`` class. From a user's perspective,
adding shared state wrapping to a task is as simple as this
: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"
@ -1871,8 +1860,7 @@ The following list explains the previous example:
instead, skipping the ``do_deploy`` task.
- The following task definition is glue logic needed to make the
previous settings effective:
::
previous settings effective::
python do_deploy_setscene () {
sstate_setscene(d)
@ -1898,8 +1886,7 @@ The following list explains the previous example:
In cases where ``sstate-inputdirs`` and ``sstate-outputdirs`` would be
the same, you can use ``sstate-plaindirs``. For example, to preserve the
${:term:`PKGD`} and ${:term:`PKGDEST`} output from the ``do_package``
task, use the following:
::
task, use the following::
do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
@ -1917,24 +1904,21 @@ The following list explains the previous example:
multiple directories. For example, the following declares
``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories,
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}"
- These methods also include the ability to take a lockfile when
manipulating shared state directory structures, for cases where file
additions or removals are sensitive:
::
additions or removals are sensitive::
do_package[sstate-lockfile] = "${PACKAGELOCK}"
Behind the scenes, the shared state code works by looking in
:term:`SSTATE_DIR` and
:term:`SSTATE_MIRRORS` for
shared state files. Here is an example:
::
shared state files. Here is an example::
SSTATE_MIRRORS ?= "\
file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
@ -2116,8 +2100,7 @@ accomplished using fakeroot.
under fakeroot. Otherwise, the task cannot run root-only operations,
and cannot see the fake file ownership and permissions set by the
other task. You need to also add a dependency on
``virtual/fakeroot-native:do_populate_sysroot``, giving the following:
::
``virtual/fakeroot-native:do_populate_sysroot``, giving the following::
fakeroot do_mytask () {
...

6
documentation/overview-manual/development-environment.rst
View File

@ -430,8 +430,7 @@ local working area (also called a branch) that tracks a specific
development branch from the upstream source Git repository. in other
words, you can define your local Git environment to work on any
development branch in the repository. To help illustrate, consider the
following example Git commands:
::
following example Git commands::
$ cd ~
$ git clone git://git.yoctoproject.org/poky
@ -476,8 +475,7 @@ 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
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
specific Yocto Project release. Here is an example:
::
specific Yocto Project release. Here is an example::
$ cd ~
$ git clone git://git.yoctoproject.org/poky

87
documentation/ref-manual/classes.rst
View File

@ -168,8 +168,7 @@ example use for this class.
the "subpath" parameter limits the checkout to a specific subpath
of the tree. Here is an example where ``${BP}`` is used so that the files
are extracted into the subdirectory expected by the default value of
``S``:
::
``S``::
SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
@ -221,8 +220,7 @@ each recipe you wish to blacklist. Specify the :term:`PN`
value as a variable flag (varflag) and provide a reason, which is
reported, if the package is requested to be built as the value. For
example, if you want to blacklist a recipe called "exoticware", you add
the following to your ``local.conf`` or distribution configuration:
::
the following to your ``local.conf`` or distribution configuration::
INHERIT += "blacklist"
PNBLACKLIST[exoticware] = "Not supported by our organization."
@ -470,8 +468,7 @@ information about using ``devshell``.
The ``devupstream`` class uses
:term:`BBCLASSEXTEND` to add a variant of the
recipe that fetches from an alternative URI (e.g. Git) instead of a
tarball. Following is an example:
::
tarball. Following is an example::
BBCLASSEXTEND = "devupstream:target"
SRC_URI_class-devupstream = "git://git.example.com/example"
@ -481,8 +478,7 @@ Adding the above statements to your recipe creates a variant that has
:term:`DEFAULT_PREFERENCE` set to "-1".
Consequently, you need to select the variant of the recipe to use it.
Any development-specific adjustments can be done by using the
``class-devupstream`` override. Here is an example:
::
``class-devupstream`` override. Here is an example::
DEPENDS_append_class-devupstream = " gperf-native"
do_configure_prepend_class-devupstream() {
@ -544,8 +540,7 @@ By default, this class expects the source code to support recipe builds
that use the :term:`B` variable to point to the directory in
which the OpenEmbedded build system places the generated objects built
from the recipes. By default, the ``B`` directory is set to the
following, which is separate from the source directory (``S``):
::
following, which is separate from the source directory (``S``)::
${WORKDIR}/${BPN}/{PV}/
@ -581,8 +576,7 @@ be performed using the
useradd
class to add user and group configuration to a specific recipe.
Here is an example that uses this class in an image recipe:
::
Here is an example that uses this class in an image recipe::
inherit extrausers
EXTRA_USERS_PARAMS = "\
@ -595,8 +589,7 @@ Here is an example that uses this class in an image recipe:
"
Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
passwords:
::
passwords::
inherit extrausers
EXTRA_USERS_PARAMS = "\
@ -604,8 +597,7 @@ passwords:
useradd -P tester01 tester-sue; \
"
Finally, here is an example that sets the root password to "1876*18":
::
Finally, here is an example that sets the root password to "1876*18"::
inherit extrausers
EXTRA_USERS_PARAMS = "\
@ -867,8 +859,7 @@ system need to either inherit the ``icecc`` class or nobody should.
At the distribution level, you can inherit the ``icecc`` class to be
sure that all builders start with the same sstate signatures. After
inheriting the class, you can then disable the feature by setting the
:term:`ICECC_DISABLED` variable to "1" as follows:
::
:term:`ICECC_DISABLED` variable to "1" as follows::
INHERIT_DISTRO_append = " icecc"
ICECC_DISABLED ??= "1"
@ -876,8 +867,7 @@ inheriting the class, you can then disable the feature by setting the
This practice
makes sure everyone is using the same signatures but also requires
individuals that do want to use Icecream to enable the feature
individually as follows in your ``local.conf`` file:
::
individually as follows in your ``local.conf`` file::
ICECC_DISABLED = ""
@ -925,8 +915,7 @@ types.
By default, the :ref:`image <ref-classes-image>` class automatically
enables the ``image_types`` class. The ``image`` class uses the
``IMGCLASSES`` variable as follows:
::
``IMGCLASSES`` variable as follows::
IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
@ -968,8 +957,7 @@ during the :ref:`ref-tasks-rootfs` task, which optimizes
the size of libraries contained in the image.
By default, the class is enabled in the ``local.conf.template`` using
the :term:`USER_CLASSES` variable as follows:
::
the :term:`USER_CLASSES` variable as follows::
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
@ -984,8 +972,7 @@ the dynamic linking of shared libraries to reduce executable startup
time.
By default, the class is enabled in the ``local.conf.template`` using
the :term:`USER_CLASSES` variable as follows:
::
the :term:`USER_CLASSES` variable as follows::
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
@ -1014,8 +1001,7 @@ configuration). However, to skip one or more checks in recipes, you
should use :term:`INSANE_SKIP`. For example, to skip
the check for symbolic link ``.so`` files in the main package of a
recipe, add the following to the recipe. You need to realize that the
package name override, in this example ``${PN}``, must be used:
::
package name override, in this example ``${PN}``, must be used::
INSANE_SKIP_${PN} += "dev-so"
@ -1152,8 +1138,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
- ``invalid-packageconfig:`` Checks that no undefined features are
being added to :term:`PACKAGECONFIG`. For
example, any name "foo" for which the following form does not exist:
::
example, any name "foo" for which the following form does not exist::
PACKAGECONFIG[foo] = "..."
@ -1636,8 +1621,7 @@ a couple different ways:
.. note::
When creating a recipe this way, the recipe name must follow this
naming convention:
::
naming convention::
myrecipe-native.bb
@ -1645,8 +1629,7 @@ a couple different ways:
Not using this naming convention can lead to subtle problems
caused by existing code that depends on that naming convention.
- Create or modify a target recipe that contains the following:
::
- Create or modify a target recipe that contains the following::
BBCLASSEXTEND = "native"
@ -1677,8 +1660,7 @@ couple different ways:
inherit statement in the recipe after all other inherit statements so
that the ``nativesdk`` class is inherited last.
- Create a ``nativesdk`` variant of any recipe by adding the following:
::
- Create a ``nativesdk`` variant of any recipe by adding the following::
BBCLASSEXTEND = "nativesdk"
@ -1689,8 +1671,7 @@ couple different ways:
.. note::
When creating a recipe, you must follow this naming convention:
::
When creating a recipe, you must follow this naming convention::
nativesdk-myrecipe.bb
@ -1753,8 +1734,7 @@ before attempting to fetch it from the upstream specified in
:term:`SRC_URI` within each recipe.
To use this class, inherit it globally and specify
:term:`SOURCE_MIRROR_URL`. Here is an example:
::
:term:`SOURCE_MIRROR_URL`. Here is an example::
INHERIT += "own-mirrors"
SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
@ -2017,8 +1997,7 @@ established and then populates the SDK. After populating the SDK, the
contains the cross-compiler and associated tooling, and the target,
which contains a target root filesystem that is configured for the SDK
usage. These two images reside in :term:`SDK_OUTPUT`,
which consists of the following:
::
which consists of the following::
${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
@ -2180,8 +2159,7 @@ installed by ``libtool``. Removing these files results in them being
absent from both the sysroot and target packages.
If a recipe needs the ``.la`` files to be installed, then the recipe can
override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:
::
override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
REMOVE_LIBTOOL_LA = "0"
@ -2231,8 +2209,7 @@ recipe, enabling ``rm_work`` will potentially result in your changes to
the source being lost. To exclude some recipes from having their work
directories deleted by ``rm_work``, you can add the names of the recipe
or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which
can also be set in your ``local.conf`` file. Here is an example:
::
can also be set in your ``local.conf`` file. Here is an example::
RM_WORK_EXCLUDE += "busybox glibc"
@ -2531,8 +2508,7 @@ You should set :term:`SYSTEMD_SERVICE` to the
name of the service file. You should also use a package name override to
indicate the package to which the value applies. If the value applies to
the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
is an example from the connman recipe:
::
is an example from the connman recipe::
SYSTEMD_SERVICE_${PN} = "connman.service"
@ -2608,8 +2584,7 @@ The tests are commands that run on the target system over ``ssh``. Each
test is written in Python and makes use of the ``unittest`` module.
The ``testimage.bbclass`` runs tests on an image when called using the
following:
::
following::
$ bitbake -c testimage image
@ -2628,8 +2603,7 @@ section in the Yocto Project Development Tasks Manual.
This class supports running automated tests against software development
kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
using the following:
::
using the following::
$ bitbake -c testsdk image
@ -2684,8 +2658,7 @@ the environment for installed SDKs.
The ``typecheck`` class provides support for validating the values of
variables set at the configuration level against their defined types.
The OpenEmbedded build system allows you to define the type of a
variable using the "type" varflag. Here is an example:
::
variable using the "type" varflag. Here is an example::
IMAGE_FEATURES[type] = "list"
@ -2695,14 +2668,12 @@ variable using the "type" varflag. Here is an example:
========================
The ``uboot-config`` class provides support for U-Boot configuration for
a machine. Specify the machine in your recipe as follows:
::
a machine. Specify the machine in your recipe as follows::
UBOOT_CONFIG ??= <default>
UBOOT_CONFIG[foo] = "config,images"
You can also specify the machine using this method:
::
You can also specify the machine using this method::
UBOOT_MACHINE = "config"

51
documentation/ref-manual/devtool-reference.rst
View File

@ -22,8 +22,7 @@ Getting Help
The ``devtool`` command line is organized similarly to Git in that it
has a number of sub-commands for each function. You can run
``devtool --help`` to see all the commands:
::
``devtool --help`` to see all the commands::
$ devtool -h
NOTE: Starting bitbake server...
@ -79,8 +78,7 @@ has a number of sub-commands for each function. You can run
As directed in the general help output, you can
get more syntax on a specific command by providing the command name and
using "--help":
::
using "--help"::
$ devtool add --help
NOTE: Starting bitbake server...
@ -172,8 +170,7 @@ you. The source files the recipe uses should exist in an external area.
The following example creates and adds a new recipe named ``jackson`` to
a workspace layer the tool creates. The source code built by the recipes
resides in ``/home/user/sources/jackson``:
::
resides in ``/home/user/sources/jackson``::
$ devtool add jackson /home/user/sources/jackson
@ -201,8 +198,7 @@ unpacking files from a remote URI. In some cases, you might want to
specify a source revision by branch, tag, or commit hash. You can
specify these options when using the ``devtool add`` command:
- To specify a source branch, use the ``--srcbranch`` option:
::
- To specify a source branch, use the ``--srcbranch`` option::
$ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/user/sources/jackson
@ -210,8 +206,7 @@ specify these options when using the ``devtool add`` command:
branch.
- To specify a specific tag or commit hash, use the ``--srcrev``
option:
::
option::
$ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/user/sources/jackson
$ devtool add --srcrev some_commit_hash /home/user/sources/jackson
@ -269,8 +264,7 @@ The ``devtool modify`` command extracts the source for a recipe, sets it
up as a Git repository if the source had not already been fetched from
Git, checks out a branch for development, and applies any patches from
the recipe as commits on top. You can use the following command to
checkout the source files:
::
checkout the source files::
$ devtool modify recipe
@ -309,8 +303,7 @@ compile, and test the code.
When you are satisfied with the results and you have committed your
changes to the Git repository, you can then run the
``devtool update-recipe`` to create the patches and update the recipe:
::
``devtool update-recipe`` to create the patches and update the recipe::
$ devtool update-recipe recipe
@ -321,8 +314,7 @@ Often, you might want to apply customizations made to your software in
your own layer rather than apply them to the original recipe. If so, you
can use the ``-a`` or ``--append`` option with the
``devtool update-recipe`` command. These options allow you to specify
the layer into which to write an append file:
::
the layer into which to write an append file::
$ devtool update-recipe recipe -a base-layer-directory
@ -358,8 +350,7 @@ particular recipe.
recipe's latest version tag.
As with all ``devtool`` commands, you can get help on the individual
command:
::
command::
$ devtool check-upgrade-status -h
NOTE: Starting bitbake server...
@ -462,8 +453,7 @@ files have been modified, the command preserves the modified files in a
separate "attic" subdirectory under the workspace layer.
Here is an example that resets the workspace directory that contains the
``mtr`` recipe:
::
``mtr`` recipe::
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
@ -482,8 +472,7 @@ Use the ``devtool build`` command to build your recipe. The
When you use the ``devtool build`` command, you must supply the root
name of the recipe (i.e. do not provide versions, paths, or extensions).
You can use either the "-s" or the "--disable-parallel-make" options to
disable parallel makes during the build. Here is an example:
::
disable parallel makes during the build. Here is an example::
$ devtool build recipe
@ -499,8 +488,7 @@ device for testing. For proper integration into a final image, you need
to edit your custom image recipe appropriately.
When you use the ``devtool build-image`` command, you must supply the
name of the image. This command has no command line options:
::
name of the image. This command has no command line options::
$ devtool build-image image
@ -510,8 +498,7 @@ Deploying Your Software on the Target Machine
=============================================
Use the ``devtool deploy-target`` command to deploy the recipe's build
output to the live target machine:
::
output to the live target machine::
$ devtool deploy-target recipe target
@ -582,15 +569,13 @@ new workspace layer, it is populated with the ``README`` file and the
``conf`` directory only.
The following example creates a new workspace layer in your current
working and by default names the workspace layer "workspace":
::
working and by default names the workspace layer "workspace"::
$ devtool create-workspace
You can create a workspace layer anywhere by supplying a pathname with
the command. The following command creates a new workspace layer named
"new-workspace":
::
"new-workspace"::
$ devtool create-workspace /home/scottrif/new-workspace
@ -603,15 +588,13 @@ Use the ``devtool status`` command to list the recipes currently in your
workspace. Information includes the paths to their respective external
source trees.
The ``devtool status`` command has no command-line options:
::
The ``devtool status`` command has no command-line options::
$ devtool status
Following is sample output after using
:ref:`devtool add <ref-manual/devtool-reference:adding a new recipe to the workspace layer>`
to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
::
to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
$ devtool status
mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)

12
documentation/ref-manual/faq.rst
View File

@ -209,8 +209,7 @@ section in the Yocto Project Development Tasks Manual.
**A:** You need to create a form factor file as described in the
":ref:`bsp-guide/bsp:miscellaneous bsp-specific recipe files`" section in
the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
::
the ``HAVE_TOUCHSCREEN`` variable equal to one as follows::
HAVE_TOUCHSCREEN=1
@ -313,8 +312,7 @@ HTTPS requests and direct them to the ``http://`` sources mirror. You
can use ``file://`` URLs to point to local directories or network shares
as well.
Aside from the previous technique, these options also exist:
::
Aside from the previous technique, these options also exist::
BB_NO_NETWORK = "1"
@ -322,8 +320,7 @@ This statement tells BitBake to issue an error
instead of trying to access the Internet. This technique is useful if
you want to ensure code builds only from local sources.
Here is another technique:
::
Here is another technique::
BB_FETCH_PREMIRRORONLY = "1"
@ -331,8 +328,7 @@ This statement
limits the build system to pulling source from the ``PREMIRRORS`` only.
Again, this technique is useful for reproducing builds.
Here is another technique:
::
Here is another technique::
BB_GENERATE_MIRROR_TARBALLS = "1"

3
documentation/ref-manual/features.rst
View File

@ -26,8 +26,7 @@ One method you can use to determine which recipes are checking to see if
a particular feature is contained or not is to ``grep`` through the
:term:`Metadata` for the feature. Here is an example that
discovers the recipes whose build is potentially changed based on a
given feature:
::
given feature::
$ cd poky
$ git grep 'contains.*MACHINE_FEATURES.*feature'

3
documentation/ref-manual/images.rst
View File

@ -18,8 +18,7 @@ image you want.
are going to build an image using non-GPLv3 and similarly licensed
components, you must make the following changes in the ``local.conf``
file before using the BitBake command to build the minimal or base
image:
::
image::
1. Comment out the EXTRA_IMAGE_FEATURES line
2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"

6
documentation/ref-manual/kickstart.rst
View File

@ -30,8 +30,7 @@ Command: part or partition
==========================
Either of these commands creates a partition on the system and uses the
following syntax:
::
following syntax::
part [mntpoint]
partition [mntpoint]
@ -59,8 +58,7 @@ must also provide one of the ``--ondrive``, ``--ondisk``, or
versions of these application are currently excluded.
Here is an example that uses "/" as the mountpoint. The command uses
``--ondisk`` to force the partition onto the ``sdb`` disk:
::
``--ondisk`` to force the partition onto the ``sdb`` disk::
part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024

3
documentation/ref-manual/migration-1.3.rst
View File

@ -181,8 +181,7 @@ Linux Kernel Naming
-------------------
The naming scheme for kernel output binaries has been changed to now
include :term:`PE` as part of the filename:
::
include :term:`PE` as part of the filename::
KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"

6
documentation/ref-manual/migration-1.4.rst
View File

@ -40,8 +40,7 @@ Differences include the following:
- *Shared State Code:* The shared state code has been optimized to
avoid running unnecessary tasks. For example, the following no longer
populates the target sysroot since that is not necessary:
::
populates the target sysroot since that is not necessary::
$ bitbake -c rootfs some-image
@ -136,8 +135,7 @@ Target Package Management with RPM
If runtime package management is enabled and the RPM backend is
selected, Smart is now installed for package download, dependency
resolution, and upgrades instead of Zypper. For more information on how
to use Smart, run the following command on the target:
::
to use Smart, run the following command on the target::
smart --help

6
documentation/ref-manual/migration-1.6.rst
View File

@ -53,8 +53,7 @@ Matching Branch Requirement for Git Fetching
When fetching source from a Git repository using
:term:`SRC_URI`, BitBake will now validate the
:term:`SRCREV` value against the branch. You can specify
the branch using the following form:
::
the branch using the following form::
SRC_URI = "git://server.name/repository;branch=branchname"
@ -248,8 +247,7 @@ the ``autotools`` or ``autotools_stage``\ classes.
``qemu-native`` now builds without SDL-based graphical output support by
default. The following additional lines are needed in your
``local.conf`` to enable it:
::
``local.conf`` to enable it::
PACKAGECONFIG_pn-qemu-native = "sdl"
ASSUME_PROVIDED += "libsdl-native"

6
documentation/ref-manual/migration-1.7.rst
View File

@ -15,8 +15,7 @@ optional features. The method used to set defaults for these options
means that existing ``local.conf`` files will need to be modified to
append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
instead of setting it. In other words, to enable graphical output for
QEMU, you should now have these lines in ``local.conf``:
::
QEMU, you should now have these lines in ``local.conf``::
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
@ -80,8 +79,7 @@ disable the scripts due to the scripts previously requiring error-prone
path substitution. Software that links against these libraries using
these scripts should use the much more robust ``pkg-config`` instead.
The list of recipes changed in this version (and their configuration
scripts) is as follows:
::
scripts) is as follows::
directfb (directfb-config)
freetype (freetype-config)

9
documentation/ref-manual/migration-2.0.rst
View File

@ -25,8 +25,7 @@ and the porting guide at
https://gcc.gnu.org/gcc-5/porting_to.html.
Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
``GCCVERSION`` in your configuration, as follows:
::
``GCCVERSION`` in your configuration, as follows::
GCCVERSION = "4.9%"
@ -91,8 +90,7 @@ unlikely to require any changes to Metadata. However, these minor
changes in behavior exist:
- All potential overrides are now visible in the variable history as
seen when you run the following:
::
seen when you run the following::
$ bitbake -e
@ -200,8 +198,7 @@ changes.
Additionally, work directories for old versions of recipes are now
pruned. If you wish to disable pruning old work directories, you can set
the following variable in your configuration:
::
the following variable in your configuration::
SSTATE_PRUNE_OBSOLETEWORKDIR = "0"

9
documentation/ref-manual/migration-2.1.rst
View File

@ -42,8 +42,7 @@ defaulted to False if not specified. Now, however, no default exists so
one must be specified. You must change any ``getVar()`` calls that do
not specify the final expand parameter to calls that do specify the
parameter. You can run the following ``sed`` command at the base of a
layer to make this change:
::
layer to make this change::
sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
@ -285,8 +284,7 @@ The following changes have been made for the Poky distribution:
Any recipe that needs to opt-out of having the "--disable-static"
option specified on the configure command line either because it is
not a supported option for the configure script or because static
libraries are needed should set the following variable:
::
libraries are needed should set the following variable::
DISABLE_STATIC = ""
@ -369,8 +367,7 @@ These additional changes exist:
- Previously, the following list of packages were removed if
package-management was not in
:term:`IMAGE_FEATURES`, regardless of any
dependencies:
::
dependencies::
update-rc.d
base-passwd

12
documentation/ref-manual/migration-2.2.rst
View File

@ -144,8 +144,7 @@ The new ``runqemu`` is a Python script. Machine knowledge is no longer
hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
configuration file to define the BSP's own arguments and to make it
bootable with ``runqemu``. If you use a configuration file, use the
following form:
::
following form::
image-name-machine.qemuboot.conf
@ -160,8 +159,7 @@ rootfs). QEMU boot arguments can be set in BSP's configuration file and
the ``qemuboot`` class will save them to ``qemuboot.conf``.
If you want to use ``runqemu`` without a configuration file, use the
following command form:
::
following command form::
$ runqemu machine rootfs kernel [options]
@ -244,8 +242,7 @@ recipes. You need to fix these recipes so that they use the expected
``LDFLAGS``. Depending on how the software is built, the build system
used by the software (e.g. a Makefile) might need to be patched.
However, sometimes making this fix is as simple as adding the following
to the recipe:
::
to the recipe::
TARGET_CC_ARCH += "${LDFLAGS}"
@ -258,8 +255,7 @@ The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
:term:`KERNEL_IMAGETYPE` variable to create the
image's base name. Because the OpenEmbedded build system can now build
multiple kernel image types, this part of the kernel image base name as
been removed leaving only the following:
::
been removed leaving only the following::
KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"

16
documentation/ref-manual/migration-2.3.rst
View File

@ -114,8 +114,7 @@ Changes to Scripts
The following changes to scripts took place:
- ``oe-find-native-sysroot``: The usage for the
``oe-find-native-sysroot`` script has changed to the following:
::
``oe-find-native-sysroot`` script has changed to the following::
$ . oe-find-native-sysroot recipe
@ -124,8 +123,7 @@ The following changes to scripts took place:
was not necessary to provide the script with the command.
- ``oe-run-native``: The usage for the ``oe-run-native`` script has
changed to the following:
::
changed to the following::
$ oe-run-native native_recipe tool
@ -453,14 +451,11 @@ The following miscellaneous changes have occurred:
tools.
- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
``DISTRO_FEATURES`` feature. Distributions that previously set:
::
``DISTRO_FEATURES`` feature. Distributions that previously set::
USE_LDCONFIG = "0"
should now instead use the following:
::
should now instead use the following::
DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
@ -478,8 +473,7 @@ The following miscellaneous changes have occurred:
order to allow module packages from multiple kernel versions to
co-exist on a target system. If you wish to return to the previous
naming scheme that does not include the version suffix, use the
following:
::
following::
KERNEL_MODULE_PACKAGE_SUFFIX = ""

6
documentation/ref-manual/migration-2.5.rst
View File

@ -138,13 +138,11 @@ The following are BitBake changes:
tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
and the ``*all`` tasks provided by the ``distrodata`` and
``archiver`` classes). There is a BitBake option to complete this for
any arbitrary task. For example:
::
any arbitrary task. For example::
bitbake <target> -c fetchall
should now be replaced with:
::
should now be replaced with::
bitbake <target> --runall=fetch

15
documentation/ref-manual/migration-2.6.rst
View File

@ -161,13 +161,11 @@ The following changes have been made:
allows easier and more direct changes.
The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
configuration file as follows:
::
configuration file as follows::
IMAGE_VERSION_SUFFIX = "-${DATETIME}"
- Several variables have changed names for consistency:
::
- Several variables have changed names for consistency::
Old Variable Name New Variable Name
========================================================
@ -292,8 +290,7 @@ avoids the ``systemd`` recipe from becoming machine-specific for cases
where machine-specific configurations need to be applied (e.g. for
``qemu*`` machines).
Currently, the new recipe packages the following files:
::
Currently, the new recipe packages the following files::
${sysconfdir}/machine-id
${sysconfdir}/systemd/coredump.conf
@ -393,8 +390,7 @@ If you wish to disable Python profile-guided optimization regardless of
the value of ``MACHINE_FEATURES``, then ensure that
:term:`PACKAGECONFIG` for the ``python3`` recipe
does not contain "pgo". You could accomplish the latter using the
following at the configuration level:
::
following at the configuration level::
PACKAGECONFIG_remove_pn-python3 = "pgo"
@ -411,8 +407,7 @@ The following miscellaneous changes occurred:
- Default to using the Thumb-2 instruction set for armv7a and above. If
you have any custom recipes that build software that needs to be
built with the ARM instruction set, change the recipe to set the
instruction set as follows:
::
instruction set as follows::
ARM_INSTRUCTION_SET = "arm"

3
documentation/ref-manual/migration-3.1.rst
View File

@ -71,8 +71,7 @@ when building a simple image such as core-image-minimal. If you do not
need runtime tests enabled for core components, then it is recommended
that you remove "ptest" from
:term:`DISTRO_FEATURES` to save a significant
amount of build time e.g. by adding the following in your configuration:
::
amount of build time e.g. by adding the following in your configuration::
DISTRO_FEATURES_remove = "ptest"

9
documentation/ref-manual/qa-checks.rst
View File

@ -221,8 +221,7 @@ Errors and Warnings
Typically, the way to solve this performance issue is to add "-fPIC"
or "-fpic" to the compiler command-line options. For example, given
software that reads :term:`CFLAGS` when you build it,
you could add the following to your recipe:
::
you could add the following to your recipe::
CFLAGS_append = " -fPIC "
@ -240,8 +239,7 @@ Errors and Warnings
variable is being passed to the linker command. A common workaround
for this situation is to pass in ``LDFLAGS`` using
:term:`TARGET_CC_ARCH` within the recipe as
follows:
::
follows::
TARGET_CC_ARCH += "${LDFLAGS}"
@ -265,8 +263,7 @@ Errors and Warnings
The ``/usr/share/info/dir`` should not be packaged. Add the following
line to your :ref:`ref-tasks-install` task or to your
``do_install_append`` within the recipe as follows:
::
``do_install_append`` within the recipe as follows::
rm ${D}${infodir}/dir
 

18
documentation/ref-manual/structure.rst
View File

@ -153,8 +153,7 @@ 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:
::
possible targets to build. Here is an example::
$ source oe-init-build-env
@ -185,8 +184,7 @@ creates the ``build/`` directory in your current working directory. If
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`:
::
Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`::
$ source oe-init-build-env ~/mybuilds
@ -269,8 +267,7 @@ and to ``meta/conf/`` when you are building from the OpenEmbedded-Core
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:
::
top-level build environment setup script as follows::
TEMPLATECONF=your_layer/conf
@ -309,8 +306,7 @@ Project development environment, and to ``meta/conf/`` when you are
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:
::
variable in the top-level build environment setup script as follows::
TEMPLATECONF=your_layer/conf
@ -463,8 +459,7 @@ 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:
::
the kernel files::
$ bitbake -c clean virtual/kernel
$ bitbake virtual/kernel
@ -535,8 +530,7 @@ recipe-specific :term:`WORKDIR` directories. Thus, the
This directory holds information that BitBake uses for accounting
purposes to track what tasks have run and when they have run. The
directory is sub-divided by architecture, package name, and version.
Following is an example:
::
Following is an example::
stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do

69
documentation/ref-manual/system-requirements.rst
View File

@ -120,8 +120,7 @@ supported Ubuntu or Debian Linux distribution:
might experience QEMU build failures due to the package installing
its own custom ``/usr/include/linux/soundcard.h`` on the Debian
system. If you run into this situation, either of the following
solutions exist:
::
solutions exist::
$ sudo apt-get build-dep qemu
$ sudo apt-get remove oss4-dev
@ -132,14 +131,12 @@ supported Ubuntu or Debian Linux distribution:
$ sudo pip3 install GitPython pylint==1.9.5
- *Essentials:* Packages needed to build an image on a headless system:
::
- *Essentials:* Packages needed to build an image on a headless system::
$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals:
::
Yocto Project documentation manuals::
$ sudo apt-get install make python3-pip
&PIP3_HOST_PACKAGES_DOC;
@ -157,14 +154,12 @@ The following list shows the required packages by function given a
supported Fedora Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system:
::
system::
$ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals:
::
Yocto Project documentation manuals::
$ sudo dnf install make python3-pip which
&PIP3_HOST_PACKAGES_DOC;
@ -176,14 +171,12 @@ The following list shows the required packages by function given a
supported openSUSE Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system:
::
system::
$ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals:
::
Yocto Project documentation manuals::
$ sudo zypper install make python3-pip which
&PIP3_HOST_PACKAGES_DOC;
@ -196,8 +189,7 @@ The following list shows the required packages by function given a
supported CentOS-7 Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system:
::
system::
$ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
@ -212,8 +204,7 @@ supported CentOS-7 Linux distribution:
``epel-release``.
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals:
::
Yocto Project documentation manuals::
$ sudo yum install make python3-pip which
&PIP3_HOST_PACKAGES_DOC;
@ -225,8 +216,7 @@ The following list shows the required packages by function given a
supported CentOS-8 Linux distribution:
- *Essentials:* Packages needed to build an image for a headless
system:
::
system::
$ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
@ -244,8 +234,7 @@ supported CentOS-8 Linux distribution:
``epel-release``.
- *Documentation:* Packages needed if you are going to build out the
Yocto Project documentation manuals:
::
Yocto Project documentation manuals::
$ sudo dnf install make python3-pip which
&PIP3_HOST_PACKAGES_DOC;
@ -287,8 +276,7 @@ The ``install-buildtools`` script is the easiest of the three methods by
which you can get these tools. It downloads a pre-built buildtools
installer and automatically installs the tools for you:
1. Execute the ``install-buildtools`` script. Here is an example:
::
1. Execute the ``install-buildtools`` script. Here is an example::
$ cd poky
$ scripts/install-buildtools --without-extended-buildtools \
@ -302,22 +290,19 @@ installer and automatically installs the tools for you:
installation is functional.
To avoid the need of ``sudo`` privileges, the ``install-buildtools``
script will by default tell the installer to install in:
::
script will by default tell the installer to install in::
/path/to/poky/buildtools
If your host development system needs the additional tools provided
in the ``buildtools-extended`` tarball, you can instead execute the
``install-buildtools`` script with the default parameters:
::
``install-buildtools`` script with the default parameters::
$ cd poky
$ scripts/install-buildtools
2. Source the tools environment setup script by using a command like the
following:
::
following::
$ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
@ -342,13 +327,11 @@ steps:
1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
2. Execute the installation script. Here is an example for the
traditional installer:
::
traditional installer::
$ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
Here is an example for the extended installer:
::
Here is an example for the extended installer::
$ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
@ -357,8 +340,7 @@ steps:
``/home/your-username/buildtools``
3. Source the tools environment setup script by using a command like the
following:
::
following::
$ source /home/your_username/buildtools/environment-setup-i586-poky-linux
@ -390,13 +372,11 @@ installer:
your build environment with the setup script
(:ref:`structure-core-script`).
2. Run the BitBake command to build the tarball:
::
2. Run the BitBake command to build the tarball::
$ bitbake buildtools-tarball
or run the BitBake command to build the extended tarball:
::
or run the BitBake command to build the extended tarball::
$ bitbake buildtools-extended-tarball
@ -415,13 +395,11 @@ installer:
4. On the machine that does not meet the requirements, run the ``.sh``
file to install the tools. Here is an example for the traditional
installer:
::
installer::
$ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
Here is an example for the extended installer:
::
Here is an example for the extended installer::
$ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
@ -430,8 +408,7 @@ installer:
``/home/your_username/buildtools``
5. Source the tools environment setup script by using a command like the
following:
::
following::
$ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux

48
documentation/ref-manual/tasks.rst
View File

@ -93,8 +93,7 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``.
The ``do_deploy`` task is not added as a task by default and
consequently needs to be added manually. If you want the task to run
after :ref:`ref-tasks-compile`, you can add it by doing
the following:
::
the following::
addtask deploy after do_compile
@ -103,8 +102,7 @@ Adding ``do_deploy`` after other tasks works the same way.
.. note::
You do not need to add ``before do_build`` to the ``addtask`` command
(though it is harmless), because the ``base`` class contains the following:
::
(though it is harmless), because the ``base`` class contains the following::
do_build[recrdeptask] += "do_deploy"
@ -302,13 +300,11 @@ Patch files, by default, are ``*.patch`` and ``*.diff`` files created
and kept in a subdirectory of the directory holding the recipe file. For
example, consider the
:yocto_git:`bluez5 </poky/tree/meta/recipes-connectivity/bluez5>`
recipe from the OE-Core layer (i.e. ``poky/meta``):
::
recipe from the OE-Core layer (i.e. ``poky/meta``)::
poky/meta/recipes-connectivity/bluez5
This recipe has two patch files located here:
::
This recipe has two patch files located here::
poky/meta/recipes-connectivity/bluez5/bluez5
@ -323,8 +319,7 @@ and patch files needed to build the package.
As mentioned earlier, the build system treats files whose file types are
``.patch`` and ``.diff`` as patch files. However, you can use the
"apply=yes" parameter with the ``SRC_URI`` statement to indicate any
file as a patch file:
::
file as a patch file::
SRC_URI = " \
git://path_to_repo/some_package \
@ -334,8 +329,7 @@ file as a patch file:
Conversely, if you have a directory full of patch files and you want to
exclude some so that the ``do_patch`` task does not apply them during
the patch phase, you can use the "apply=no" parameter with the
``SRC_URI`` statement:
::
``SRC_URI`` statement::
SRC_URI = " \
git://path_to_repo/some_package \
@ -455,8 +449,7 @@ of the recipe exists upstream and a status of not updated, updated, or
unknown.
To check the upstream version and status of a recipe, use the following
devtool commands:
::
devtool commands::
$ devtool latest-version
$ devtool check-upgrade-status
@ -467,8 +460,7 @@ chapter for more information on
section for information on checking the upgrade status of a recipe.
To build the ``checkpkg`` task, use the ``bitbake`` command with the
"-c" option and task name:
::
"-c" option and task name::
$ bitbake core-image-minimal -c checkpkg
@ -494,8 +486,7 @@ Removes all output files for a target from the
:ref:`ref-tasks-install`, and
:ref:`ref-tasks-package`).
You can run this task using BitBake as follows:
::
You can run this task using BitBake as follows::
$ bitbake -c clean recipe
@ -519,8 +510,7 @@ downloaded source files for a target (i.e. the contents of
identical to the :ref:`ref-tasks-cleansstate` task
with the added removal of downloaded source files.
You can run this task using BitBake as follows:
::
You can run this task using BitBake as follows::
$ bitbake -c cleanall recipe
@ -540,8 +530,7 @@ target. Essentially, the ``do_cleansstate`` task is identical to the
shared state (:ref:`sstate <overview-manual/concepts:shared state cache>`)
cache.
You can run this task using BitBake as follows:
::
You can run this task using BitBake as follows::
$ bitbake -c cleansstate recipe
@ -553,8 +542,7 @@ scratch is guaranteed.
The ``do_cleansstate`` task cannot remove sstate from a remote sstate
mirror. If you need to build a target from scratch using remote mirrors, use
the "-f" option as follows:
::
the "-f" option as follows::
$ bitbake -f -c do_cleansstate target
@ -687,8 +675,7 @@ changes made by the user with other methods (i.e. using
(:ref:`ref-tasks-kernel_menuconfig`). Once the
file of differences is created, it can be used to create a config
fragment that only contains the differences. You can invoke this task
from the command line as follows:
::
from the command line as follows::
$ bitbake linux-yocto -c diffconfig
@ -718,8 +705,7 @@ Validates the configuration produced by the
configuration does not appear in the final ``.config`` file or when you
override a policy configuration in a hardware configuration fragment.
You can run this task explicitly and view the output by using the
following command:
::
following command::
$ bitbake linux-yocto -c kernel_configcheck -f
@ -750,8 +736,7 @@ tool, which you then use to modify the kernel configuration.
.. note::
You can also invoke this tool from the command line as follows:
::
You can also invoke this tool from the command line as follows::
$ bitbake linux-yocto -c menuconfig
@ -793,8 +778,7 @@ instead of the default defconfig. The saved defconfig contains the
differences between the default defconfig and the changes made by the
user using other methods (i.e. the
:ref:`ref-tasks-kernel_menuconfig` task. You
can invoke the task using the following command:
::
can invoke the task using the following command::
$ bitbake linux-yocto -c savedefconfig

3
documentation/ref-manual/terms.rst
View File

@ -26,8 +26,7 @@ universal, the list includes them just in case:
When you name an append file, you can use the "``%``" wildcard character
to allow for matching recipe names. For example, suppose you have an
append file named as follows:
::
append file named as follows::
busybox_1.21.%.bbappend

849
documentation/ref-manual/variables.rst
View File

File diff suppressed because it is too large Load Diff

27
documentation/sdk-manual/appendix-customizing.rst
View File

@ -149,8 +149,7 @@ from the :term:`DISTRO` variable.
The
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
class defines the default value of the ``SDK_TITLE`` variable as
follows:
::
follows::
SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
@ -162,8 +161,7 @@ an example, assume you have your own layer for your distribution named
does the default "poky" distribution. If so, you could update the
``SDK_TITLE`` variable in the
``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
form:
::
form::
SDK_TITLE = "your_title"
@ -194,8 +192,7 @@ the installed SDKs to update the installed SDKs by using the
3. Build the extensible SDK normally (i.e., use the
``bitbake -c populate_sdk_ext`` imagename command).
4. Publish the SDK using the following command:
::
4. Publish the SDK using the following command::
$ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
@ -218,8 +215,7 @@ installation directory for the SDK is based on the
:term:`SDKEXTPATH` variables from
within the
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
class as follows:
::
class as follows::
SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
@ -236,8 +232,7 @@ assume you have your own layer for your distribution named
does the default "poky" distribution. If so, you could update the
``SDKEXTPATH`` variable in the
``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
form:
::
form::
SDKEXTPATH = "some_path_for_your_installed_sdk"
@ -272,8 +267,7 @@ source, you need to do a number of things:
3. Set the appropriate configuration so that the produced SDK knows how
to find the configuration. The variable you need to set is
:term:`SSTATE_MIRRORS`:
::
:term:`SSTATE_MIRRORS`::
SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
@ -287,8 +281,7 @@ source, you need to do a number of things:
side, and its contents will not interfere with the build), then
you can set the variable in your ``local.conf`` or custom distro
configuration file. You can then "whitelist" the variable through
to the SDK by adding the following:
::
to the SDK by adding the following::
SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
@ -313,8 +306,7 @@ everything needed to reconstruct the image for which the SDK was built.
This bundling can lead to an SDK installer file that is a Gigabyte or
more in size. If the size of this file causes a problem, you can build
an SDK that has just enough in it to install and provide access to the
``devtool command`` by setting the following in your configuration:
::
``devtool command`` by setting the following in your configuration::
SDK_EXT_TYPE = "minimal"
@ -336,8 +328,7 @@ information enables the ``devtool search`` command to return useful
results.
To facilitate this wider range of information, you would need to set the
following:
::
following::
SDK_INCLUDE_PKGDATA = "1"

30
documentation/sdk-manual/appendix-obtain.rst
View File

@ -25,8 +25,7 @@ Follow these steps to locate and hand-install the toolchain:
download the installer appropriate for your build host, target
hardware, and image type.
The installer files (``*.sh``) follow this naming convention:
::
The installer files (``*.sh``) follow this naming convention::
poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
@ -55,15 +54,13 @@ Follow these steps to locate and hand-install the toolchain:
For example, if your build host is a 64-bit x86 system and you need
an extended SDK for a 64-bit core2 target, go into the ``x86_64``
folder and download the following installer:
::
folder and download the following installer::
poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
4. *Run the Installer:* Be sure you have execution privileges and run
the installer. Following is an example from the ``Downloads``
directory:
::
directory::
$ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
@ -132,8 +129,7 @@ build the SDK installer. Follow these steps:
using to build the installer. If
SDKMACHINE
is not set appropriately, the build fails and provides an error
message similar to the following:
::
message similar to the following::
The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
@ -144,8 +140,7 @@ build the SDK installer. Follow these steps:
SDK and populate the SDK image, use the following command form. Be
sure to replace image with an image (e.g. "core-image-sato"): $
bitbake image -c populate_sdk You can do the same for the extensible
SDK using this command form:
::
SDK using this command form::
$ bitbake image -c populate_sdk_ext
@ -170,8 +165,7 @@ build the SDK installer. Follow these steps:
libc-staticdev"
7. *Run the Installer:* You can now run the SDK installer from
``tmp/deploy/sdk`` in the Build Directory. Following is an example:
::
``tmp/deploy/sdk`` in the Build Directory. Following is an example::
$ cd poky/build/tmp/deploy/sdk
$ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh
@ -211,8 +205,7 @@ Follow these steps to extract the root filesystem:
which you can use with QEMU directly.
The pre-built root filesystem image files follow these naming
conventions:
::
conventions::
core-image-profile-arch.tar.bz2
@ -233,8 +226,7 @@ Follow these steps to extract the root filesystem:
For example, if you plan on using a BeagleBone device as your target
hardware and your image is a ``core-image-sato-sdk`` image, you can
download the following file:
::
download the following file::
core-image-sato-sdk-beaglebone-yocto.tar.bz2
@ -246,8 +238,7 @@ Follow these steps to extract the root filesystem:
installed the toolchain (e.g. ``poky_sdk``).
Following is an example based on the toolchain installed in the
":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section:
::
":ref:`sdk-manual/appendix-obtain:locating pre-built sdk installers`" section::
$ source poky_sdk/environment-setup-core2-64-poky-linux
@ -258,8 +249,7 @@ Follow these steps to extract the root filesystem:
from a previously built root filesystem image that was downloaded
from the :yocto_dl:`Index of Releases </releases/yocto/yocto-&DISTRO;/machines/>`.
This command extracts the root filesystem into the ``core2-64-sato``
directory:
::
directory::
$ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato

81
documentation/sdk-manual/extensible.rst
View File

@ -59,8 +59,7 @@ The names of the tarball installer scripts are such that a string
representing the host system appears first in the filename and then is
immediately followed by a string representing the target architecture.
An extensible SDK has the string "-ext" as part of the name. Following
is the general form:
::
is the general form::
poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
@ -83,8 +82,7 @@ is the general form:
For example, the following SDK installer is for a 64-bit
development host system and a i586-tuned target architecture based off
the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot:
::
the SDK for ``core-image-sato`` and using the current &DISTRO; snapshot::
poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh
@ -150,8 +148,7 @@ begin with the string "``environment-setup``" and include as part of
their name the tuned target architecture. As an example, the following
commands set the working directory to where the SDK was installed and
then source the environment setup script. In this example, the setup
script is for an IA-based target machine using i586 tuning:
::
script is for an IA-based target machine using i586 tuning::
$ cd /home/scottrif/poky_sdk
$ source environment-setup-core2-64-poky-linux
@ -258,8 +255,7 @@ command:
to be extracted. In this situation, the source code is extracted
to the default workspace - you do not want the files in some
specific location outside of the workspace. Thus, everything you
need will be located in the workspace:
::
need will be located in the workspace::
$ devtool add recipe fetchuri
@ -283,8 +279,7 @@ command:
Furthermore, the first positional argument srctree in this case
identifies where the ``devtool add`` command will locate the
extracted code outside of the workspace. You need to specify an
empty directory:
::
empty directory::
$ devtool add recipe srctree fetchuri
@ -300,8 +295,7 @@ command:
``devtool`` workspace.
The following command provides a new recipe name and identifies
the existing source tree location:
::
the existing source tree location::
$ devtool add recipe srctree
@ -317,8 +311,7 @@ command:
2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
editor as defined by the ``$EDITOR`` environment variable and modify
the file:
::
the file::
$ devtool edit-recipe recipe
@ -338,8 +331,7 @@ command:
On the other hand, if you want an image to contain the recipe's
packages from the workspace for immediate deployment onto a device
(e.g. for testing purposes), you can use the ``devtool build-image``
command:
::
command::
$ devtool build-image image
@ -435,8 +427,7 @@ command:
outside the workspace (i.e. ``meta-``\ layername).
The following command identifies the recipe and, by default,
extracts the source files:
::
extracts the source files::
$ devtool modify recipe
@ -474,8 +465,7 @@ command:
The following command tells ``devtool`` the recipe with which to
work and, in this case, identifies a local area for the extracted
source files that exists outside of the default ``devtool``
workspace:
::
workspace::
$ devtool modify recipe srctree
@ -508,8 +498,7 @@ command:
The following command tells ``devtool`` the recipe with which to
work, uses the "-n" option to indicate source does not need to be
extracted, and uses srctree to point to the previously extracted
source files:
::
source files::
$ devtool modify -n recipe srctree
@ -532,8 +521,7 @@ command:
depends on what you are going to do with the new code.
If you need to eventually move the build output to the target
hardware, use the following ``devtool`` command:
::
hardware, use the following ``devtool`` command::
$ devtool build recipe
@ -556,8 +544,7 @@ command:
development machine.
You can deploy your build output to that target hardware by using the
``devtool deploy-target`` command:
::
``devtool deploy-target`` command::
$ devtool deploy-target recipe target
@ -651,8 +638,7 @@ The following diagram shows the common development flow used with the
A common situation is where third-party software has undergone a
revision so that it has been upgraded. The recipe you have access to
is likely in your own layer. Thus, you need to upgrade the recipe to
use the newer version of the software:
::
use the newer version of the software::
$ devtool upgrade -V version recipe
@ -703,16 +689,14 @@ The following diagram shows the common development flow used with the
depends on what you are going to do with the new code.
If you need to eventually move the build output to the target
hardware, use the following ``devtool`` command:
::
hardware, use the following ``devtool`` command::
$ devtool build recipe
On the other hand, if you want an image to contain the recipe's
packages from the workspace for immediate deployment onto a device
(e.g. for testing purposes), you can use the ``devtool build-image``
command:
::
command::
$ devtool build-image image
@ -828,8 +812,7 @@ name and version, just the name, or just the version as part of the
command line.
Sometimes the name or version determined from the source tree might be
incorrect. For such a case, you must reset the recipe:
::
incorrect. For such a case, you must reset the recipe::
$ devtool reset -n recipename
@ -853,8 +836,7 @@ the ``DEPENDS`` variable in the original recipe to include the new
recipe.
If you need to add runtime dependencies, you can do so by adding the
following to your recipe:
::
following to your recipe::
RDEPENDS_${PN} += "dependency1 dependency2 ..."
@ -938,8 +920,7 @@ mind:
the command line, add the variable setting to
:term:`EXTRA_OEMAKE` or
:term:`PACKAGECONFIG_CONFARGS`
within the recipe. Here is an example using ``EXTRA_OEMAKE``:
::
within the recipe. Here is an example using ``EXTRA_OEMAKE``::
EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
@ -993,8 +974,7 @@ You can use the ``devtool add`` command two different ways to add
Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
source.
Use the following form to add Node.js modules through ``npm``:
::
Use the following form to add Node.js modules through ``npm``::
$ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
@ -1018,8 +998,7 @@ these behaviors ensure the reproducibility and integrity of the build.
As mentioned earlier, you can also add Node.js modules directly from a
repository or local source tree. To add modules this way, use
``devtool add`` in the following form:
::
``devtool add`` in the following form::
$ devtool add https://github.com/diversario/node-ssdp
@ -1196,15 +1175,13 @@ need to restore the original files that existed prior to running the
``devtool deploy-target`` command. Because the ``devtool deploy-target``
command backs up any files it overwrites, you can use the
``devtool undeploy-target`` command to restore those files and remove
any other files the recipe deployed. Consider the following example:
::
any other files the recipe deployed. Consider the following example::
$ devtool undeploy-target lighttpd root@192.168.7.2
If you have deployed
multiple applications, you can remove them all using the "-a" option
thus restoring the target device to its original state:
::
thus restoring the target device to its original state::
$ devtool undeploy-target -a root@192.168.7.2
@ -1235,22 +1212,19 @@ populated on-demand. Sometimes you must explicitly install extra items
into the SDK. If you need these extra items, you can first search for
the items using the ``devtool search`` command. For example, suppose you
need to link to libGL but you are not sure which recipe provides libGL.
You can use the following command to find out:
::
You can use the following command to find out::
$ devtool search libGL mesa
A free implementation of the OpenGL API Once you know the recipe
(i.e. ``mesa`` in this example), you can install it:
::
(i.e. ``mesa`` in this example), you can install it::
$ devtool sdk-install mesa
By default, the ``devtool sdk-install`` command assumes
the item is available in pre-built form from your SDK provider. If the
item is not available and it is acceptable to build the item from
source, you can add the "-s" option as follows:
::
source, you can add the "-s" option as follows::
$ devtool sdk-install -s mesa
@ -1266,8 +1240,7 @@ If you are working with an installed extensible SDK that gets
occasionally updated (e.g. a third-party SDK), then you will need to
manually "pull down" the updates into the installed SDK.
To update your installed SDK, use ``devtool`` as follows:
::
To update your installed SDK, use ``devtool`` as follows::
$ devtool sdk-update

6
documentation/sdk-manual/using.rst
View File

@ -77,8 +77,7 @@ immediately followed by a string representing the target architecture.
For example, the following SDK installer is for a 64-bit
development host system and a i586-tuned target architecture based off
the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
::
the SDK for ``core-image-sato`` and using the current DISTRO snapshot::
poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
@ -141,8 +140,7 @@ begin with the string "``environment-setup``" and include as part of
their name the tuned target architecture. As an example, the following
commands set the working directory to where the SDK was installed and
then source the environment setup script. In this example, the setup
script is for an IA-based target machine using i586 tuning:
::
script is for an IA-based target machine using i586 tuning::
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux

60
documentation/sdk-manual/working-projects.rst
View File

@ -45,16 +45,14 @@ project:
respectively.
Use the following command to create an empty README file, which is
required by GNU Coding Standards:
::
required by GNU Coding Standards::
$ touch README
Create the remaining
three files as follows:
- ``hello.c``:
::
- ``hello.c``::
#include <stdio.h>
@ -63,8 +61,7 @@ project:
printf("Hello World!\n");
}
- ``configure.ac``:
::
- ``configure.ac``::
AC_INIT(hello,0.1)
AM_INIT_AUTOMAKE([foreign])
@ -72,8 +69,7 @@ project:
AC_CONFIG_FILES(Makefile)
AC_OUTPUT
- ``Makefile.am``:
::
- ``Makefile.am``::
bin_PROGRAMS = hello
hello_SOURCES = hello.c
@ -87,8 +83,7 @@ project:
which is followed by the string "poky-linux". For this example, the
command sources a script from the default SDK installation directory
that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
Project release:
::
Project release::
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
@ -113,8 +108,7 @@ project:
the cross-compiler. The
:term:`CONFIGURE_FLAGS`
environment variable provides the minimal arguments for GNU
configure:
::
configure::
$ ./configure ${CONFIGURE_FLAGS}
@ -127,14 +121,12 @@ project:
``armv5te-poky-linux-gnueabi``. You will notice that the name of the
script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
following command works to update your project and rebuild it using
the appropriate cross-toolchain tools:
::
the appropriate cross-toolchain tools::
$ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
5. *Make and Install the Project:* These two commands generate and
install the project into the destination directory:
::
install the project into the destination directory::
$ make
$ make install DESTDIR=./tmp
@ -157,8 +149,7 @@ project:
6. *Execute Your Project:* To execute the project, you would need to run
it on your target hardware. If your target hardware happens to be
your build host, you could run the project as follows:
::
your build host, you could run the project as follows::
$ ./tmp/usr/local/bin/hello
@ -203,8 +194,7 @@ regarding variable behavior:
.. note::
Regardless of how you set your variables, if you use the "-e" option
with ``make``, the variables from the SDK setup script take precedence:
::
with ``make``, the variables from the SDK setup script take precedence::
$ make -e target
@ -226,8 +216,7 @@ Running the
SDK setup script for a 64-bit build host and an i586-tuned target
architecture for a ``core-image-sato`` image using the current &DISTRO;
Yocto Project release and then echoing that variable shows the value
established through the script:
::
established through the script::
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
$ echo ${CC}
@ -252,8 +241,7 @@ example:
Create the three files as follows:
- ``main.c``:
::
- ``main.c``::
#include "module.h"
void sample_func();
@ -263,14 +251,12 @@ example:
return 0;
}
- ``module.h``:
::
- ``module.h``::
#include <stdio.h>
void sample_func();
- ``module.c``:
::
- ``module.c``::
#include "module.h"
void sample_func()
@ -288,8 +274,7 @@ example:
which is followed by the string "poky-linux". For this example, the
command sources a script from the default SDK installation directory
that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
Project release:
::
Project release::
$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
@ -297,8 +282,7 @@ example:
two lines that can be used to set the ``CC`` variable. One line is
identical to the value that is set when you run the SDK environment
setup script, and the other line sets ``CC`` to "gcc", the default
GNU compiler on the build host:
::
GNU compiler on the build host::
# CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
# CC="gcc"
@ -315,8 +299,7 @@ example:
4. *Make the Project:* Use the ``make`` command to create the binary
output file. Because variables are commented out in the Makefile, the
value used for ``CC`` is the value set when the SDK environment setup
file was run:
::
file was run::
$ make
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
@ -351,8 +334,7 @@ example:
variable as part of the command line. Go into the Makefile and
re-insert the comment character so that running ``make`` uses the
established SDK compiler. However, when you run ``make``, use a
command-line argument to set ``CC`` to "gcc":
::
command-line argument to set ``CC`` to "gcc"::
$ make clean
rm -rf *.o
@ -376,8 +358,7 @@ example:
environment variable.
In this last case, edit Makefile again to use the "gcc" compiler but
then use the "-e" option on the ``make`` command line:
::
then use the "-e" option on the ``make`` command line::
$ make clean
rm -rf *.o
@ -402,8 +383,7 @@ example:
Makefile.
5. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
use the following command:
::
use the following command::
$ ./target_bin
Hello World!