Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/dev-manual/dev-manual-start.xml b/poky/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 0000000..9ff9ac4
--- /dev/null
+++ b/poky/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,1288 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='dev-manual-start'>
+
+<title>Setting Up to Use the Yocto Project</title>
+
+<para>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>,
+ how to locate Yocto Project source repositories, and how to create local
+ Git repositories.
+</para>
+
+<section id="usingpoky-changes-collaborate">
+ <title>Creating a Team Development Environment</title>
+
+ <para>
+ It might not be immediately clear how you can use the Yocto
+ Project in a team development environment, or how to scale it for a
+ large team of developers.
+ You can adapt the Yocto Project to many different use cases and
+ scenarios;
+ however, this flexibility could cause difficulties if you are trying
+ to create a working setup that scales effectively.
+ </para>
+
+ <para>
+ To help you understand how to set up this type of environment,
+ this section presents a procedure that gives you information
+ that can help you get the results you want.
+ The procedure is high-level and presents some of the project's most
+ successful experiences, practices, solutions, and available
+ technologies that have proved to work well in the past;
+ however, keep in mind, the procedure here is simply a starting point.
+ You can build off these steps and customize the procedure to fit any
+ particular working environment and set of practices.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Determine Who is Going to be Developing:</emphasis>
+ You first need to understand who is going to be doing anything
+ related to the Yocto Project and determine their roles.
+ Making this determination is essential to completing
+ subsequent steps, which are to get your equipment together
+ and set up your development environment's hardware topology.
+ </para>
+
+ <para>The following roles exist:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Application Developer:</emphasis>
+ This type of developer does application level work
+ on top of an existing software stack.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Core System Developer:</emphasis>
+ This type of developer works on the contents of the
+ operating system image itself.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build Engineer:</emphasis>
+ This type of developer manages Autobuilders and
+ releases. Depending on the specifics of the environment,
+ not all situations might need a Build Engineer.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Test Engineer:</emphasis>
+ This type of developer creates and manages automated
+ tests that are used to ensure all application and
+ core system development meets desired quality
+ standards.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Gather the Hardware:</emphasis>
+ Based on the size and make-up of the team, get the hardware
+ together.
+ Ideally, any development, build, or test engineer uses
+ a system that runs a supported Linux distribution.
+ These systems, in general, should be high performance
+ (e.g. dual, six-core Xeons with 24 Gbytes of RAM and plenty
+ of disk space).
+ You can help ensure efficiency by having any machines used
+ for testing or that run Autobuilders be as high performance
+ as possible.
+ <note>
+ Given sufficient processing power, you might also consider
+ building Yocto Project development containers to be run
+ under Docker, which is described later.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
+ Once you understand the hardware involved and the make-up
+ of the team, you can understand the hardware topology of the
+ development environment.
+ You can get a visual idea of the machines and their roles
+ across the development environment.
+
+<!--
+ The following figure shows a moderately sized Yocto Project
+ development environment.
+
+ <para role="writernotes">
+ Need figure.</para>
+-->
+
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
+ Keeping your
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ (i.e. recipes, 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
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
+ Git is a distributed system that is easy to back up,
+ allows you to work remotely, and then connects back to the
+ infrastructure.
+ <note>
+ For information about BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </note></para>
+
+ <para>It is relatively easy to set up Git services and create
+ infrastructure like
+ <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
+ which is based on server software called
+ <filename>gitolite</filename> with <filename>cgit</filename>
+ being used to generate the web interface that lets you view the
+ repositories.
+ The <filename>gitolite</filename> software identifies users
+ using SSH keys and allows branch-based access controls to
+ repositories that you can control as little or as much as
+ necessary.
+ <note>
+ The setup of these services is beyond the scope of this
+ manual.
+ However, sites such as the following exist that describe
+ how to perform setup:
+ <itemizedlist>
+ <listitem><para>
+ <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
+ Describes how to install
+ <filename>gitolite</filename> on the server.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='http://gitolite.com'>Gitolite</ulink>:
+ Information for <filename>gitolite</filename>.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
+ Documentation on how to create interfaces and
+ frontends for Git.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up the Application Development Machines:</emphasis>
+ As mentioned earlier, application developers are creating
+ applications on top of existing software stacks.
+ Following are some best practices for setting up machines
+ used for application development:
+ <itemizedlist>
+ <listitem><para>
+ Use a pre-built toolchain that contains the software
+ stack itself.
+ Then, develop the application code on top of the
+ stack.
+ This method works well for small numbers of relatively
+ isolated applications.
+ </para></listitem>
+ <listitem><para>
+ Keep your cross-development toolchains updated.
+ You can do this through provisioning either as new
+ toolchain downloads or as updates through a package
+ update mechanism using <filename>opkg</filename>
+ to provide updates to an existing toolchain.
+ The exact mechanics of how and when to do this depend
+ on local policy.
+ </para></listitem>
+ <listitem><para>
+ Use multiple toolchains installed locally into
+ different locations to allow development across
+ versions.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up the Core Development Machines:</emphasis>
+ As mentioned earlier, core developers work on the contents of
+ the operating system itself.
+ Following are some best practices for setting up machines
+ used for developing images:
+ <itemizedlist>
+ <listitem><para>
+ Have the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ available on the developer workstations so developers
+ can run their own builds and directly rebuild the
+ software stack.
+ </para></listitem>
+ <listitem><para>
+ Keep the core system unchanged as much as
+ possible and do your work in layers on top of the
+ core system.
+ Doing so gives you a greater level of portability when
+ upgrading to new versions of the core system or Board
+ Support Packages (BSPs).
+ </para></listitem>
+ <listitem><para>
+ Share layers amongst the developers of a
+ particular project and contain the policy configuration
+ that defines the project.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up an Autobuilder:</emphasis>
+ Autobuilders are often the core of the development
+ environment.
+ It is here that changes from individual developers are brought
+ together and centrally tested.
+ Based on this automated build and test environment, subsequent
+ decisions about releases can be made.
+ Autobuilders also allow for "continuous integration" style
+ testing of software components and regression identification
+ and tracking.</para>
+
+ <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
+ for more information and links to buildbot.
+ The Yocto Project team has found this implementation
+ works well in this role.
+ A public example of this is the Yocto Project
+ Autobuilders, which the Yocto Project team uses to test the
+ overall health of the project.</para>
+
+ <para>The features of this system are:
+ <itemizedlist>
+ <listitem><para>
+ Highlights when commits break the build.
+ </para></listitem>
+ <listitem><para>
+ Populates an
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate cache</ulink>
+ from which developers can pull rather than requiring
+ local builds.
+ </para></listitem>
+ <listitem><para>
+ Allows commit hook triggers, which trigger builds when
+ commits are made.
+ </para></listitem>
+ <listitem><para>
+ Allows triggering of automated image booting
+ and testing under the QuickEMUlator (QEMU).
+ </para></listitem>
+ <listitem><para>
+ Supports incremental build testing and
+ from-scratch builds.
+ </para></listitem>
+ <listitem><para>
+ Shares output that allows developer
+ testing and historical regression investigation.
+ </para></listitem>
+ <listitem><para>
+ Creates output that can be used for releases.
+ </para></listitem>
+ <listitem><para>
+ Allows scheduling of builds so that resources
+ can be used efficiently.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up Test Machines:</emphasis>
+ Use a small number of shared, high performance systems
+ for testing purposes.
+ Developers can use these systems for wider, more
+ extensive testing while they continue to develop
+ locally using their primary development system.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Document Policies and Change Flow:</emphasis>
+ The Yocto Project uses a hierarchical structure and a
+ pull model.
+ Scripts exist to create and send pull requests
+ (i.e. <filename>create-pull-request</filename> and
+ <filename>send-pull-request</filename>).
+ This model is in line with other open source projects where
+ maintainers are responsible for specific areas of the project
+ and a single maintainer handles the final "top-of-tree" merges.
+ <note>
+ You can also use a more collective push model.
+ The <filename>gitolite</filename> software supports both the
+ push and pull models quite easily.
+ </note></para>
+
+ <para>As with any development environment, it is important
+ to document the policy used as well as any main project
+ guidelines so they are understood by everyone.
+ It is also a good idea to have well-structured
+ commit messages, which are usually a part of a project's
+ guidelines.
+ Good commit messages are essential when looking back in time and
+ trying to understand why changes were made.</para>
+
+ <para>If you discover that changes are needed to the core
+ layer of the project, it is worth sharing those with the
+ community as soon as possible.
+ Chances are if you have discovered the need for changes,
+ someone else in the community needs them also.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Development Environment Summary:</emphasis>
+ Aside from the previous steps, some best practices exist
+ within the Yocto Project development environment.
+ Consider the following:
+ <itemizedlist>
+ <listitem><para>
+ Use
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
+ as the source control system.
+ </para></listitem>
+ <listitem><para>
+ Maintain your Metadata in layers that make sense
+ for your situation.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual and the
+ "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
+ section for more information on layers.
+ </para></listitem>
+ <listitem><para>
+ Separate the project's Metadata and code by using
+ separate Git repositories.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual for information on these repositories.
+ See the
+ "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
+ section for information on how to set up local Git
+ repositories for related upstream Yocto Project
+ Git repositories.
+ </para></listitem>
+ <listitem><para>
+ Set up the directory for the shared state cache
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
+ where it makes sense.
+ For example, set up the sstate cache on a system used
+ by developers in the same organization and share the
+ same source directories on their machines.
+ </para></listitem>
+ <listitem><para>
+ Set up an Autobuilder and have it populate the
+ sstate cache and source directories.
+ </para></listitem>
+ <listitem><para>
+ 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 "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ 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
+ "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+ section.
+ For a description of the available mailing lists, see
+ the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </orderedlist>
+ </para>
+</section>
+
+<section id='dev-preparing-the-build-host'>
+ <title>Preparing the Build Host</title>
+
+ <para>
+ This section provides procedures to set up a system to be used as your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+ 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
+ <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
+ which leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink> or it can
+ be a Windows machine capable of running Windows Subsystem For Linux v2 (WSL).
+ <note>
+ The Yocto Project is not compatible with
+ <ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux v1</ulink>.
+ It is compatible but not officially supported nor validated with WSLv2.
+ If you still decide to use WSL please upgrade to
+ <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>WSLv2</ulink>.
+ </note>
+ </para>
+
+ <para>
+ Once your build host is set up to use the Yocto Project,
+ further steps 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:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>BSP Development:</emphasis>
+ See the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work With BSP Layers</ulink>"
+ section in the Yocto Project Board Support Package (BSP)
+ Developer's Guide.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Kernel Development:</emphasis>
+ See the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel'>Preparing the Build Host to Work on the Kernel</ulink>"
+ section in the Yocto Project Linux Kernel Development Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <section id='setting-up-a-native-linux-host'>
+ <title>Setting Up a Native Linux Host</title>
+
+ <para>
+ Follow these steps to prepare a native Linux machine as your
+ Yocto Project Build Host:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Use a Supported Linux Distribution:</emphasis>
+ You should have a reasonably current Linux-based host
+ system.
+ You will have the best results with 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
+ "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
+ in the Yocto Project Reference Manual and the wiki page at
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Have Enough Free Memory:</emphasis>
+ Your system should have at least 50 Gbytes of free disk
+ space for building images.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Meet Minimal Version Requirements:</emphasis>
+ The OpenEmbedded build system should be able to run on any
+ modern distribution that has the following versions for
+ Git, tar, Python and gcc.
+ <itemizedlist>
+ <listitem><para>
+ Git 1.8.3.1 or greater
+ </para></listitem>
+ <listitem><para>
+ tar 1.28 or greater
+ </para></listitem>
+ <listitem><para>
+ Python 3.5.0 or greater.
+ </para></listitem>
+ <listitem><para>
+ gcc 5.0 or greater.
+ </para></listitem>
+ </itemizedlist>
+ 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
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</ulink>"
+ section in the Yocto Project Reference Manual for
+ information.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Install Development Host Packages:</emphasis>
+ Required development host packages vary depending on your
+ build host and what you want to do with the Yocto
+ Project.
+ Collectively, the number of required packages is large
+ if you want to be able to cover all cases.</para>
+
+ <para>For lists of required packages for all scenarios,
+ see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para></listitem>
+ </orderedlist>
+ 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
+ "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+ section.
+ If you are going to use the Extensible SDK, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+ 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
+ <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
+ If you are going to use Toaster, see the
+ "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+ section in the Toaster User Manual.
+ </para>
+ </section>
+
+ <section id='setting-up-to-use-crops'>
+ <title>Setting Up to Use CROss PlatformS (CROPS)</title>
+
+ <para>
+ With
+ <ulink url='https://github.com/crops/poky-container'>CROPS</ulink>,
+ which leverages
+ <ulink url='https://www.docker.com/'>Docker Containers</ulink>,
+ you can create a Yocto Project development environment that
+ is operating system agnostic.
+ You can set up a container in which you can develop using the
+ Yocto Project on a Windows, Mac, or Linux machine.
+ </para>
+
+ <para>
+ Follow these general steps to prepare a Windows, Mac, or Linux
+ machine as your Yocto Project build host:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Determine What Your Build Host Needs:</emphasis>
+ <ulink url='https://www.docker.com/what-docker'>Docker</ulink>
+ is a software container platform that you need to install
+ on the build host.
+ Depending on your build host, you might have to install
+ different software to support Docker containers.
+ Go to the Docker installation page and read about the
+ platform requirements in
+ "<ulink url='https://docs.docker.com/install/#supported-platforms'>Supported Platforms</ulink>"
+ your build host needs to run containers.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Choose What To Install:</emphasis>
+ Depending on whether or not your build host meets system
+ requirements, you need to install "Docker CE Stable" or
+ the "Docker Toolbox".
+ Most situations call for Docker CE.
+ However, if you have a build host that does not meet
+ requirements (e.g. Pre-Windows 10 or Windows 10 "Home"
+ version), you must install Docker Toolbox instead.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Go to the Install Site for Your Platform:</emphasis>
+ Click the link for the Docker edition associated with
+ your build host's native software.
+ For example, if your build host is running Microsoft
+ Windows Version 10 and you want the Docker CE Stable
+ edition, click that link under "Supported Platforms".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Install the Software:</emphasis>
+ Once you have understood all the pre-requisites, you can
+ download and install the appropriate software.
+ Follow the instructions for your specific machine and
+ the type of the software you need to install:
+ <itemizedlist>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/docker-for-windows/install/#install-docker-for-windows-desktop-app'>Docker CE for Windows</ulink>
+ for Windows build hosts that meet requirements.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/docker-for-mac/install/#install-and-run-docker-for-mac'>Docker CE for Macs</ulink>
+ for Mac build hosts that meet requirements.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/toolbox/toolbox_install_windows/'>Docker Toolbox for Windows</ulink>
+ for Windows build hosts that do not meet Docker
+ requirements.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/toolbox/toolbox_install_mac/'>Docker Toolbox for MacOS</ulink>
+ for Mac build hosts that do not meet Docker
+ requirements.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/install/linux/docker-ce/centos/'>Docker CE for CentOS</ulink>
+ for Linux build hosts running the CentOS
+ distribution.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/install/linux/docker-ce/debian/'>Docker CE for Debian</ulink>
+ for Linux build hosts running the Debian
+ distribution.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/install/linux/docker-ce/fedora/'>Docker CE for Fedora</ulink>
+ for Linux build hosts running the Fedora
+ distribution.
+ </para></listitem>
+ <listitem><para>
+ Install
+ <ulink url='https://docs.docker.com/install/linux/docker-ce/ubuntu/'>Docker CE for Ubuntu</ulink>
+ for Linux build hosts running the Ubuntu
+ distribution.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Orient Yourself With Docker:</emphasis>
+ If you are unfamiliar with Docker and the container
+ concept, you can learn more here -
+ <ulink url='https://docs.docker.com/get-started/'></ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch Docker or Docker Toolbox:</emphasis>
+ You should be able to launch Docker or the Docker Toolbox
+ and have a terminal shell on your development host.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set Up the Containers to Use the Yocto Project:</emphasis>
+ Go to
+ <ulink url='https://github.com/crops/docker-win-mac-docs/wiki'></ulink>
+ and follow the directions for your particular
+ build host (i.e. Linux, Mac, or Windows).</para>
+
+ <para>Once you complete the setup instructions for your
+ machine, you have the Poky, Extensible SDK, and Toaster
+ containers available.
+ You can click those links from the page and learn more
+ about using each of those containers.
+ </para></listitem>
+ </orderedlist>
+ 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
+ "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+ section.
+ If you are going to use the Extensible SDK container, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+ 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
+ "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+ section in the Toaster User Manual.
+ </para>
+ </section>
+
+ <section id='setting-up-to-use-wsl'>
+ <title>Setting Up to Use Windows Subsystem For Linux (WSLv2)</title>
+
+ <para>
+ With <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'>
+ Windows Subsystem for Linux (WSLv2)</ulink>, you can create a
+ Yocto Project development environment that allows you to build
+ on Windows. You can set up a Linux distribution inside Windows
+ in which you can develop using the Yocto Project.
+ </para>
+
+ <para>
+ Follow these general steps to prepare a Windows machine using WSLv2
+ as your Yocto Project build host:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Make sure your Windows 10 machine is capable of running WSLv2:</emphasis>
+
+ 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".
+ <literallayout class='monospaced'>
+ C:\Users\myuser> ver
+
+ Microsoft Windows [Version 10.0.19041.153]
+ </literallayout>
+ 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 <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-install'>Windows 10 WSLv2</ulink>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Install the Linux distribution of your choice inside Windows 10:</emphasis>
+ Once you know your version of Windows 10 supports WSLv2,
+ you can install the distribution of your choice from the
+ Microsoft Store.
+ Open the Microsoft Store and search for Linux. While there
+ are several Linux distributions available, the assumption
+ is that your pick will be one of the distributions supported
+ by the Yocto Project as stated on the instructions for
+ using a native Linux host.
+ After making your selection, simply click "Get" to download
+ and install the distribution.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Check your Linux distribution is using WSLv2:</emphasis>
+ Open a Windows PowerShell and run:
+ <literallayout class='monospaced'>
+ C:\WINDOWS\system32> wsl -l -v
+ NAME STATE VERSION
+ *Ubuntu Running 2
+ </literallayout>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Orient Yourself on WSL:</emphasis>
+ If you are unfamiliar with WSL, you can learn more here -
+ <ulink url='https://docs.microsoft.com/en-us/windows/wsl/wsl2-about'></ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch your WSL Distibution:</emphasis>
+ From the Windows start menu simply launch your WSL distribution
+ just like any other application.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optimize your WSLv2 storage often:</emphasis>
+ Due to the way storage is handled on WSLv2, the storage
+ space used by the undelying Linux distribution is not
+ reflected immedately, and since bitbake heavily uses
+ storage, after several builds, you may be unaware you
+ are running out of space. WSLv2 uses a VHDX file for
+ storage, this issue can be easily avoided by manually
+ optimizing this file often, this can be done in the
+ following way:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Find the location of your VHDX file:</emphasis>
+ First you need to find the distro app package directory,
+ to achieve this open a Windows Powershell as Administrator
+ and run:
+ <literallayout class='monospaced'>
+ C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
+ PackageFamilyName
+ -----------------
+ CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
+ </literallayout>
+ You should now replace the <replaceable>PackageFamilyName</replaceable>
+ and your <replaceable>user</replaceable> on the following
+ path to find your VHDX file: <filename>C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\</filename>
+ For example:
+ <literallayout class='monospaced'>
+ 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
+ </literallayout>
+ Your VHDX file path is: <filename>C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx</filename>
+ </para></listitem>
+ <listitem><para><emphasis>Optimize your VHDX file:</emphasis>
+ Open a Windows Powershell as Administrator to optimize
+ your VHDX file, shutting down WSL first:
+ <literallayout class='monospaced'>
+ 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
+ </literallayout>
+ A progress bar should be shown while optimizing the VHDX file,
+ and storage should now be reflected correctly on the Windows
+ Explorer.
+ </para></listitem>
+ </orderedlist>
+ </para></listitem>
+ </orderedlist>
+ <note>
+ The current implementation of WSLv2 does not have out-of-the-box
+ access to external devices such as those connected through a
+ USB port, but it automatically mounts your <filename>C:</filename>
+ drive on <filename>/mnt/c/</filename> (and others), which
+ you can use to share deploy artifacts to be later flashed on
+ hardware through Windows, but your build directory should not
+ reside inside this mountpoint.
+ </note>
+ 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
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
+ 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
+ "<ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use'>Setting Up and Using Toaster</ulink>"
+ section in the Toaster User Manual.
+ </para>
+ </section>
+</section>
+
+<section id='locating-yocto-project-source-files'>
+ <title>Locating Yocto Project Source Files</title>
+
+ <para>
+ This section shows you how to locate, fetch and configure the source
+ files you'll need to work with the Yocto Project.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ For concepts and introductory information about Git as it
+ is used in the Yocto Project, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para></listitem>
+ <listitem><para>
+ For concepts on Yocto Project source repositories, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+ section in the Yocto Project Overview and Concepts Manual."
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <section id='accessing-source-repositories'>
+ <title>Accessing Source Repositories</title>
+
+ <para>
+ Working from a copy of the upstream Yocto Project
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
+ is the preferred method for obtaining and using a Yocto Project
+ release.
+ You can view the Yocto Project Source Repositories at
+ <ulink url='&YOCTO_GIT_URL;'></ulink>.
+ In particular, you can find the
+ <filename>poky</filename> repository at
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
+ </para>
+
+ <para>
+ Use the following procedure to locate the latest upstream copy of
+ the <filename>poky</filename> Git repository:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Access Repositories:</emphasis>
+ Open a browser and go to
+ <ulink url='&YOCTO_GIT_URL;'></ulink> to access the
+ GUI-based interface into the Yocto Project source
+ repositories.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select the Repository:</emphasis>
+ Click on the repository in which you are interested (e.g.
+ <filename>poky</filename>).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Find the URL Used to Clone the Repository:</emphasis>
+ At the bottom of the page, note the URL used to
+ <ulink url='&YOCTO_DOCS_OM_URL;#git-commands-clone'>clone</ulink>
+ that repository (e.g.
+ <filename>&YOCTO_GIT_URL;/poky</filename>).
+ <note>
+ For information on cloning a repository, see the
+ "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+ section.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='accessing-index-of-releases'>
+ <title>Accessing Index of Releases</title>
+
+ <para>
+ Yocto Project maintains an Index of Releases area that contains
+ related files that contribute to the Yocto Project.
+ Rather than Git repositories, these files are tarballs that
+ represent snapshots in time of a given component.
+ <note><title>Tip</title>
+ The recommended method for accessing Yocto Project
+ components is to use Git to clone the upstream repository and
+ work from within that locally cloned repository.
+ The procedure in this section exists should you desire a
+ tarball snapshot of any given component.
+ </note>
+ Follow these steps to locate and download a particular tarball:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Access the Index of Releases:</emphasis>
+ Open a browser and go to
+ <ulink url='&YOCTO_DL_URL;/releases'></ulink> to access the
+ Index of Releases.
+ The list represents released components (e.g.
+ <filename>bitbake</filename>,
+ <filename>sato</filename>, and so on).
+ <note>
+ The <filename>yocto</filename> directory contains the
+ full array of released Poky tarballs.
+ The <filename>poky</filename> directory in the
+ Index of Releases was historically used for very
+ early releases and exists now only for retroactive
+ completeness.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select a Component:</emphasis>
+ Click on any released component in which you are interested
+ (e.g. <filename>yocto</filename>).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Find the Tarball:</emphasis>
+ Drill down to find the associated tarball.
+ For example, click on <filename>yocto-&DISTRO;</filename> to
+ view files associated with the Yocto Project &DISTRO;
+ release (e.g. <filename>poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;.tar.bz2</filename>,
+ which is the released Poky tarball).
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download the Tarball:</emphasis>
+ Click the tarball to download and save a snapshot of the
+ given component.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='using-the-downloads-page'>
+ <title>Using the Downloads Page</title>
+
+ <para>
+ The
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+ uses a "DOWNLOADS" page from which you can locate and download
+ tarballs of any Yocto Project release.
+ Rather than Git repositories, these files represent snapshot
+ tarballs similar to the tarballs located in the Index of Releases
+ described in the
+ "<link linkend='accessing-index-of-releases'>Accessing Index of Releases</link>"
+ section.
+ <note><title>Tip</title>
+ The recommended method for accessing Yocto Project
+ components is to use Git to clone a repository and work from
+ within that local repository.
+ The procedure in this section exists should you desire a
+ tarball snapshot of any given component.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Go to the Yocto Project Website:</emphasis>
+ Open The
+ <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+ in your browser.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Get to the Downloads Area:</emphasis>
+ Select the "DOWNLOADS" item from the pull-down
+ "SOFTWARE" tab menu near the top of the page.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select a Yocto Project Release:</emphasis>
+ 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).
+ <note><title>Tip</title>
+ For a "map" of Yocto Project releases to version
+ numbers, see the
+ <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Releases</ulink>
+ wiki page.
+ </note>
+ You can use the "RELEASE ARCHIVE" link to reveal a menu of
+ all Yocto Project releases.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download Tools or Board Support Packages (BSPs):</emphasis>
+ From the "DOWNLOADS" page, you can download tools or
+ BSPs as well.
+ Just scroll down the page and look for what you need.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='accessing-nightly-builds'>
+ <title>Accessing Nightly Builds</title>
+
+ <para>
+ Yocto Project maintains an area for nightly builds that contains
+ tarball releases at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>.
+ These builds include Yocto Project releases ("poky"),
+ toolchains, and builds for supported machines.
+ </para>
+
+ <para>
+ Should you ever want to access a nightly build of a particular
+ Yocto Project component, use the following procedure:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Locate the Index of Nightly Builds:</emphasis>
+ Open a browser and go to
+ <ulink url='&YOCTO_AB_NIGHTLY_URL;'/> to access the
+ Nightly Builds.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select a Date:</emphasis>
+ Click on the date in which you are interested.
+ If you want the latest builds, use "CURRENT".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select a Build:</emphasis>
+ Choose the area in which you are interested.
+ For example, if you are looking for the most recent
+ toolchains, select the "toolchain" link.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Find the Tarball:</emphasis>
+ Drill down to find the associated tarball.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download the Tarball:</emphasis>
+ Click the tarball to download and save a snapshot of the
+ given component.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+</section>
+
+<section id='cloning-and-checking-out-branches'>
+ <title>Cloning and Checking Out Branches</title>
+
+ <para>
+ 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
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ in the Yocto Project documentation.
+ </para>
+
+ <para>
+ The preferred method of creating your Source Directory is by using
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local
+ copy of the upstream <filename>poky</filename> 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 Git maintains and creates an upstream repository with
+ a complete history of changes and you are working with a local
+ clone of that repository, you have access to all the Yocto
+ Project development branches and tag names used in the upstream
+ repository.
+ </para>
+
+ <section id='cloning-the-poky-repository'>
+ <title>Cloning the <filename>poky</filename> Repository</title>
+
+ <para>
+ Follow these steps to create a local version of the
+ upstream
+ <ulink url='&YOCTO_DOCS_REF_URL;#poky'><filename>poky</filename></ulink>
+ Git repository.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set Your Directory:</emphasis>
+ Change your working directory to where you want to
+ create your local copy of
+ <filename>poky</filename>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the Repository:</emphasis>
+ The following example command clones the
+ <filename>poky</filename> repository and uses
+ the default name "poky" for your local repository:
+ <literallayout class='monospaced'>
+ $ 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.
+ </literallayout>
+ 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 a specific
+ development branch or on how to check out a local
+ branch based on a tag name, see the
+ "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
+ and
+ <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>"
+ sections, respectively.</para>
+
+ <para>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:
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ 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 <filename>git pull ‐‐rebase</filename>
+ command to be sure you are up-to-date with the upstream
+ branch.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='checking-out-by-branch-in-poky'>
+ <title>Checking Out by Branch in Poky</title>
+
+ <para>
+ When you clone the upstream poky repository, you have access to
+ all its development branches.
+ Each development branch in a repository is unique as it forks
+ off the "master" branch.
+ To see and use the files of a particular development branch
+ locally, you need to know the branch name and then specifically
+ check out that development branch.
+ <note>
+ Checking out an active development branch by branch name
+ gives you a snapshot of that particular branch at the time
+ you check it out.
+ Further development on top of the branch that occurs after
+ check it out can occur.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Switch to the Poky Directory:</emphasis>
+ If you have a local poky Git repository, switch to that
+ directory.
+ If you do not have the local copy of poky, see the
+ "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Determine Existing Branch Names:</emphasis>
+ <literallayout class='monospaced'>
+ $ 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 ...
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Check out the Branch:</emphasis>
+ 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:
+ <literallayout class='monospaced'>
+ $ 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;'
+ </literallayout>
+ The previous command checks out the "&DISTRO_NAME_NO_CAP;"
+ development branch and reports that the branch is tracking
+ the upstream "origin/&DISTRO_NAME_NO_CAP;" branch.</para>
+
+ <para>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:
+ <literallayout class='monospaced'>
+ $ git branch
+ master
+ * &DISTRO_NAME_NO_CAP;
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='checkout-out-by-tag-in-poky'>
+ <title>Checking Out by Tag in Poky</title>
+
+ <para>
+ Similar to branches, the upstream repository uses tags
+ to mark specific commits associated with significant points in
+ a development branch (i.e. a release point or stage of a
+ release).
+ You might want to set up a local branch based on one of those
+ points in the repository.
+ The process is similar to checking out by branch name except you
+ use tag names.
+ <note>
+ Checking out a branch based on a tag gives you a
+ stable set of files not affected by development on the
+ branch above the tag.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Switch to the Poky Directory:</emphasis>
+ If you have a local poky Git repository, switch to that
+ directory.
+ If you do not have the local copy of poky, see the
+ "<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Fetch the Tag Names:</emphasis>
+ To checkout the branch based on a tag name, you need to
+ fetch the upstream tags into your local repository:
+ <literallayout class='monospaced'>
+ $ git fetch --tags
+ $
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>List the Tag Names:</emphasis>
+ You can list the tag names now:
+ <literallayout class='monospaced'>
+ $ 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
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Check out the Branch:</emphasis>
+ <literallayout class='monospaced'>
+ $ git checkout tags/&DISTRO_REL_TAG; -b my_yocto_&DISTRO;
+ Switched to a new branch 'my_yocto_&DISTRO;'
+ $ git branch
+ master
+ * my_yocto_&DISTRO;
+ </literallayout>
+ 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 <filename>checkout</filename>
+ command are a snapshot of the
+ "&DISTRO_NAME_NO_CAP;" development branch at the point
+ where Yocto Project &DISTRO; was released.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->