mirror of
https://git.yoctoproject.org/poky
synced 2026-01-29 21:08:42 +01:00
293b53674c
Fixes [YOCTO #11630] The section on the devtool workflow in the dev-manual was 99% identical to what was in the sdk-manual. I have moved the workflow procedure from the old "Model" chapter of the dev-manual to be merged with what was in the sdk-manual. In truth, the only things added were a note about devtool not being exclusive to SDK development. The result of moving (deleting) this section was that the "model" chapter of the dev-manual went away. The devtool stuff, Quilt, devshell, and python shell are all out now and there is no chapter left. So, mega-manual had to be adjusted to not pull that chapter in when building the dev-manual. I had to delete three figures that were used in the flow. The figures were already replicated in the sdk-manual. The figures were deleted from the figures folder of both the dev-manual and the mega-manual. I had to make sure all references to the old devtool stuf in the YP doc set were adjusted. (From yocto-docs rev: 5dbd643d31ab502df53a22229e457a03da7772b7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
932 lines
44 KiB
XML
932 lines
44 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.
|
||
For a Linux system to use the Yocto Project, you need to be sure
|
||
you are running a supported Linux distribution and have the proper
|
||
host packages installed.
|
||
If you are using
|
||
<ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>
|
||
that leverages
|
||
<ulink url='https://www.docker.com/'>Docker Containers</ulink>,
|
||
host setup differs from that of a native Linux machine.
|
||
</para>
|
||
|
||
<section id='setting-up-a-native-linux-host'>
|
||
<title>Setting Up a Native Linux Host</title>
|
||
|
||
<para role='writernotes'>
|
||
Need text - Following is some basics for a Linux host system.
|
||
This information needs to be worked in.
|
||
</para>
|
||
|
||
<para>
|
||
Setup consists of making sure you have a supported operating system,
|
||
installing host packages, and Here is what you need to use the Yocto Project:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<emphasis>Host System:</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>
|
||
<para>
|
||
You should also have about 50 Gbytes of free disk space
|
||
for building images.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Packages:</emphasis>
|
||
The OpenEmbedded build system requires that certain
|
||
packages exist on your development system
|
||
(e.g. Python 2.7).
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_QS_URL;#packages'>Build Host Packages</ulink>"
|
||
section in the Yocto Project Quick Start and 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 for the
|
||
exact package requirements and the installation commands
|
||
to install them for the supported distributions.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</section>
|
||
|
||
<section id='setting-up-to-use-crops'>
|
||
<title>Setting Up to Use CROPS</title>
|
||
|
||
<para role='writernotes'>
|
||
Need text.
|
||
With CROPS, not sure what the basic package requirements are.
|
||
Need to find this out.
|
||
</para>
|
||
</section>
|
||
|
||
<section id='setting-up-bsp-layers'>
|
||
<title>Setting Up BSP Layers</title>
|
||
|
||
<para>
|
||
This section describes how to set up a layer for a Board Support
|
||
Package (BSP).
|
||
For structural information on BSPs, see the
|
||
<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-guide'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Determine the BSP Layer You Want:</emphasis>
|
||
The Yocto Project supports many BSPs, which are maintained in
|
||
their own layers or in layers designed to contain several
|
||
BSPs.
|
||
To get an idea of machine support through BSP layers, you can
|
||
look at the
|
||
<ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink>
|
||
for the release.
|
||
<note>
|
||
The Yocto Project uses the following BSP layer naming
|
||
scheme:
|
||
<literallayout class='monospaced'>
|
||
meta-<replaceable>bsp_name</replaceable>
|
||
</literallayout>
|
||
where <replaceable>bsp_name</replaceable> is the recognized
|
||
BSP name.
|
||
Here is an example:
|
||
<literallayout class='monospaced'>
|
||
meta-raspberrypi
|
||
</literallayout>
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
|
||
section in the Yocto Project Board Support Package (BSP)
|
||
Developer's Guide for more information on BSP Layers.
|
||
</note>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Optionally Set Up the <filename>meta-intel</filename> BSP Layer:</emphasis>
|
||
If your hardware is based on current Intel CPUs and devices,
|
||
you can leverage this BSP layer.
|
||
For details on the <filename>meta-intel</filename> BSP layer,
|
||
see the layer's
|
||
<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink>
|
||
file.
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Navigate to Your Source Directory:</emphasis>
|
||
Typically, you set up the
|
||
<filename>meta-intel</filename> Git repository
|
||
inside the
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||
(e.g. <filename>poky</filename>).
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Clone the Layer:</emphasis>
|
||
<literallayout class='monospaced'>
|
||
$ git clone git://git.yoctoproject.org/meta-intel.git
|
||
Cloning into 'meta-intel'...
|
||
remote: Counting objects: 14224, done.
|
||
remote: Compressing objects: 100% (4591/4591), done.
|
||
remote: Total 14224 (delta 8245), reused 13985 (delta 8006)
|
||
Receiving objects: 100% (14224/14224), 4.29 MiB | 2.90 MiB/s, done.
|
||
Resolving deltas: 100% (8245/8245), done.
|
||
Checking connectivity... done.
|
||
</literallayout>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Check Out the Proper Branch:</emphasis>
|
||
The branch you check out for
|
||
<filename>meta-intel</filename> must match the same
|
||
branch you are using for the Yocto Project release
|
||
(e.g. &DISTRO_NAME_NO_CAP;):
|
||
<literallayout class='monospaced'>
|
||
$ git checkout <replaceable>branch_name</replaceable>
|
||
</literallayout>
|
||
For an example on how to discover branch names and
|
||
checkout on a branch, see the
|
||
"<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
|
||
section.
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis>
|
||
If your hardware can be more closely leveraged to an
|
||
existing BSP not within the <filename>meta-intel</filename>
|
||
BSP layer, you can clone that BSP layer.</para>
|
||
|
||
<para>The process is identical to the process used for the
|
||
<filename>meta-intel</filename> layer except for the layer's
|
||
name.
|
||
For example, if you determine that your hardware most
|
||
closely matches the <filename>meta-minnow</filename>,
|
||
clone that layer:
|
||
<literallayout class='monospaced'>
|
||
$ git clone git://git.yoctoproject.org/meta-minnow
|
||
Cloning into 'meta-minnow'...
|
||
remote: Counting objects: 456, done.
|
||
remote: Compressing objects: 100% (283/283), done.
|
||
remote: Total 456 (delta 163), reused 384 (delta 91)
|
||
Receiving objects: 100% (456/456), 96.74 KiB | 0 bytes/s, done.
|
||
Resolving deltas: 100% (163/163), done.
|
||
Checking connectivity... done.
|
||
</literallayout>
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
|
||
<section id='local-kernel-files'>
|
||
<title>Setting Up to Work on a Kernel</title>
|
||
|
||
<para>
|
||
Kernel development is best accomplished using
|
||
<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename></ulink>
|
||
and not through traditional kernel workflow methods.
|
||
This section provides procedures to set up for both.
|
||
</para>
|
||
|
||
<section id='getting-ready-to-develop-using-devtool'>
|
||
<title>Getting Ready to Develop using <filename>devtool</filename></title>
|
||
|
||
<para role='writernotes'>
|
||
Need the updated wiki stuff here
|
||
</para>
|
||
</section>
|
||
|
||
<section id='getting-ready-for-traditional-kernel-development'>
|
||
<title>Getting Ready for Traditional Kernel Development</title>
|
||
|
||
<para>
|
||
For traditional kernel development using the Yocto
|
||
Project, you need to establish local copies of the
|
||
kernel source.
|
||
You can find Git repositories of supported Yocto Project
|
||
kernels organized under "Yocto Linux Kernel" in the Yocto
|
||
Project Source Repositories at
|
||
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
|
||
</para>
|
||
|
||
<para>
|
||
This setup can involve creating a bare clone of the
|
||
Yocto Project kernel and then copying that cloned
|
||
repository.
|
||
You can create the bare clone and the copy of the bare
|
||
clone anywhere you like.
|
||
For simplicity, it is recommended that you create these
|
||
structures outside of the
|
||
<ulink url='&YOCTO_DOCS_REF_URL;source-directory'>Source Directory</ulink>,
|
||
which is usually named <filename>poky</filename>.
|
||
</para>
|
||
|
||
<para>
|
||
The following steps show how to create a bare clone of the
|
||
<filename>linux-yocto-4.4</filename> kernel and then
|
||
create a copy of that clone:
|
||
<note>
|
||
When you have a local Yocto Project kernel Git
|
||
repository, you can reference that repository rather than
|
||
the upstream Git repository as part of the
|
||
<filename>clone</filename> command.
|
||
Doing so can speed up the process.
|
||
</note>
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Create the Bare Clone:</emphasis>
|
||
In the following example, the bare clone is named
|
||
<filename>linux-yocto-4.4.git</filename>:
|
||
<literallayout class='monospaced'>
|
||
$ git clone ‐‐bare git://git.yoctoproject.org/linux-yocto-4.4 linux-yocto-4.4.git
|
||
Cloning into bare repository 'linux-yocto-4.4.git'...
|
||
remote: Counting objects: 4543903, done.
|
||
remote: Compressing objects: 100% (695618/695618), done.
|
||
remote: Total 4543903 (delta 3818435), reused 4541724 (delta 3816256)
|
||
Receiving objects: 100% (4543903/4543903), 801.08 MiB | 6.55 MiB/s, done.
|
||
Resolving deltas: 100% (3818435/3818435), done.
|
||
Checking connectivity... done.
|
||
</literallayout>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Create the Copy of the Bare Clone:</emphasis>
|
||
In the following command, the copy of the bare clone
|
||
is named <filename>my-linux-yocto-4.4-work</filename>:
|
||
<literallayout class='monospaced'>
|
||
$ git clone linux-yocto-4.4.git my-linux-yocto-4.4-work
|
||
Cloning into 'my-linux-yocto-4.4-work'...
|
||
done.
|
||
Checking out files: 100% (52221/52221), done.
|
||
</literallayout>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Cloning the <filename>meta-yocto-kernel-extras</filename> Repository:</emphasis>
|
||
The <filename>meta-yocto-kernel-extras</filename> Git
|
||
repository contains Metadata needed only if you are
|
||
modifying and building the kernel image.
|
||
In particular, it contains the kernel BitBake append
|
||
(<filename>.bbappend</filename>) files that you edit to
|
||
point to your locally modified kernel source files and to
|
||
build the kernel image.
|
||
Pointing to these local files is much more efficient than
|
||
requiring a download of the kernel's source files from
|
||
upstream each time you make changes to the kernel.</para>
|
||
|
||
<para>You can find the
|
||
<filename>meta-yocto-kernel-extras</filename> Git
|
||
Repository in the "Yocto Metadata Layers" area of the
|
||
Yocto Project Source Repositories at
|
||
<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
|
||
It is good practice to create this Git repository
|
||
inside the Source Directory.</para>
|
||
|
||
<para>Following is an example that creates the
|
||
<filename>meta-yocto-kernel-extras</filename> Git
|
||
repository inside the Source Directory, which is named
|
||
<filename>poky</filename>, in this case:
|
||
<literallayout class='monospaced'>
|
||
$ cd ~/poky
|
||
$ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
|
||
Cloning into 'meta-yocto-kernel-extras'...
|
||
remote: Counting objects: 727, done.
|
||
remote: Compressing objects: 100% (452/452), done.
|
||
remote: Total 727 (delta 260), reused 719 (delta 252)
|
||
Receiving objects: 100% (727/727), 536.36 KiB | 0 bytes/s, done.
|
||
Resolving deltas: 100% (260/260), done.
|
||
Checking connectivity... done.
|
||
</literallayout>
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section id='setting-up-to-use-eclipse'>
|
||
<title>Setting Up to Use Eclipse</title>
|
||
|
||
<para>
|
||
This section presents the steps needed to set up your host if you
|
||
are going to be using the popular
|
||
<trademark class='trade'>Eclipse</trademark> IDE.
|
||
The steps in this procedure are links to sections in the
|
||
Yocto Project Software Development Kit (SDK) Developer's Guide
|
||
that provide detailed procedures given the Neon version of
|
||
Eclipse.
|
||
For procedures on the entire development process using
|
||
Eclipse, see the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-developing-applications-using-eclipse'>Developing Applications Using Eclipse</ulink>"
|
||
section in the Yocto Project Software Development Kit (SDK)
|
||
Developer's Guide.
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Install Eclipse:</emphasis>
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;#neon-installing-eclipse-ide'>Installing the Neon Eclipse IDE</ulink>"
|
||
section.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Configure Eclipse:</emphasis>
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;#neon-configuring-the-mars-eclipse-ide'>Configuring the Neon Eclipse IDE</ulink>"
|
||
section.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Configure Eclipse:</emphasis>
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;#neon-installing-the-eclipse-yocto-plug-in'>Installing or Accessing the Neon Eclipse Yocto Plug-in</ulink>"
|
||
section.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Configure Eclipse:</emphasis>
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;#neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</ulink>"
|
||
section.
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</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-2.3</filename> to
|
||
view files associated with the Yocto Project 2.3
|
||
release (e.g. <filename>poky-pyro-17.0.0tar.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".</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
|
||
</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
|
||
2.3 Release (Pyro), use the following command:
|
||
<literallayout class='monospaced'>
|
||
$ git checkout -b pyro origin/pyro
|
||
Branch pyro set up to track remote branch pyro from origin.
|
||
Switched to a new branch 'pyro'
|
||
</literallayout>
|
||
The previous command checks out the "pyro" development
|
||
branch and reports that the branch is tracking the upstream
|
||
"origin/pyro" 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
|
||
* pyro
|
||
</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_1.5_M5.rc8
|
||
</literallayout>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Checkout the Branch:</emphasis>
|
||
<literallayout class='monospaced'>
|
||
$ git checkout tags/2.2_M2 -b my_yocto_2.2_M2
|
||
Switched to a new branch 'my_yocto_2.2_M2'
|
||
$ git branch
|
||
master
|
||
* my_yocto_2.2_M2
|
||
</literallayout>
|
||
The previous command creates and checks out a local
|
||
branch named "my_yocto_2.2_M2", 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
|
||
"morty" development branch at the point where
|
||
milestone two was reached.
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section id='performing-a-simple-build'>
|
||
<title>Performing a Simple Build</title>
|
||
|
||
<para>
|
||
The build process creates an entire Linux distribution,
|
||
including the toolchain, from source.
|
||
For more information on this topic, see the
|
||
"<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
|
||
section in the Yocto Project Quick Start.
|
||
</para>
|
||
|
||
<para>
|
||
Following are the high-level steps for performing a simple build
|
||
using the Yocto Project:
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Set Up Your Source Directories:</emphasis>
|
||
Make sure you have set up the Source Directory described in the
|
||
"<link linkend='cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</link>"
|
||
section.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Initialize the Build Environment:</emphasis>
|
||
Initialize the build environment by sourcing a build
|
||
environment script (i.e.
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
|
||
or
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</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>
|
||
|
||
<section id='using-pre-built-binaries-and-qemu'>
|
||
<title>Using Pre-Built Binaries and QEMU</title>
|
||
|
||
<para>
|
||
Another option you have to get started is to use pre-built binaries.
|
||
The Yocto Project provides many types of binaries with each release.
|
||
See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
|
||
chapter in the Yocto Project Reference Manual
|
||
for descriptions of the types of binaries that ship with a Yocto Project
|
||
release.
|
||
</para>
|
||
|
||
<para>
|
||
Using a pre-built binary is ideal for developing software
|
||
applications to run on your target hardware.
|
||
To do this, you need to be able to access the appropriate
|
||
cross-toolchain tarball for the architecture on which you are
|
||
developing.
|
||
If you are using an SDK type image, the image ships with the complete
|
||
toolchain native to the architecture (i.e. a toolchain designed to
|
||
run on the
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>).
|
||
If you are not using an SDK type image, you need to separately download
|
||
and install the stand-alone Yocto Project cross-toolchain tarball.
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-appendix-obtain'>Obtaining the SDK</ulink>"
|
||
appendix in the Yocto Project Software Development Kit (SDK)
|
||
Developer's Guide for more information on locating and installing
|
||
cross-toolchains.
|
||
</para>
|
||
|
||
<para>
|
||
Regardless of the type of image you are using, you need to download the pre-built kernel
|
||
that you will boot in the QEMU emulator and then download and extract the target root
|
||
filesystem for your target machine’s architecture.
|
||
You can get architecture-specific binaries and file systems from
|
||
<ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
|
||
You can get installation scripts for stand-alone toolchains from
|
||
<ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
|
||
Once you have all your files, you set up the environment to emulate the hardware
|
||
by sourcing an environment setup script.
|
||
Finally, you start the QEMU emulator.
|
||
You can find details on all these steps in the
|
||
<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
|
||
You can learn more about using QEMU with the Yocto Project in the
|
||
"<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
|
||
section.
|
||
</para>
|
||
|
||
<para>
|
||
Using QEMU to emulate your hardware can result in speed issues
|
||
depending on the target and host architecture mix.
|
||
For example, using the <filename>qemux86</filename> image in the emulator
|
||
on an Intel-based 32-bit (x86) host machine is fast because the target and
|
||
host architectures match.
|
||
On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
|
||
host can be slower.
|
||
But, you still achieve faithful emulation of ARM-specific issues.
|
||
</para>
|
||
|
||
<para>
|
||
To speed things up, the QEMU images support using <filename>distcc</filename>
|
||
to call a cross-compiler outside the emulated system.
|
||
If you used <filename>runqemu</filename> to start QEMU, and the
|
||
<filename>distccd</filename> application is present on the host system, any
|
||
BitBake cross-compiling toolchain available from the build system is automatically
|
||
used from within QEMU simply by calling <filename>distcc</filename>.
|
||
You can accomplish this by defining the cross-compiler variable
|
||
(e.g. <filename>export CC="distcc"</filename>).
|
||
Alternatively, if you are using a suitable SDK image or the appropriate
|
||
stand-alone toolchain is present,
|
||
the toolchain is also automatically used.
|
||
</para>
|
||
|
||
<note>
|
||
Several mechanisms exist that let you connect to the system running on the
|
||
QEMU emulator:
|
||
<itemizedlist>
|
||
<listitem><para>QEMU provides a framebuffer interface that makes standard
|
||
consoles available.</para></listitem>
|
||
<listitem><para>Generally, headless embedded devices have a serial port.
|
||
If so, you can configure the operating system of the running image
|
||
to use that port to run a console.
|
||
The connection uses standard IP networking.</para></listitem>
|
||
<listitem><para>
|
||
SSH servers exist in some QEMU images.
|
||
The <filename>core-image-sato</filename> QEMU image has a
|
||
Dropbear secure shell (SSH) server that runs with the root
|
||
password disabled.
|
||
The <filename>core-image-full-cmdline</filename> and
|
||
<filename>core-image-lsb</filename> QEMU images
|
||
have OpenSSH instead of Dropbear.
|
||
Including these SSH servers allow you to use standard
|
||
<filename>ssh</filename> and <filename>scp</filename> commands.
|
||
The <filename>core-image-minimal</filename> QEMU image,
|
||
however, contains no SSH server.
|
||
</para></listitem>
|
||
<listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
|
||
using a local copy of the root filesystem on the host.
|
||
In order to make this connection, you must extract a root filesystem tarball by using the
|
||
<filename>runqemu-extract-sdk</filename> command.
|
||
After running the command, you must then point the <filename>runqemu</filename>
|
||
script to the extracted directory instead of a root filesystem image file.</para></listitem>
|
||
</itemizedlist>
|
||
</note>
|
||
</section>
|
||
</chapter>
|
||
<!--
|
||
vim: expandtab tw=80 ts=4
|
||
-->
|