mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-01-29 21:08:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
(From yocto-docs rev: 8e73d870e9dc2df416f5c5cf5b10ef552be0aa6d)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie
2020-09-13 22:03:26 +01:00
parent 292598164a
commit 688e49bb5e
4 changed files with 3196 additions and 1536 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

File diff suppressed because it is too large Load Diff

13
documentation/dev-manual/dev-manual-intro.rst
View File

@@ -32,16 +32,14 @@ This manual provides the following:
This manual does not provide the following:
- Redundant Step-by-step Instructions: For example, the `Yocto Project
Application Development and the Extensible Software Development Kit
(eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual contains detailed
- Redundant Step-by-step Instructions: For example, the
:doc:`../sdk-manual/sdk-manual` manual contains detailed
instructions on how to install an SDK, which is used to develop
applications for target hardware.
- Reference or Conceptual Material: This type of material resides in an
appropriate reference manual. For example, system variables are
documented in the `Yocto Project Reference
Manual <&YOCTO_DOCS_REF_URL;>`__.
documented in the :doc`../ref-manual/ref-manual`.
- Detailed Public Information Not Specific to the Yocto Project: For
example, exhaustive information on how to use the Source Control
@@ -56,9 +54,8 @@ supplemental information is recommended for full comprehension. For
introductory information on the Yocto Project, see the
:yocto_home:`Yocto Project Website <>`. If you want to build an image with no
knowledge of Yocto Project as a way of quickly testing it out, see the
`Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document.
:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document.
For a comprehensive list of links and other documentation, see the
"`Links and Related
Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__"
":ref:`ref-manual/resources:links and related documentation`"
section in the Yocto Project Reference Manual.

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

