mirror of
https://git.yoctoproject.org/poky
synced 2026-02-07 01:06:37 +01:00
1ad7977742
To make the kernel example more easily understood, Joshua Lock suggested that the names used for the bare clone of the kernel git repo and the copy of the bare clone be more different. So I have changed the example such that the bare clone repo is named linux-yocto-3.0-1.1.x.git and the copy of the bare clone (or working repo) is named my-linux-yocto-3.0-1.1.x-work. Note that this also implies the use of the linux-yocto_3.0-1.1.x kernel and not the linux-yocto_3.0 kernel. All the changes made here should take care of the example. I did have to introduce a new figure that showed the kernel repos based on the new names used in the example. Also, I had to delete the other from this branch. The examples are now diverging according to (master) work and 1.1.x work. Reported-by: Joshua Lock <joshua.lock@intel.com> (From yocto-docs rev: f4fdef6078fccfc2c72b6e0ad1dfae1f1ecb2aa6) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
278 lines
17 KiB
XML
278 lines
17 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||
|
||
<chapter id='dev-manual-start'>
|
||
|
||
<title>Getting Started with the Yocto Project</title>
|
||
|
||
<para>
|
||
This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
|
||
You can find enough information to set up your development host and build or use images for
|
||
hardware supported by the Yocto Project by reading
|
||
<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html'>
|
||
The Yocto Project Quick Start</ulink>.
|
||
</para>
|
||
|
||
<para>
|
||
The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
|
||
some higher-level concepts you might want to consider.
|
||
</para>
|
||
|
||
<section id='introducing-the-yocto-project'>
|
||
<title>Introducing the Yocto Project</title>
|
||
|
||
<para>
|
||
The Yocto Project is an open-source collaboration project focused on embedded Linux development.
|
||
The project currently provides a build system, which is sometimes referred to as "Poky",
|
||
and provides various ancillary tools suitable for the embedded developer.
|
||
The Yocto Project also features the Sato reference User Interface, which is optimized for
|
||
stylus driven, low-resolution screens.
|
||
</para>
|
||
|
||
<para>
|
||
You can use the Yocto Project, which uses the BitBake build tool, to develop complete Linux
|
||
images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
|
||
x86 and x86-64.
|
||
While the Yocto Project does not provide a strict testing framework,
|
||
it does provide or generate for you artifacts that let you perform target-level and
|
||
emulated testing and debugging.
|
||
And, if you are an <trademark class='trade'>Eclipse</trademark>
|
||
IDE user, you can install an Eclipse Yocto Plug-in to allow you to
|
||
develop within that familiar environment.
|
||
</para>
|
||
</section>
|
||
|
||
<section id='getting-setup'>
|
||
<title>Getting Setup</title>
|
||
|
||
<para>
|
||
Here is what you need to get set up 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, or Ubuntu as these releases are frequently tested against the Yocto Project
|
||
and officially supported.
|
||
You should also have about 100 gigabytes of free disk space for building images.
|
||
</para></listitem>
|
||
<listitem><para><emphasis>Packages:</emphasis> The Yocto Project requires certain packages
|
||
exist on your development system (e.g. Python 2.6 or 2.7).
|
||
See "<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#packages'>The Packages</ulink>"
|
||
section in the Yocto Project Quick start for the exact package
|
||
requirements and the installation commands to install them
|
||
for the supported distributions.</para></listitem>
|
||
<listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
|
||
You need a release of the Yocto Project.
|
||
You can get set up with local Yocto Project files one of two ways depending on whether you
|
||
are going to be contributing back into the Yocto Project source repository or not.
|
||
<note>
|
||
Regardless of the method you use, this manual refers to the resulting
|
||
hierarchical set of files as "the Yocto Project files" or "the Yocto Project file
|
||
structure."
|
||
</note>
|
||
<itemizedlist>
|
||
<listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
|
||
back into the Yocto Project, you can simply download the Yocto Project release you want
|
||
from the website’s <ulink url='http://yoctoproject.org/download'>download page</ulink>.
|
||
Once you have the tarball, just extract it into a directory of your choice.</para>
|
||
<para>For example, the following command extracts the Yocto Project 1.1.1 release tarball
|
||
into the current working directory and sets up the Yocto Project file structure
|
||
with a top-level directory named <filename>poky-edison-6.0.1</filename>:
|
||
<literallayout class='monospaced'>
|
||
$ tar xfj poky-edison-6.0.1.tar.bz2
|
||
</literallayout></para>
|
||
<para>This method does not produce a Git repository.
|
||
Instead, you simply end up with a local snapshot of the
|
||
Yocto Project files that are based on the particular release in the
|
||
tarball.</para></listitem>
|
||
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing
|
||
back into the Yocto Project, you should use Git commands to set up a local
|
||
Git repository of the Yocto Project files.
|
||
Doing so creates a Git repository with a complete history of changes and allows
|
||
you to easily submit your changes upstream to the project.</para>
|
||
<para>The following transcript shows how to clone the Yocto Project files'
|
||
Git repository into the current working directory.
|
||
The command creates the repository in a directory named <filename>poky</filename>.
|
||
For information on the Yocto Project and Git, see the
|
||
"<link linkend='git'>Git</link>" section.
|
||
<literallayout class='monospaced'>
|
||
$ git clone git://git.yoctoproject.org/poky
|
||
Initialized empty Git repository in /home/scottrif/poky/.git/
|
||
remote: Counting objects: 116882, done.
|
||
remote: Compressing objects: 100% (35987/35987), done.
|
||
remote: Total 116882 (delta 80651), reused 113045 (delta 77578)
|
||
Receiving objects: 100% (116882/116882), 72.13 MiB | 2.68 MiB/s, done.
|
||
Resolving deltas: 100% (80651/80651), done. </literallayout></para>
|
||
<para>For another example of how to set up your own local Git repositories, see this
|
||
<ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
|
||
wiki page</ulink>, which describes how to create both <filename>poky</filename>
|
||
and <filename>meta-intel</filename> Git repositories.</para></listitem>
|
||
</itemizedlist></para></listitem>
|
||
<listitem id='local-kernel-files'><para><emphasis>Linux Yocto Kernel:</emphasis>
|
||
If you are going to be making modifications to a supported Linux Yocto kernel, you
|
||
need to establish local copies of the source.
|
||
This setup involves creating a bare clone of the Linux Yocto kernel and then cloning
|
||
that 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
|
||
Yocto Project files' Git repository.</para>
|
||
<para>As an example, the following transcript shows how to create the bare clone
|
||
of the <filename>linux-yocto-3.0-1.1.x</filename> kernel and then create a copy of
|
||
that clone.
|
||
<note>When you have a local Linux Yocto 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>
|
||
In the following example, the bare clone is named
|
||
<filename>linux-yocto-3.0-1.1.x.git</filename>, while the
|
||
copy is named <filename>my-linux-yocto-3.0-1.1.x-work</filename>:
|
||
<literallayout class='monospaced'>
|
||
$ git clone --bare git://git.yoctoproject.org/linux-yocto-3.0-1.1.x linux-yocto-3.0-1.1.x.git
|
||
Initialized empty Git repository in /home/scottrif/linux-yocto-3.0-1.1.x.git/
|
||
remote: Counting objects: 2259181, done.
|
||
remote: Compressing objects: 100% (373259/373259), done.
|
||
remote: Total 2259181 (delta 1892638), reused 2231556 (delta 1865300)
|
||
Receiving objects: 100% (2259181/2259181), 482.44 MiB | 580 KiB/s, done.
|
||
Resolving deltas: 100% (1892638/1892638), done.
|
||
</literallayout></para>
|
||
<para>Now create a clone of the bare clone just created:
|
||
<literallayout class='monospaced'>
|
||
$ git clone linux-yocto-3.0-1.1.x.git my-linux-yocto-3.0-1.1.x-work
|
||
Initialized empty Git repository in /home/scottrif/my-linux-yocto-3.0-1.1.x/.git/
|
||
Checking out files: 100% (36898/36898), done.
|
||
</literallayout></para></listitem>
|
||
<listitem id='poky-extras-repo'><para><emphasis>
|
||
The <filename>poky-extras</filename> Git Repository</emphasis>:
|
||
The <filename>poky-extras</filename> Git repository contains metadata needed to
|
||
build the kernel image.
|
||
In particular, it contains the kernel <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
|
||
source files from upstream each time you make changes to the kernel.</para>
|
||
<para>It is good practice to create this Git repository inside the Yocto Project
|
||
files Git repository.
|
||
Following is an example that creates the <filename>poky-extras</filename> Git
|
||
repository inside the Yocto Project files Git repository, which is named
|
||
<filename>poky</filename> in this case:
|
||
<literallayout class='monospaced'>
|
||
$ cd ~/poky
|
||
$ git clone git://git.yoctoproject.org/poky-extras poky-extras
|
||
Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
|
||
remote: Counting objects: 561, done.
|
||
remote: Compressing objects: 100% (501/501), done.
|
||
remote: Total 561 (delta 159), reused 306 (delta 39)
|
||
Receiving objects: 100% (561/561), 519.96 KiB | 479 KiB/s, done.
|
||
Resolving deltas: 100% (159/159), done.
|
||
</literallayout></para></listitem>
|
||
<listitem><para><emphasis>Supported Board Support Packages (BSPs):</emphasis>
|
||
Similar considerations exist for BSPs.
|
||
You can get set up for BSP development one of two ways: tarball extraction or
|
||
with a local Git repository.
|
||
Regardless of the method you use, the Yocto Project uses the following BSP layer
|
||
naming scheme:
|
||
<literallayout class='monospaced'>
|
||
meta-<BSP_name>
|
||
</literallayout>
|
||
where <BSP_name> is the recognized BSP name.
|
||
Here are some examples:
|
||
<literallayout class='monospaced'>
|
||
meta-crownbay
|
||
meta-emenlow
|
||
meta-n450
|
||
</literallayout>
|
||
<itemizedlist>
|
||
<listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
|
||
BSP tarball from the same
|
||
<ulink url='http://yoctoproject.org/download'>download site</ulink> used
|
||
to get the Yocto Project release.
|
||
Once you have the tarball, just extract it into a directory of your choice.
|
||
Again, this method just produces a snapshot of the BSP layer in the form
|
||
of a hierarchical directory structure.</para></listitem>
|
||
<listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
|
||
with a Yocto Project files Git repository, you should also set up a
|
||
<filename>meta-intel</filename> Git repository.
|
||
Typically, you set up the <filename>meta-intel</filename> Git repository inside
|
||
the Yocto Project files Git repository.</para>
|
||
<para>For example, the following transcript shows the steps to clone the
|
||
<filename>meta-intel</filename>
|
||
Git repository inside the <filename>poky</filename> Git repository.
|
||
<literallayout class='monospaced'>
|
||
$cd poky
|
||
$ git clone git://git.yoctoproject.org/meta-intel.git
|
||
Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
|
||
remote: Counting objects: 3279, done.
|
||
remote: Compressing objects: 100% (2708/2708), done.
|
||
remote: Total 3279 (delta 1761), reused 194 (delta 105)
|
||
Receiving objects: 100% (3279/3279), 1.75 MiB | 377 KiB/s, done.
|
||
Resolving deltas: 100% (1761/1761), done.
|
||
</literallayout></para>
|
||
<para>The same
|
||
<ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
|
||
wiki page</ulink> referenced earlier covers how to
|
||
set up the <filename>meta-intel</filename> Git repository.</para></listitem>
|
||
</itemizedlist></para></listitem>
|
||
<listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
|
||
applications using the Eclipse Integrated Development Environment (IDE),
|
||
you will need this plug-in.
|
||
See the
|
||
"<ulink url='http://www.yoctoproject.org/docs/1.1.1/adt-manual/adt-manual.html#setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</ulink>"
|
||
section in the Yocto Application Development Toolkit (ADT)
|
||
User’s Guide for more information.</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</section>
|
||
|
||
<section id='building-images'>
|
||
<title>Building Images</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='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>"
|
||
section in the Yocto Project Quick Start.
|
||
</para>
|
||
|
||
<para>
|
||
The build process is as follows:
|
||
<orderedlist>
|
||
<listitem><para>Make sure you have the Yocto Project files as described in the
|
||
previous section.</para></listitem>
|
||
<listitem><para>Initialize the build environment by sourcing a build environment
|
||
script.</para></listitem>
|
||
<listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file is set
|
||
up how you want it.
|
||
This file defines the target machine architecture and other build options.</para></listitem>
|
||
<listitem><para>Build the image using the BitBake command.
|
||
If you want information on Bitbake, see the user manual at
|
||
<ulink url='http://docs.openembedded.org/bitbake/html'></ulink>.</para></listitem>
|
||
<listitem><para>Run the image either on the actual hardware or using the QEMU
|
||
emulator.</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.
|
||
This scenario is ideal for developing software applications to run on your target hardware.
|
||
To do this, you need to install the stand-alone Yocto Project cross-toolchain tarball and
|
||
then download the pre-built kernel that you will boot in the QEMU emulator.
|
||
Next, you must download and extract the target root filesystem for your target
|
||
machine’s architecture.
|
||
Finally, you set up the environment to emulate the hardware and then start the QEMU emulator.
|
||
</para>
|
||
|
||
<para>
|
||
You can find details on all these steps in the
|
||
"<ulink url='http://www.yoctoproject.org/docs/1.1.1/yocto-project-qs/yocto-project-qs.html#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
|
||
section of the Yocto Project Quick Start.
|
||
</para>
|
||
</section>
|
||
</chapter>
|
||
<!--
|
||
vim: expandtab tw=80 ts=4
|
||
-->
|