yocto-project-qs: Added section for CROPS.

(From yocto-docs rev: 0d6fba532e0247db2cce4e94466f4476114d3e13)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2017-07-28 16:40:30 -07:00
committed by Richard Purdie
parent b9a3edf6ce
commit 2f25c9b56c

View File

@@ -44,7 +44,6 @@
</note>
</legalnotice>
<abstract>
<imagedata fileref="figures/yocto-project-transp.png"
width="6in" depth="1in"
@@ -180,163 +179,234 @@
<title>Setting Up to Use the Yocto Project</title>
<para>
The following list shows what you need in order to use a
Linux-based build host to use the Yocto Project to build images:
Setting up to use the Yocto Project involves getting your build
host ready.
If you have a native Linux machine that runs a Yocto Project
supported distribution as described by the
"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
section in the Yocto Project Reference Manual, you can prepare
that machine as your build host.
See the
"<link linkend='qs-native-linux-build-host'>Using a Native Linux Machine</link>"
section for more information.
</para>
<itemizedlist>
<listitem><para><emphasis>Build Host</emphasis>
A build host with a minimum of 50 Gbytes of free disk
space that is running a supported Linux distribution (i.e.
recent releases of Fedora, openSUSE, CentOS, Debian, or
Ubuntu).
</para></listitem>
<listitem><para><emphasis>Build Host Packages</emphasis>
Appropriate packages installed on the build host.
</para></listitem>
<listitem><para><emphasis>The Yocto Project</emphasis>
A release of the Yocto Project.
</para></listitem>
</itemizedlist>
<para>
If you do not want to use the Yocto Project on a native Linux
machine, you can prepare your build host to 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>.
You can set up a build host for Windows, Mac, and Linux
machines.
See the
"<link linkend='qs-crops-build-host'>Using CROPS and Containers</link>"
section for more information.
</para>
<section id='the-linux-distro'>
<title>The Linux Distribution</title>
<section id='qs-crops-build-host'>
<title>Using CROPS and Containers</title>
<para>
The Yocto Project team verifies each release against recent
versions of the most popular Linux distributions that
provide stable releases.
In general, if you have the current release minus one of the
following distributions, you should have no problems.
<itemizedlist>
Follow these steps to get your build host set up with a
Poky container that you can use to complete the build
examples further down in the Quick Start:
<orderedlist>
<listitem><para>
Ubuntu
<emphasis>Reference the Procedure:</emphasis>
Work through the first six steps of the procedure
in the
"<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"
section of the Yocto Project Development Manual.
</para></listitem>
<listitem><para>
Fedora
</para></listitem>
<listitem><para>
openSUSE
</para></listitem>
<listitem><para>
CentOS
</para></listitem>
<listitem><para>
Debian
</para></listitem>
</itemizedlist>
For a more detailed list of distributions that support the
Yocto Project, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
section in the Yocto Project Reference Manual.
</para>
<emphasis>Set Up the Poky Container to Use the Yocto Project:</emphasis>
Go to
<ulink url='https://github.com/crops/poky-container/blob/master/README.md'></ulink>
and follow the directions to set up the Poky container
on your build host.</para>
<para>
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>Once you complete the setup instructions for your
machine, you need to get a copy of the
<filename>poky</filename> repository on your build
host.
See the
"<link linkend='releases'>Yocto Project Release</link>"
section to continue.
</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.
</orderedlist>
</para>
</section>
<section id='packages'>
<title>The Build Host Packages</title>
<section id='qs-native-linux-build-host'>
<title>Using a Native Linux Machine</title>
<para>
Required build host packages vary depending on your
build machine and what you want to do with the Yocto Project.
For example, if you want to build an image that can run
on QEMU in graphical mode (a minimal, basic build
requirement), then the build host package requirements
are different than if you want to build an image on a headless
system or build out the Yocto Project documentation set.
The following list shows what you need in order to use a
Linux-based build host to use the Yocto Project to build images:
</para>
<para>
Collectively, the number of required packages is large
if you want to be able to cover all cases.
<note>
In general, you need to have root access and then install
the required packages.
Thus, the commands in the following section may or may
not work depending on whether or not your Linux
distribution has <filename>sudo</filename> installed.
</note>
</para>
<itemizedlist>
<listitem><para><emphasis>Build Host</emphasis>
A build host with a minimum of 50 Gbytes of free disk
space that is running a supported Linux distribution (i.e.
recent releases of Fedora, openSUSE, CentOS, Debian, or
Ubuntu).
</para></listitem>
<listitem><para><emphasis>Build Host Packages</emphasis>
Appropriate packages installed on the build host.
</para></listitem>
</itemizedlist>
<para>
The following list shows the required packages needed to build
an image that runs on QEMU in graphical mode (e.g. essential
plus graphics support).
For lists of required packages for other 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.
<itemizedlist>
<listitem><para><emphasis>Ubuntu and Debian</emphasis>
<literallayout class='monospaced'>
<section id='the-linux-distro'>
<title>The Linux Distribution</title>
<para>
The Yocto Project team verifies each release against recent
versions of the most popular Linux distributions that
provide stable releases.
In general, if you have the current release minus one of the
following distributions, you should have no problems.
<itemizedlist>
<listitem><para>
Ubuntu
</para></listitem>
<listitem><para>
Fedora
</para></listitem>
<listitem><para>
openSUSE
</para></listitem>
<listitem><para>
CentOS
</para></listitem>
<listitem><para>
Debian
</para></listitem>
</itemizedlist>
For a more detailed list of distributions that support the
Yocto Project, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
section in the Yocto Project Reference Manual.
</para>
<para>
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>
</section>
<section id='packages'>
<title>The Build Host Packages</title>
<para>
Required build host packages vary depending on your
build machine and what you want to do with the Yocto Project.
For example, if you want to build an image that can run
on QEMU in graphical mode (a minimal, basic build
requirement), then the build host package requirements
are different than if you want to build an image on a headless
system or build out the Yocto Project documentation set.
</para>
<para>
Collectively, the number of required packages is large
if you want to be able to cover all cases.
<note>
In general, you need to have root access and then install
the required packages.
Thus, the commands in the following section may or may
not work depending on whether or not your Linux
distribution has <filename>sudo</filename> installed.
</note>
</para>
<para>
The following list shows the required packages needed to build
an image that runs on QEMU in graphical mode (e.g. essential
plus graphics support).
For lists of required packages for other 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.
<itemizedlist>
<listitem><para><emphasis>Ubuntu and Debian</emphasis>
<literallayout class='monospaced'>
$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
</literallayout>
</para></listitem>
<listitem><para><emphasis>Fedora</emphasis>
<literallayout class='monospaced'>
</literallayout>
</para></listitem>
<listitem><para><emphasis>Fedora</emphasis>
<literallayout class='monospaced'>
$ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
</literallayout>
</para></listitem>
<listitem><para><emphasis>OpenSUSE</emphasis>
<literallayout class='monospaced'>
</literallayout>
</para></listitem>
<listitem><para><emphasis>OpenSUSE</emphasis>
<literallayout class='monospaced'>
$ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
</literallayout>
</para></listitem>
<listitem><para><emphasis>CentOS</emphasis>
<literallayout class='monospaced'>
</literallayout>
</para></listitem>
<listitem><para><emphasis>CentOS</emphasis>
<literallayout class='monospaced'>
$ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
</literallayout>
<note><title>Notes</title>
<itemizedlist>
<listitem><para>
CentOS 6.x users need to ensure that the
required versions of Git, tar and Python
are available.
For details, 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>
Extra Packages for Enterprise Linux
(i.e. <filename>epel-release</filename>)
is a collection of packages from Fedora
built on RHEL/CentOS for easy installation
of packages not included in enterprise
Linux by default.
You need to install these packages
separately.
</para></listitem>
<listitem><para>
The <filename>makecache</filename> command
consumes additional Metadata from
<filename>epel-release</filename>.
</para></listitem>
</itemizedlist>
</note>
</para></listitem>
</itemizedlist>
</literallayout>
<note><title>Notes</title>
<itemizedlist>
<listitem><para>
CentOS 6.x users need to ensure that the
required versions of Git, tar and Python
are available.
For details, 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>
Extra Packages for Enterprise Linux
(i.e. <filename>epel-release</filename>)
is a collection of packages from Fedora
built on RHEL/CentOS for easy installation
of packages not included in enterprise
Linux by default.
You need to install these packages
separately.
</para></listitem>
<listitem><para>
The <filename>makecache</filename> command
consumes additional Metadata from
<filename>epel-release</filename>.
</para></listitem>
</itemizedlist>
</note>
</para></listitem>
</itemizedlist>
</para>
</section>
<para>
Once you complete the setup instructions for your
machine, you need to get a copy of the
<filename>poky</filename> repository on your build
host.
Continue with the
"<link linkend='releases'>Yocto Project Release</link>"
section.
</para>
</section>
@@ -344,8 +414,9 @@
<title>Yocto Project Release</title>
<para>
The last requirement you need to meet before using the
Yocto Project is getting a Yocto Project release.
Now that your build host has the right packages (native
Linux machine) or you have the Poky container set up
(CROPS), you need to get a copy of the Yocto Project.
It is recommended that you get the latest Yocto Project release
by setting up (cloning in
<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> terms) a
@@ -356,9 +427,14 @@
</para>
<para>
Here is an example from an Ubuntu build host that clones the
<filename>poky</filename> repository and then checks out the
latest Yocto Project Release by tag
Here is an example from a native Linux machine that is
running Ubuntu.
<note>
If your build host is using a Poky container, you can
use the same Git commands.
</note>
The example clones the <filename>poky</filename> repository
and then checks out the latest Yocto Project Release by tag
(i.e. <filename>&DISTRO_REL_TAG;</filename>):
<literallayout class='monospaced'>
$ git clone git://git.yoctoproject.org/poky
@@ -404,20 +480,21 @@
<title>Building Images</title>
<para>
Now that you have your system requirements in order, you can give
Yocto Project a try.
You can try out Yocto Project using either the command-line
interface or using Toaster, which uses a graphical user
interface.
If you want to try out the Yocto Project using a GUI, see the
<ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
for information on how to install and set up Toaster.
You are now ready to give the Yocto Project a try.
For this example, you will be using the command line to build
your images.
<note>
A graphical user interface to the Yocto Project is available
through Toaster.
See the
<ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
for more information.
</note>
</para>
<para>
To use the Yocto Project through the command-line interface,
finish this quick start, which presents steps that let you
do the following:
The remainder of this quick start steps you through the
following:
<itemizedlist>
<listitem><para>
Build a <filename>qemux86</filename> reference image
@@ -477,7 +554,8 @@
<para>
<orderedlist>
<listitem><para><emphasis>Be Sure Your Build Host is Set Up:</emphasis>
<listitem><para>
<emphasis>Be Sure Your Build Host is Set Up:</emphasis>
The steps to build an image in this section depend on
your build host being properly set up.
Be sure you have worked through the requirements
@@ -485,7 +563,8 @@
"<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>"
section.
</para></listitem>
<listitem><para><emphasis>Check Out Your Branch:</emphasis>
<listitem><para>
<emphasis>Check Out Your Branch:</emphasis>
Be sure you are in the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
(e.g. <filename>poky</filename>) and then check out
@@ -505,7 +584,8 @@
branch ensures you are using the latest files for
that release.
</para></listitem>
<listitem><para><emphasis>Initialize the Build Environment:</emphasis>
<listitem><para>
<emphasis>Initialize the Build Environment:</emphasis>
Run the
<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
environment setup script to define the OpenEmbedded
@@ -530,7 +610,8 @@
setup script.
</note>
</para></listitem>
<listitem><para><emphasis>Examine Your Local Configuration File:</emphasis>
<listitem><para>
<emphasis>Examine Your Local Configuration File:</emphasis>
When you set up the build environment, a local
configuration file named
<filename>local.conf</filename> becomes available in
@@ -584,7 +665,8 @@
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para><emphasis>Start the Build:</emphasis>
<listitem><para>
<emphasis>Start the Build:</emphasis>
Continue with the following command to build an OS image
for the target, which is
<filename>core-image-sato</filename> in this example:
@@ -642,7 +724,8 @@
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
chapter in the Yocto Project Reference Manual.
</para></listitem>
<listitem><para><emphasis>Simulate Your Image Using QEMU:</emphasis>
<listitem><para>
<emphasis>Simulate Your Image Using QEMU:</emphasis>
Once this particular image is built, you can start QEMU
and run the image:
<literallayout class='monospaced'>
@@ -652,7 +735,8 @@
"<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"
chapter in the Yocto Project Development Manual.
</para></listitem>
<listitem><para><emphasis>Exit QEMU:</emphasis>
<listitem><para>
<emphasis>Exit QEMU:</emphasis>
Exit QEMU by either clicking on the shutdown icon or by
typing <filename>Ctrl-C</filename> in the QEMU
transcript window from which you evoked QEMU.
@@ -682,7 +766,8 @@
<para>
<orderedlist>
<listitem><para><emphasis>Create a Local Copy of the
<listitem><para>
<emphasis>Create a Local Copy of the
<filename>meta-intel</filename> Repository:</emphasis>
Building an image for the MinnowBoard Turbot requires
the
@@ -731,7 +816,8 @@
"meta-intel-&DISTRO_NAME_NO_CAP;-&YOCTO_DOC_VERSION;"
in the above example.
</para></listitem>
<listitem><para><emphasis>Configure the Build:</emphasis>
<listitem><para>
<emphasis>Configure the Build:</emphasis>
To configure the build, you edit the
<filename>bblayers.conf</filename> and
<filename>local.conf</filename> files, both of which are
@@ -836,7 +922,8 @@
tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.wic
</literallayout>
</para></listitem>
<listitem><para><emphasis>Write the Image:</emphasis>
<listitem><para>
<emphasis>Write the Image:</emphasis>
You can write the image just built to a bootable media
(e.g. a USB key, SATA drive, SD card, etc.) using the
<filename>dd</filename> utility:
@@ -850,7 +937,8 @@
<filename>/dev/mmcblk0</filename>, which is most likely an
SD card).
</para></listitem>
<listitem><para><emphasis>Boot the Hardware:</emphasis>
<listitem><para>
<emphasis>Boot the Hardware:</emphasis>
With the boot device provisioned, you can insert the
media into the MinnowBoard Turbot and boot the hardware.
The board should automatically detect the media and boot to
@@ -914,7 +1002,7 @@
<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>,
which are used primarily for application development.
This manual also provides example workflows
that use the popular <trademark class='trad'>Eclipse</trademark>
that use the popular <trademark class='trade'>Eclipse</trademark>
development environment and that use <filename>devtool</filename>.
See the
"<ulink url='&YOCTO_DOCS_SDK_URL;#workflow-using-eclipse'>Workflow using Eclipse™</ulink>"