mirror of
git://git.yoctoproject.org/poky.git
synced 2025-07-19 21:09:03 +02:00
edaad681fb
Bump tar, Python versions and add new gcc requirement. Update reference from 'required-git-tar-and-python-versions' to 'required-git-tar-python-and-gcc-versions' (From yocto-docs rev: 18b11662c7c9ab7828d2709eed4090116a751e14) Signed-off-by: Tim Orling <timothy.t.orling@linux.intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
1288 lines
66 KiB
XML
1288 lines
66 KiB
XML
<!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; ] >
|
|
|
|
<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
|
|
-->
|