752 lines
36 KiB
XML
752 lines
36 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>Getting Started with the Yocto Project</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This chapter provides procedures related to getting set up to use the
|
||
|
|
Yocto Project.
|
||
|
|
For a more front-to-end process that takes you from minimally preparing
|
||
|
|
a build host through building an image, see the
|
||
|
|
<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<section id='setting-up-the-development-host-to-use-the-yocto-project'>
|
||
|
|
<title>Setting Up the Development Host to Use the Yocto Project</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This section provides procedures to set up your development host to
|
||
|
|
use the Yocto Project.
|
||
|
|
You can use the Yocto Project on a native Linux development host or
|
||
|
|
you can use
|
||
|
|
<ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>,
|
||
|
|
which leverages
|
||
|
|
<ulink url='https://www.docker.com/'>Docker Containers</ulink>,
|
||
|
|
to prepare any Linux, Mac, or Windows development host.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Once your development 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, kernel development, and
|
||
|
|
development using the <trademark class='trade'>Eclipse</trademark> IDE:
|
||
|
|
<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>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Eclipse Development:</emphasis>
|
||
|
|
See the
|
||
|
|
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>"
|
||
|
|
Chapter in the Yocto Project Application Development and the
|
||
|
|
Extensible Software Development Kit (eSDK) 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 development 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, 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>
|
||
|
|
You 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, and Python.
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>
|
||
|
|
Git 1.8.3.1 or greater
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
tar 1.27 or greater
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
Python 3.4.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-and-python-versions'>Required Git, tar, and Python 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 machine 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-host-development-system'>Required Packages for the Host Development System</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://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>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 development host:
|
||
|
|
<orderedlist>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Go to the Docker Installation Site:</emphasis>
|
||
|
|
<ulink url='https://www.docker.com/what-docker'>Docker</ulink>
|
||
|
|
is a software container platform that you need to install
|
||
|
|
on the host development machine.
|
||
|
|
To start the installation process, see the
|
||
|
|
<ulink url='https://docs.docker.com/engine/installation/'>Docker Installation</ulink>
|
||
|
|
site.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Choose Your Docker Edition:</emphasis>
|
||
|
|
Docker comes in several editions.
|
||
|
|
For the Yocto Project, the stable community edition
|
||
|
|
(i.e. "Docker CE Stable") is adequate.
|
||
|
|
You can learn more about the Docker editions from the
|
||
|
|
site.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Go the Install Site for Your Platform:</emphasis>
|
||
|
|
Click the link for the Docker edition associated with
|
||
|
|
your development host machine's native software.
|
||
|
|
For example, if your machine 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>Understand What You Need:</emphasis>
|
||
|
|
The install page has pre-requisites your machine must
|
||
|
|
meet.
|
||
|
|
Be sure you read through this page and make sure your
|
||
|
|
machine meets the requirements to run Docker.
|
||
|
|
If your machine does not meet the requirements, the page
|
||
|
|
has instructions to handle exceptions.
|
||
|
|
For example, to run Docker on Windows 10, you must have
|
||
|
|
the pro version of the operating system.
|
||
|
|
If you have the home version, you need to install the
|
||
|
|
<ulink url='https://docs.docker.com/toolbox/overview/#ready-to-get-started'>Docker Toolbox</ulink>.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>Another example is that a Windows machine needs to
|
||
|
|
have Microsoft Hyper-V.
|
||
|
|
If you have a legacy version of the the Microsoft
|
||
|
|
operating system or for any other reason you do not have
|
||
|
|
Microsoft Hyper-V, you would have to enter the BIOS and
|
||
|
|
enable virtualization.
|
||
|
|
</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.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Optionally Orient Yourself With Dockers:</emphasis>
|
||
|
|
If you are unfamiliar with Dockers and the container
|
||
|
|
concept, you can learn more here -
|
||
|
|
<ulink url='https://docs.docker.com/get-started/'></ulink>.
|
||
|
|
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
|
||
|
|
development 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>
|
||
|
|
|
||
|
|
<section id='working-with-yocto-project-source-files'>
|
||
|
|
<title>Working With Yocto Project Source Files</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
This section contains procedures related to locating and securing
|
||
|
|
Yocto Project files.
|
||
|
|
You establish and use these local files to work on projects.
|
||
|
|
<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_REF_URL;#git'>Git</ulink>"
|
||
|
|
section in the Yocto Project Reference Manual.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
For concepts on Yocto Project source repositories, see the
|
||
|
|
"<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
|
||
|
|
section in the Yocto Project Reference Manual."
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<section id='accessing-source-repositories'>
|
||
|
|
<title>Accessing Source Repositories</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Yocto Project maintains upstream Git
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
|
||
|
|
that you can examine and access using a browser-based UI:
|
||
|
|
<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 a Repository:</emphasis>
|
||
|
|
Click on any 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_REF_URL;#git-commands-clone'>clone</ulink>
|
||
|
|
that repository (e.g.
|
||
|
|
<filename>&YOCTO_GIT_URL;/poky</filename>).
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Examine Change History of the Repository:</emphasis>
|
||
|
|
At the top of the page, click on any branch in which you
|
||
|
|
might be interested (e.g.
|
||
|
|
<filename>&DISTRO_NAME_NO_CAP;</filename>).
|
||
|
|
You can then view the commit log or tree view for that
|
||
|
|
development branch.
|
||
|
|
</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 represent snapshot
|
||
|
|
tarballs.
|
||
|
|
<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>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>eclipse-plugin</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 for retroactive
|
||
|
|
completeness only.
|
||
|
|
</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 a tarball to download and save a snapshot of a
|
||
|
|
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" area from which you can locate and download
|
||
|
|
tarballs of any Yocto Project release.
|
||
|
|
Rather than Git repositories, these files represent snapshot
|
||
|
|
tarballs.
|
||
|
|
<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>
|
||
|
|
Click the "Downloads" tab.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Select the Type of Files:</emphasis>
|
||
|
|
Click the type of files you want (i.e "Build System",
|
||
|
|
"Tools", or "Board Support Packages (BSPs)".
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Locate and Download the Tarball:</emphasis>
|
||
|
|
From the list of releases, locate the appropriate
|
||
|
|
download link and download the files.
|
||
|
|
</para></listitem>
|
||
|
|
</orderedlist>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
<section id='cloning-the-poky-repository'>
|
||
|
|
<title>Cloning the <filename>poky</filename> Repository</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
To use the Yocto Project, you need a release of the Yocto Project
|
||
|
|
locally installed on your development system.
|
||
|
|
The 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>
|
||
|
|
You create your Source Directory by using
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> to clone a local
|
||
|
|
copy of the upstream <filename>poky</filename> repository.
|
||
|
|
<note><title>Tip</title>
|
||
|
|
The preferred method of getting the Yocto Project Source
|
||
|
|
Directory set up is to clone the repository.
|
||
|
|
</note>
|
||
|
|
Working from a copy of the upstream repository allows you
|
||
|
|
to contribute back into the Yocto Project or 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>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
Be in the directory where you want to create your local
|
||
|
|
copy of poky.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Clone the Repository:</emphasis>
|
||
|
|
The following command clones the 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: 367178, done.
|
||
|
|
remote: Compressing objects: 100% (88161/88161), done.
|
||
|
|
remote: Total 367178 (delta 272761), reused 366942 (delta 272525)
|
||
|
|
Receiving objects: 100% (367178/367178), 133.26 MiB | 6.40 MiB/s, done.
|
||
|
|
Resolving deltas: 100% (272761/272761), 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>",
|
||
|
|
respectively.</para>
|
||
|
|
|
||
|
|
<para>Once the 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.
|
||
|
|
</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/master-next
|
||
|
|
remotes/origin/master-next2
|
||
|
|
remotes/origin/morty
|
||
|
|
remotes/origin/pinky
|
||
|
|
remotes/origin/purple
|
||
|
|
remotes/origin/pyro
|
||
|
|
remotes/origin/rocko
|
||
|
|
</literallayout>
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Checkout the Branch:</emphasis>
|
||
|
|
Checkout 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.2
|
||
|
|
yocto-2.2.1
|
||
|
|
yocto-2.3
|
||
|
|
yocto-2.3.1
|
||
|
|
yocto-2.4
|
||
|
|
yocto_1.5_M5.rc8
|
||
|
|
</literallayout>
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Checkout the Branch:</emphasis>
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
$ git checkout tags/&DISTRO; -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>
|
||
|
|
|
||
|
|
<section id='performing-a-simple-build'>
|
||
|
|
<title>Performing a Simple Build</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
Several methods exist that allow you to build an image within the
|
||
|
|
Yocto Project.
|
||
|
|
This procedure shows how to build an image using BitBake from a
|
||
|
|
Linux host.
|
||
|
|
<note><title>Notes</title>
|
||
|
|
<itemizedlist>
|
||
|
|
<listitem><para>
|
||
|
|
For information on how to build an image using
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
|
||
|
|
see the
|
||
|
|
<ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
For information on how to use
|
||
|
|
<filename>devtool</filename> to build images, see the
|
||
|
|
"<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
|
||
|
|
section in the Yocto Project Application Development and
|
||
|
|
the Extensible Software Development Kit (eSDK) manual.
|
||
|
|
</para></listitem>
|
||
|
|
</itemizedlist>
|
||
|
|
</note>
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The build process creates an entire Linux distribution from source
|
||
|
|
and places it in your
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
|
||
|
|
under <filename>tmp/deploy/images</filename>.
|
||
|
|
For detailed information on the build process using BitBake, see the
|
||
|
|
"<ulink url='&YOCTO_DOCS_REF_URL;#images-dev-environment'>Images</ulink>"
|
||
|
|
section in the Yocto Project Reference Manual.
|
||
|
|
You can also reference the
|
||
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
|
||
|
|
section in the Yocto Project Quick Start.
|
||
|
|
</para>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The following figure and list overviews the build process:
|
||
|
|
<imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
|
||
|
|
<orderedlist>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Set up Your Host Development System to Support
|
||
|
|
Development Using the Yocto Project</emphasis>:
|
||
|
|
See the
|
||
|
|
"<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
|
||
|
|
section in the Yocto Project Quick Start for options on how
|
||
|
|
to get a build host ready to use the Yocto Project.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Initialize the Build Environment:</emphasis>
|
||
|
|
Initialize the build environment by sourcing the build
|
||
|
|
environment script (i.e.
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Make Sure Your <filename>local.conf</filename>
|
||
|
|
File is Correct:</emphasis>
|
||
|
|
Ensure the <filename>conf/local.conf</filename> configuration
|
||
|
|
file, which is found in the
|
||
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
|
||
|
|
is set up how you want it.
|
||
|
|
This file defines many aspects of the build environment
|
||
|
|
including the target machine architecture through the
|
||
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
|
||
|
|
the packaging format used during the build
|
||
|
|
(<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
|
||
|
|
and a centralized tarball download directory through the
|
||
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.
|
||
|
|
</para></listitem>
|
||
|
|
<listitem><para>
|
||
|
|
<emphasis>Build the Image:</emphasis>
|
||
|
|
Build the image using the <filename>bitbake</filename> command.
|
||
|
|
For example, the following command builds the
|
||
|
|
<filename>core-image-minimal</filename> image:
|
||
|
|
<literallayout class='monospaced'>
|
||
|
|
$ bitbake core-image-minimal
|
||
|
|
</literallayout>
|
||
|
|
For information on BitBake, see the
|
||
|
|
<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
|
||
|
|
</para></listitem>
|
||
|
|
</orderedlist>
|
||
|
|
</para>
|
||
|
|
</section>
|
||
|
|
|
||
|
|
-->
|
||
|
|
</chapter>
|
||
|
|
<!--
|
||
|
|
vim: expandtab tw=80 ts=4
|
||
|
|
-->
|