@@ -50,8 +50,7 @@ available. Follow these general steps to run QEMU:
1. *Install QEMU:* QEMU is made available with the Yocto Project a
number of ways. One method is to install a Software Development Kit
(SDK). See "`The QEMU
Emulator <&YOCTO_DOCS_SDK_URL;#the-qemu-emulator>`__" section in the
(SDK). See ":ref:`sdk-manual/sdk-intro:the qemu emulator`" section in the
Yocto Project Application Development and the Extensible Software
Development Kit (eSDK) manual for information on how to install QEMU.
@@ -60,14 +59,18 @@ 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.
````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__): $ cd
~/poky $ source oe-init-build-env
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:
. ~/poky_sdk/environment-setup-core2-64-poky-linux
::
. ~/poky_sdk/environment-setup-core2-64-poky-linux
3. *Ensure the Artifacts are in Place:* You need to be sure you have a
pre-built kernel that will boot in QEMU. You also need the target
@@ -78,18 +81,21 @@ available. Follow these general steps to run QEMU:
your :term:`Build Directory`.
- If you have not built an image, you can go to the
`machines/qemu <&YOCTO_MACHINES_DL_URL;>`__ area and download a
:yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu/>` area and download a
pre-built image that matches your architecture and can be run on
QEMU.
See the "`Extracting the Root
Filesystem <&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem>`__"
See the ":ref:`sdk-manual/sdk-appendix-obtain:extracting the root filesystem`"
section in the Yocto Project Application Development and the
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: $
runqemu [option ] [...] Based on what you provide on the command
4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:
::
$ runqemu [option ] [...]
Based on what you provide on the command
line, ``runqemu`` does a good job of figuring out what you are trying
to do. For example, by default, QEMU looks for the most recently
built image according to the timestamp when it needs to look for an
@@ -113,30 +119,40 @@ available. Follow these general steps to run QEMU:
and uses the most recently built image according to the
timestamp.
$ runqemu qemux86-64
::
$ runqemu qemux86-64
- This example produces the exact same results as the previous
example. This command, however, specifically provides the image
and root filesystem type. $ runqemu qemux86-64 core-image-minimal
ext4
and root filesystem type.
::
$ runqemu qemux86-64 core-image-minimal ext4
- This example specifies to boot an initial RAM disk image and to
enable audio in QEMU. For this case, ``runqemu`` set the internal
variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
an appropriate driver must be installed (see the previous
description for the ``audio`` option for more information). $
runqemu qemux86-64 ramfs audio
description for the ``audio`` option for more information).
::
$ runqemu qemux86-64 ramfs audio
- This example does not provide enough information for QEMU to
launch. While the command does provide a root filesystem type, it
must also minimally provide a MACHINE, KERNEL, or VM option. $
runqemu ext4
must also minimally provide a MACHINE, KERNEL, or VM option.
::
$ runqemu ext4
- This example specifies to boot a virtual machine image
(``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
determines the QEMU architecture (MACHINE) to be "qemux86-64" and
the root filesystem type to be "vmdk". $ runqemu
/home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
the root filesystem type to be "vmdk".
::
$ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
Switching Between Consoles
==========================
@@ -191,15 +207,19 @@ using an NFS server.
The ``runqemu-extract-sdk`` takes a root filesystem tarball and
extracts it into a location that you specify. Here is an example that
takes a file system and extracts it to a directory named
``test-nfs``: runqemu-extract-sdk
./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2
test-nfs
``test-nfs``:
::
runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
2. *Start QEMU:* Once you have extracted the file system, you can run
``runqemu`` normally with the additional location of the file system.
You can then also make changes to the files within ``./test-nfs`` and
see those changes appear in the image in real time. Here is an
example using the ``qemux86`` image: runqemu qemux86-64 ./test-nfs
example using the ``qemux86`` image:
::
runqemu qemux86-64 ./test-nfs
.. note::
@@ -297,38 +317,57 @@ present, the toolchain is also automatically used.
QEMU Command-Line Syntax
========================
The basic ``runqemu`` command syntax is as follows: $ runqemu [option ]
[...] Based on what you provide on the command line, ``runqemu`` does a
The basic ``runqemu`` command syntax is as follows:
::
$ runqemu [option ] [...]
Based on what you provide on the command line, ``runqemu`` does a
good job of figuring out what you are trying to do. For example, by
default, QEMU looks for the most recently built image according to the
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: $
runqemu --help Usage: you can run this script with any valid combination
of the following environment variables (in any order): KERNEL - the
kernel image file to use ROOTFS - the rootfs image file or nfsroot
directory to use MACHINE - the machine name (optional, autodetected from
KERNEL filename if unspecified) Simplified QEMU command-line options can
be passed with: nographic - disable video console serial - enable a
serial console on /dev/ttyS0 slirp - enable user networking, no root
privileges is required kvm - enable KVM when running x86/x86_64
(VT-capable CPU required) kvm-vhost - enable KVM with vhost when running
x86/x86_64 (VT-capable CPU required) publicvnc - enable a VNC server
open to all hosts audio - enable audio [*/]ovmf\* - OVMF firmware file
or base name for booting with UEFI tcpserial=<port> - specify tcp serial
port number biosdir=<dir> - specify custom bios dir
biosfilename=<filename> - specify bios filename qemuparams=<xyz> -
specify custom parameters to QEMU bootparams=<xyz> - specify custom
kernel parameters during boot help, -h, --help: print this text
Examples: runqemu runqemu qemuarm runqemu tmp/deploy/images/qemuarm
runqemu tmp/deploy/images/qemux86/<qemuboot.conf> runqemu qemux86-64
core-image-sato ext4 runqemu qemux86-64 wic-image-minimal wic runqemu
path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial runqemu qemux86
iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... runqemu qemux86
qemuparams="-m 256" runqemu qemux86 bootparams="psplash=false" runqemu
path/to/<image>-<machine>.wic runqemu path/to/<image>-<machine>.wic.vmdk
Following is the command-line help output for the ``runqemu`` command:
::
$ runqemu --help
Usage: you can run this script with any valid combination
of the following environment variables (in any order):
KERNEL - the kernel image file to use
ROOTFS - the rootfs image file or nfsroot directory to use
MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
Simplified QEMU command-line options can be passed with:
nographic - disable video console
serial - enable a serial console on /dev/ttyS0
slirp - enable user networking, no root privileges is required
kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
publicvnc - enable a VNC server open to all hosts
audio - enable audio
[*/]ovmf* - OVMF firmware file or base name for booting with UEFI
tcpserial=<port> - specify tcp serial port number
biosdir=<dir> - specify custom bios dir
biosfilename=<filename> - specify bios filename
qemuparams=<xyz> - specify custom parameters to QEMU
bootparams=<xyz> - specify custom kernel parameters during boot
help, -h, --help: print this text
Examples:
runqemu
runqemu qemuarm
runqemu tmp/deploy/images/qemuarm
runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
runqemu qemux86-64 core-image-sato ext4
runqemu qemux86-64 wic-image-minimal wic
runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
runqemu qemux86 qemuparams="-m 256"
runqemu qemux86 bootparams="psplash=false"
runqemu path/to/<image>-<machine>.wic
runqemu path/to/<image>-<machine>.wic.vmdk
.. _qemu-dev-runqemu-command-line-options:

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

@@ -5,9 +5,9 @@ Setting Up to Use the Yocto Project
***********************************
This chapter provides guidance on how to prepare to use the Yocto
Project. You can learn about creating a team environment that develops
using the Yocto Project, how to set up a `build
host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, how to locate
Project. You can learn about creating a team environment to develop
using the Yocto Project, how to set up a :ref:`build
host <dev-manual/dev-manual-start:preparing the build host>`, how to locate
Yocto Project source repositories, and how to create local Git
repositories.
@@ -79,8 +79,9 @@ particular working environment and set of practices.
configuration files, classes, and so forth) and any software you are
developing under the control of an SCM system that is compatible
with the OpenEmbedded build system is advisable. Of all of the SCMs
supported by BitBake, the Yocto Project team strongly recommends
using `Git <&YOCTO_DOCS_OM_URL;#git>`__. Git is a distributed system
supported by BitBake, the Yocto Project team strongly recommends using
:ref:`overview-manual/overview-manual-development-environment:git`.
Git is a distributed system
that is easy to back up, allows you to work remotely, and then
connects back to the infrastructure.
@@ -171,8 +172,8 @@ particular working environment and set of practices.
- Highlights when commits break the build.
- Populates an `sstate
cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ from which
- Populates an :ref:`sstate
cache <overview-manual/overview-manual-concepts:shared state cache>` from which
developers can pull rather than requiring local builds.
- Allows commit hook triggers, which trigger builds when commits
@@ -226,20 +227,17 @@ particular working environment and set of practices.
some best practices exist within the Yocto Project development
environment. Consider the following:
- Use `Git <&YOCTO_DOCS_OM_URL;#git>`__ as the source control
- Use :ref:`overview-manual/overview-manual-development-environment:git` as the source control
system.
- Maintain your Metadata in layers that make sense for your
situation. See the "`The Yocto Project Layer
Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__"
situation. See the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`"
section in the Yocto Project Overview and Concepts Manual and the
"`Understanding and Creating
Layers <#understanding-and-creating-layers>`__" section for more
information on layers.
":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
section for more information on layers.
- Separate the project's Metadata and code by using separate Git
repositories. See the "`Yocto Project Source
Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__"
repositories. See the ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`"
section in the Yocto Project Overview and Concepts Manual for
information on these repositories. See the "`Locating Yocto
Project Source Files <#locating-yocto-project-source-files>`__"
@@ -258,15 +256,16 @@ particular working environment and set of practices.
- The Yocto Project community encourages you to send patches to the
project to fix bugs or add features. If you do submit patches,
follow the project commit guidelines for writing good commit
messages. See the "`Submitting a Change to the Yocto
Project <#how-to-submit-a-change>`__" section.
messages. See the
":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
section.
- Send changes to the core sooner than later as others are likely
to run into the same issues. For some guidance on mailing lists
to use, see the list in the "`Submitting a Change to the Yocto
Project <#how-to-submit-a-change>`__" section. For a description
of the available mailing lists, see the "`Mailing
Lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__" section in
to use, see the list in the
":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
section. For a description
of the available mailing lists, see the ":ref:`resources-mailinglist`" section in
the Yocto Project Reference Manual.
.. _dev-preparing-the-build-host:
@@ -275,7 +274,7 @@ Preparing the Build Host
========================
This section provides procedures to set up a system to be used as your
`build host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ for
:term:`Build Host` for
development using the Yocto Project. Your build host can be a native
Linux machine (recommended), it can be a machine (Linux, Mac, or
Windows) that uses `CROPS <https://github.com/crops/poky-container>`__,
@@ -297,15 +296,11 @@ are necessary depending on what you want to accomplish. See the
following references for information on how to prepare for Board Support
Package (BSP) development and kernel development:
- *BSP Development:* See the "`Preparing Your Build Host to Work With
BSP
Layers <&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers>`__"
- *BSP Development:* See the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
section in the Yocto Project Board Support Package (BSP) Developer's
Guide.
- *Kernel Development:* See the "`Preparing the Build Host to Work on
the
Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel>`__"
- *Kernel Development:* See the ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
section in the Yocto Project Linux Kernel Development Manual.
Setting Up a Native Linux Host
@@ -319,8 +314,8 @@ Project Build Host:
a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS
as these releases are frequently tested against the Yocto Project and
officially supported. For a list of the distributions under
validation and their status, see the "`Supported Linux
Distributions <&YOCTO_DOCS_REF_URL;#detailed-supported-distros>`__"
validation and their status, see the ":ref:`Supported Linux
Distributions <detailed-supported-distros>`"
section in the Yocto Project Reference Manual and the wiki page at
:yocto_wiki:`Distribution Support </wiki/Distribution_Support>`.
@@ -341,9 +336,8 @@ Project Build Host:
If your build host does not meet any of these three listed version
requirements, you can take steps to prepare the system so that you
can still use the Yocto Project. See the "`Required Git, tar, Python
and gcc
Versions <&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions>`__"
can still use the Yocto Project. See the
":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`"
section in the Yocto Project Reference Manual for information.
4. *Install Development Host Packages:* Required development host
@@ -351,23 +345,19 @@ Project Build Host:
with the Yocto Project. Collectively, the number of required packages
is large if you want to be able to cover all cases.
For lists of required packages for all scenarios, see the "`Required
Packages for the Build
Host <&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host>`__"
For lists of required packages for all scenarios, see the
":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
section in the Yocto Project Reference Manual.
Once you have completed the previous steps, you are ready to continue
using a given development path on your native Linux machine. If you are
going to use BitBake, see the "`Cloning the ``poky``
Repository <#cloning-the-poky-repository>`__" section. If you are going
to use the Extensible SDK, see the "`Using the Extensible
SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto
going to use BitBake, see the
":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
section. If you are going
to use the Extensible SDK, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
Project Application Development and the Extensible Software Development
Kit (eSDK) manual. If you want to work on the kernel, see the `Yocto
Project Linux Kernel Development
Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__. If you are going to use
Toaster, see the "`Setting Up and Using
Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__"
Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/kernel-dev`. If you are going to use
Toaster, see the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
section in the Toaster User Manual.
.. _setting-up-to-use-crops:
@@ -465,12 +455,11 @@ Once you have a container set up, everything is in place to develop just
as if you were running on a native Linux machine. If you are going to
use the Poky container, see the "`Cloning the ``poky``
Repository <#cloning-the-poky-repository>`__" section. If you are going
to use the Extensible SDK container, see the "`Using the Extensible
SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto
to use the Extensible SDK container, see the
":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
Project Application Development and the Extensible Software Development
Kit (eSDK) manual. If you are going to use the Toaster container, see
the "`Setting Up and Using
Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__"
the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
section in the Toaster User Manual.
.. _setting-up-to-use-wsl:
@@ -490,8 +479,14 @@ your Yocto Project build host:
1. *Make sure your Windows 10 machine is capable of running WSLv2:*
WSLv2 is only available for Windows 10 builds > 18917. To check which
build version you are running, you may open a command prompt on
Windows and execute the command "ver". C:\Users\myuser> ver Microsoft
Windows [Version 10.0.19041.153] If your build is capable of running
Windows and execute the command "ver".
::
C:\Users\myuser> ver
Microsoft Windows [Version 10.0.19041.153]
If your build is capable of running
WSLv2 you may continue, for more information on this subject or
instructions on how to upgrade to WSLv2 visit `Windows 10
WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__
@@ -507,8 +502,14 @@ your Yocto Project build host:
distribution.
3. *Check your Linux distribution is using WSLv2:* Open a Windows
PowerShell and run: C:\WINDOWS\system32> wsl -l -v NAME STATE VERSION
\*Ubuntu Running 2 Note the version column which says the WSL version
PowerShell and run:
::
C:\WINDOWS\system32> wsl -l -v
NAME STATE VERSION
*Ubuntu Running 2
Note the version column which says the WSL version
being used by your distribution, on compatible systems, this can be
changed back at any point in time.
@@ -529,25 +530,35 @@ 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: C:\WINDOWS\system32>
Get-AppxPackage -Name "*Ubuntu*" \| Select PackageFamilyName
PackageFamilyName -----------------
CanonicalGroupLimited.UbuntuonWindows_79abcdefgh You should now
Powershell as Administrator and run:
::
C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
PackageFamilyName
-----------------
CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
You should now
replace the PackageFamilyName and your user on the following path
to find your VHDX file:
``C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\``
For example: ls
C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\\
Mode LastWriteTime Length Name -a---- 3/14/2020 9:52 PM
57418973184 ext4.vhdx Your VHDX file path is:
::
ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
Mode LastWriteTime Length Name
-a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
Your VHDX file path is:
``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:
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 A progress bar should be shown while optimizing the
::
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
A progress bar should be shown while optimizing the
VHDX file, and storage should now be reflected correctly on the
Windows Explorer.
@@ -565,12 +576,10 @@ your Yocto Project build host:
Once you have WSLv2 set up, everything is in place to develop just as if
you were running on a native Linux machine. If you are going to use the
Extensible SDK container, see the "`Using the Extensible
SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto
Extensible SDK container, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
Project Application Development and the Extensible Software Development
Kit (eSDK) manual. If you are going to use the Toaster container, see
the "`Setting Up and Using
Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__"
the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
section in the Toaster User Manual.
Locating Yocto Project Source Files
@@ -582,19 +591,17 @@ files you'll need to work with the Yocto Project.
.. note::
- For concepts and introductory information about Git as it is used
in the Yocto Project, see the "`Git <&YOCTO_DOCS_OM_URL;#git>`__"
in the Yocto Project, see the ":ref:`overview-manual/overview-manual-development-environment:git`"
section in the Yocto Project Overview and Concepts Manual.
- For concepts on Yocto Project source repositories, see the "`Yocto
Project Source
Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__"
- For concepts on Yocto Project source repositories, see the
":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`"
section in the Yocto Project Overview and Concepts Manual."
Accessing Source Repositories
-----------------------------
Working from a copy of the upstream Yocto Project `Source
Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ is the
Working from a copy of the upstream :ref:`dev-manual/dev-manual-start:accessing source repositories` is the
preferred method for obtaining and using a Yocto Project release. You
can view the Yocto Project Source Repositories at
:yocto_git:`/`. In particular, you can find the ``poky``
@@ -611,8 +618,7 @@ Use the following procedure to locate the latest upstream copy of the
interested (e.g. ``poky``).
3. *Find the URL Used to Clone the Repository:* At the bottom of the
page, note the URL used to
`clone <&YOCTO_DOCS_OM_URL;#git-commands-clone>`__ that repository
page, note the URL used to clone that repository
(e.g. :yocto_git:`/git/poky`).
.. note::
@@ -658,9 +664,9 @@ Follow these steps to locate and download a particular tarball:
are interested (e.g. ``yocto``).
3. *Find the Tarball:* Drill down to find the associated tarball. For
example, click on ``yocto-DISTRO`` to view files associated with the
Yocto Project DISTRO release (e.g.
``poky-DISTRO_NAME_NO_CAP-POKYVERSION.tar.bz2``, which is the
example, click on ``yocto-&DISTRO;`` to view files associated with the
Yocto Project &DISTRO; release (e.g.
``&YOCTO_POKY;.tar.bz2``, which is the
released Poky tarball).
4. *Download the Tarball:* Click the tarball to download and save a
@@ -691,8 +697,7 @@ Releases <#accessing-index-of-releases>`__" section.
3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to
display and choose a recent or past supported Yocto Project release
(e.g. DISTRO_NAME_NO_CAP, DISTRO_NAME_NO_CAP_MINUS_ONE, and so
forth).
(e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
.. note::
@@ -711,7 +716,7 @@ Accessing Nightly Builds
------------------------
Yocto Project maintains an area for nightly builds that contains tarball
releases at ` <&YOCTO_AB_NIGHTLY_URL;>`__. These builds include Yocto
releases at https://autobuilder.yocto.io//pub/nightly/. These builds include Yocto
Project releases ("poky"), toolchains, and builds for supported
machines.
@@ -719,7 +724,7 @@ Should you ever want to access a nightly build of a particular Yocto
Project component, use the following procedure:
1. *Locate the Index of Nightly Builds:* Open a browser and go to
` <&YOCTO_AB_NIGHTLY_URL;>`__ to access the Nightly Builds.
https://autobuilder.yocto.io//pub/nightly/ to access the Nightly Builds.
2. *Select a Date:* Click on the date in which you are interested. If
you want the latest builds, use "CURRENT".
@@ -739,11 +744,10 @@ Cloning and Checking Out Branches
To use the Yocto Project for development, you need a release locally
installed on your development system. This locally installed set of
files is referred to as the :term:`Source Directory`
in the Yocto
Project documentation.
in the Yocto Project documentation.
The preferred method of creating your Source Directory is by using
`Git <&YOCTO_DOCS_OM_URL;#git>`__ to clone a local copy of the upstream
:ref:`overview-manual/overview-manual-development-environment:git` to clone a local copy of the upstream
``poky`` repository. Working from a cloned copy of the upstream
repository allows you to contribute back into the Yocto Project or to
simply work with the latest software on a development branch. Because
@@ -756,19 +760,26 @@ Cloning the ``poky`` Repository
-------------------------------
Follow these steps to create a local version of the upstream
```poky`` <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository.
:term:`Poky` Git repository.
1. *Set Your Directory:* Change your working directory to where you want
to create your local copy of ``poky``.
2. *Clone the Repository:* The following example command clones the
``poky`` repository and uses the default name "poky" for your local
repository: $ git clone git://git.yoctoproject.org/poky Cloning into
'poky'... remote: Counting objects: 432160, done. remote: Compressing
objects: 100% (102056/102056), done. remote: Total 432160 (delta
323116), reused 432037 (delta 323000) Receiving objects: 100%
(432160/432160), 153.81 MiB \| 8.54 MiB/s, done. Resolving deltas:
100% (323116/323116), done. Checking connectivity... done. Unless you
repository:
::
$ git clone git://git.yoctoproject.org/poky
Cloning into 'poky'...
remote: Counting objects: 432160, done.
remote: Compressing objects: 100% (102056/102056), done.
remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
Resolving deltas: 100% (323116/323116), done.
Checking connectivity... done.
Unless you
specify a specific development branch or tag name, Git clones the
"master" branch, which results in a snapshot of the latest
development changes for "master". For information on how to check out
@@ -779,13 +790,21 @@ 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: $ cd ~/poky
$ git status On branch master Your branch is up-to-date with
'origin/master'. nothing to commit, working directory clean $ git
branch \* master Your local repository of poky is identical to the
exists on your system and by default, it is checked out:
::
$ cd ~/poky
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
$ git branch
* master
Your local repository of poky is identical to the
upstream poky repository at the time from which it was cloned. As you
work with the local branch, you can periodically use the
``git pull DASHDASHrebase`` command to be sure you are up-to-date
``git pull --rebase`` command to be sure you are up-to-date
with the upstream branch.
Checking Out by Branch in Poky
@@ -809,28 +828,48 @@ and then specifically check out that development branch.
copy of poky, see the "`Cloning the ``poky``
Repository <#cloning-the-poky-repository>`__" section.
2. *Determine Existing Branch Names:* $ git branch -a \* master
remotes/origin/1.1_M1 remotes/origin/1.1_M2 remotes/origin/1.1_M3
remotes/origin/1.1_M4 remotes/origin/1.2_M1 remotes/origin/1.2_M2
remotes/origin/1.2_M3 . . . remotes/origin/thud
remotes/origin/thud-next remotes/origin/warrior
remotes/origin/warrior-next remotes/origin/zeus
remotes/origin/zeus-next ... and so on ...
2. *Determine Existing Branch Names:*
::
$ git branch -a
* master
remotes/origin/1.1_M1
remotes/origin/1.1_M2
remotes/origin/1.1_M3
remotes/origin/1.1_M4
remotes/origin/1.2_M1
remotes/origin/1.2_M2
remotes/origin/1.2_M3
. . .
remotes/origin/thud
remotes/origin/thud-next
remotes/origin/warrior
remotes/origin/warrior-next
remotes/origin/zeus
remotes/origin/zeus-next
... and so on ...
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: $ 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. Switched to a new branch 'DISTRO_NAME_NO_CAP' The
previous command checks out the "DISTRO_NAME_NO_CAP" development
&DISTRO; Release (&DISTRO_NAME;), use the following command:
::
$ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
Switched to a new branch '&DISTRO_NAME;'
The previous command checks out the "&DISTRO_NAME;" development
branch and reports that the branch is tracking the upstream
"origin/DISTRO_NAME_NO_CAP" branch.
"origin/&DISTRO_NAME;" 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: $ git branch master \*
DISTRO_NAME_NO_CAP
that is currently checked out for work:
::
$ git branch
master *
&DISTRO_NAME;
.. _checkout-out-by-tag-in-poky:
@@ -854,20 +893,48 @@ similar to checking out by branch name except you use tag names.
Repository <#cloning-the-poky-repository>`__" 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: $ git
fetch --tags $
you need to fetch the upstream tags into your local repository:
::
3. *List the Tag Names:* You can list the tag names now: $ git tag
1.1_M1.final 1.1_M1.rc1 1.1_M1.rc2 1.1_M2.final 1.1_M2.rc1 . . .
yocto-2.5 yocto-2.5.1 yocto-2.5.2 yocto-2.5.3 yocto-2.6 yocto-2.6.1
yocto-2.6.2 yocto-2.7 yocto_1.5_M5.rc8
$ git fetch --tags
$
4. *Check out the Branch:* $ git checkout tags/DISTRO_REL_TAG -b
my_yocto_DISTRO Switched to a new branch 'my_yocto_DISTRO' $ git
branch master \* my_yocto_DISTRO The previous command creates and
checks out a local branch named "my_yocto_DISTRO", which is based on
3. *List the Tag Names:* You can list the tag names now:
::
$ git tag
1.1_M1.final
1.1_M1.rc1
1.1_M1.rc2
1.1_M2.final
1.1_M2.rc1
.
.
.
yocto-2.5
yocto-2.5.1
yocto-2.5.2
yocto-2.5.3
yocto-2.6
yocto-2.6.1
yocto-2.6.2
yocto-2.7
yocto_1.5_M5.rc8
4. *Check out the Branch:*
::
$ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO;
Switched to a new branch 'my_yocto_&DISTRO;'
$ git branch
master
* my_yocto_&DISTRO;
The previous command creates and
checks out a local branch named "my_yocto_&DISTRO;", which is based on
the commit in the upstream poky repository that has the same tag. In
this example, the files you have available locally as a result of the
``checkout`` command are a snapshot of the "DISTRO_NAME_NO_CAP"
development branch at the point where Yocto Project DISTRO was
``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;"
development branch at the point where Yocto Project &DISTRO; was
released.