summaryrefslogtreecommitdiff
path: root/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
diff options
context:
space:
mode:
authorBrad Bishop <bradleyb@fuzziesquirrel.com>2018-02-26 06:55:05 +0300
committerBrad Bishop <bradleyb@fuzziesquirrel.com>2018-03-15 17:22:49 +0300
commitd7bf8c17eca8f8c89898a7794462c773c449e983 (patch)
treed18618fca85ca5f0c077032cc7b009344b60f663 /import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
parente2b5abdc9f28cdf8578e5b9be803c8e697443c20 (diff)
downloadopenbmc-d7bf8c17eca8f8c89898a7794462c773c449e983.tar.xz
Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko) Tested: Built and verified Witherspoon and Palmetto images Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67 Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Diffstat (limited to 'import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml')
-rw-r--r--import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml1167
1 files changed, 694 insertions, 473 deletions
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
index b8527f670..195b22d0b 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-start.xml
@@ -7,523 +7,744 @@
<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 the
+ 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>
-<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>
+<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>
- The Yocto Project is an open-source collaboration project focused on embedded Linux development.
- The project currently provides a build system that is
- referred to as the
- <link linkend='build-system-term'>OpenEmbedded build system</link>
- in the Yocto Project documentation.
- The Yocto Project provides various ancillary tools for the embedded developer
- and also features the Sato reference User Interface, which is optimized for
- stylus-driven, low-resolution screens.
+ 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>
- You can use the OpenEmbedded build system, which uses
- <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux
- images and associated user-space applications for architectures based
- on ARM, MIPS, PowerPC, x86 and x86-64.
- <note>
- By default, using the Yocto Project creates a Poky distribution.
- However, you can create your own distribution by providing key
- <link linkend='metadata'>Metadata</link>.
- See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
- section for more information.
- </note>
- 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.
- Additionally, 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.
+ 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='getting-setup'>
- <title>Getting Set Up</title>
+<section id='working-with-yocto-project-source-files'>
+ <title>Working With Yocto Project Source Files</title>
<para>
- 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 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The 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>
- <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
- You need a release of the Yocto Project locally installed on
- your development system.
- The documentation refers to this set of locally installed files
- as the <link linkend='source-directory'>Source Directory</link>.
- You create your Source Directory by using
- <link linkend='git'>Git</link> to clone a local copy
- of the upstream <filename>poky</filename> repository,
- or by downloading and unpacking a tarball of an official
- Yocto Project release.
- The preferred method is to create a clone of the repository.
- </para>
- <para>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>
- <note>You can view the Yocto Project Source Repositories at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>
- </note>
- <para>The following transcript shows how to clone the
- <filename>poky</filename> Git repository into the current
- working directory.
- The command creates the local repository in a directory
- named <filename>poky</filename>.
- For information on Git used within the Yocto Project, see
- the "<link linkend='git'>Git</link>" section.
- <literallayout class='monospaced'>
+ 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: 226790, done.
- remote: Compressing objects: 100% (57465/57465), done.
- remote: Total 226790 (delta 165212), reused 225887 (delta 164327)
- Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done.
- Resolving deltas: 100% (165212/165212), done.
- </literallayout></para>
- <para>For another example of how to set up your own local Git
- repositories, see this
- <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
- wiki page</ulink>, which describes how to create local
- Git repositories for both
- <filename>poky</filename> and <filename>meta-intel</filename>.
- </para>
- <para>
- You can also get the Yocto Project Files by downloading
- Yocto Project releases from the
- <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
- From the website, you just click "Downloads" in the navigation
- pane to the left to display all Yocto Project downloads.
- Current and archived releases are available for download.
- Nightly and developmental builds are also maintained at
- <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>.
- One final site you can visit for information on Yocto Project
- releases is the
- <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
- wiki.
- </para></listitem>
- <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
- If you are going to be making modifications to a supported Yocto Project kernel, you
- need to establish local copies of the 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
- Source Directory, which is usually named <filename>poky</filename>.</para>
- <para>As an example, the following transcript shows how to create the bare clone
- of the <filename>linux-yocto-3.19</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></para>
- <para>In the following example, the bare clone is named
- <filename>linux-yocto-3.19.git</filename>, while the
- copy is named <filename>my-linux-yocto-3.19-work</filename>:
- <literallayout class='monospaced'>
- $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.19 linux-yocto-3.19.git
- Cloning into bare repository 'linux-yocto-3.19.git'...
- remote: Counting objects: 3983256, done.
- remote: Compressing objects: 100% (605006/605006), done.
- remote: Total 3983256 (delta 3352832), reused 3974503 (delta 3344079)
- Receiving objects: 100% (3983256/3983256), 843.66 MiB | 1.07 MiB/s, done.
- Resolving deltas: 100% (3352832/3352832), done.
+ 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></para>
- <para>Now create a clone of the bare clone just created:
- <literallayout class='monospaced'>
- $ git clone linux-yocto-3.19.git my-linux-yocto-3.19-work
- Cloning into 'my-linux-yocto-3.19-work'...
- done.
- Checking out files: 100% (48440/48440), done.
- </literallayout></para></listitem>
- <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
- The <filename>meta-yocto-kernel-extras</filename> Git 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 | 240 KiB/s, done.
- Resolving deltas: 100% (260/260), done.
- </literallayout></para></listitem>
- <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</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.</para>
-
- <para>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.</para>
-
- <para>A useful Git repository released with the Yocto
- Project is <filename>meta-intel</filename>, which is a
- parent layer that contains many supported
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.
- You can locate the <filename>meta-intel</filename> Git
- repository in the "Yocto Metadata Layers" area of the Yocto
- Project Source Repositories at
- <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
-
- <para>Using
- <link linkend='git'>Git</link> to create a local clone of the
- upstream repository can be helpful if you are working with
- BSPs.
- Typically, you set up the <filename>meta-intel</filename>
- Git repository inside the Source Directory.
- For example, the following transcript shows the steps to clone
- <filename>meta-intel</filename>.
- <note>
- Be sure to work in the <filename>meta-intel</filename>
- branch that matches your
- <link linkend='source-directory'>Source Directory</link>
- (i.e. <filename>poky</filename>) branch.
- For example, if you have checked out the "master" branch
- of <filename>poky</filename> and you are going to use
- <filename>meta-intel</filename>, be sure to checkout the
- "master" branch of <filename>meta-intel</filename>.
- </note>
- <literallayout class='monospaced'>
+ </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 clone git://git.yoctoproject.org/meta-intel.git
- Cloning into 'meta-intel'...
- remote: Counting objects: 11917, done.
- remote: Compressing objects: 100% (3842/3842), done.
- remote: Total 11917 (delta 6840), reused 11699 (delta 6622)
- Receiving objects: 100% (11917/11917), 2.92 MiB | 2.88 MiB/s, done.
- Resolving deltas: 100% (6840/6840), done.
- Checking connectivity... done.
- </literallayout></para>
+ $ 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>
- <para>The same
- <ulink url='&YOCTO_WIKI_URL;/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>
- <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='&YOCTO_DOCS_SDK_URL;#sdk-appendix-latest-yp-eclipse-plug-in'>Using Eclipse</ulink>"
- section in the Yocto Project Software Development Kit (SDK)
- Developer's Guide for more information.</para></listitem>
- </itemizedlist>
- </para>
+ <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='building-images'>
- <title>Building Images</title>
+<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, including the toolchain, from source.
- For more information on this topic, see the
+ 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 build process is as follows:
+ 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>Make sure you have set up the Source Directory described in the
- previous section.</para></listitem>
- <listitem><para>Initialize the build environment by sourcing a build
+ <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>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>).
</para></listitem>
- <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
- which is found in the
- <link linkend='build-directory'>Build Directory</link>,
+ <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
+ 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>
- Build the image using the <filename>bitbake</filename> command.
- If you want information on BitBake, see the
- <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</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='flashing-images-using-bmaptool'>
- <title>Flashing Images Using <filename>bmaptool</filename></title>
-
- <para>
- An easy way to flash an image to a bootable device is to use
- <filename>bmaptool</filename>, which is integrated into the
- OpenEmbedded build system.
- </para>
-
- <para>
- Following, is an example that shows how to flash a Wic image.
- <note>
- You can use <filename>bmaptool</filename> to flash any
- type of image.
- </note>
- Use these steps to flash an image using
- <filename>bmaptool</filename>:
- <note>
- Unless you are able to install the
- <filename>bmap-tools</filename> package as mentioned in the note
- in the second bullet of step 3 further down, you will need to build
- <filename>bmaptool</filename> before using it.
- Build the tool using the following command:
- <literallayout class='monospaced'>
- $ bitbake bmap-tools-native
- </literallayout>
- </note>
- <orderedlist>
- <listitem><para>
- Add the following to your <filename>local.conf</filename>
- file:
- <literallayout class='monospaced'>
- IMAGE_FSTYPES += "wic wic.bmap"
- </literallayout>
+ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.
</para></listitem>
<listitem><para>
- Either have your image ready (pre-built) or take the step
- build the image:
+ <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 <replaceable>image</replaceable>
+ $ bitbake core-image-minimal
</literallayout>
- </para></listitem>
- <listitem><para>
- Flash the image to the media by using
- <filename>bmaptool</filename> depending on your particular
- setup:
- <itemizedlist>
- <listitem><para>
- If you have write access to the media,
- use this command form:
- <literallayout class='monospaced'>
- $ oe-run-native bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
- </literallayout>
- </para></listitem>
- <listitem><para>
- If you do not have write access to
- the media, use the following
- commands:
- <literallayout class='monospaced'>
- $ sudo bash
- $ PATH=tmp/sysroots/x86_64-linux/usr/bin/ bmaptool copy ./tmp/deploy/images/qemux86-64/core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
- </literallayout>
- <note>
- If you are using Ubuntu or Debian distributions,
- you can install the
- <filename>bmap-tools</filename> package using the
- following command and then use the tool
- without specifying
- <filename>PATH</filename> even from the
- root account:
- <literallayout class='monospaced'>
- $ sudo apt-get install bmap-tools
- </literallayout>
- </note>
- </para></listitem>
- </itemizedlist>
+ For information on BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
</para></listitem>
</orderedlist>
</para>
-
- <para>
- For help on the <filename>bmaptool</filename> command, use either of
- the following commands:
- <literallayout class='monospaced'>
- $ bmaptool --help
- $ oe-run-native bmaptool --help
- </literallayout>
- </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