documentation/adt-manual/adt-prepare.xml: Updates to ADT install steps

Significant re-write to every section in this chapter except the
"Setting Up the Environment" and "Kernels and Filesystem Images"
chapters.  I established some terms to communicate the build and
source trees and the build and source top-level directories for
YP.  These terms had not been consitently communicated.  I also
stepped through each of the three methods by which a user can
install ADT (and the cross-toolchain) and meticulously documented
the steps.  The result is a much more complete and clear set
of procedures.

(From yocto-docs rev: 37076a07ccc748ceb416c4bc3a57b698f6e8d80a)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2011-06-23 07:24:43 -07:00 committed by Richard Purdie
parent bb07dfe662
commit 231f6bc327
1 changed files with 248 additions and 144 deletions

View File

@ -6,74 +6,159 @@
<title>Preparing to Use the Application Development Toolkit (ADT)</title> <title>Preparing to Use the Application Development Toolkit (ADT)</title>
<para> <para>
In order to use the ADT it must be installed, the environment setup script must be In order to use the ADT you must install it, source a script to set up the
sourced, and the kernel and filesystem image specific to the target architecture must exist. environment, and be sure the kernel and filesystem image specific to the target architecture
This section describes how to install the ADT, set up the environment, and provides exists.
some reference information on kernels and filesystem images. </para>
<para>
This section describes how to be sure you meet these requirements.
Througout this section two important terms are used:
<itemizedlist>
<listitem><para><emphasis>Yocto Project Source Tree:</emphasis>
This term refers to the directory structure created as a result of downloading
and unpacking a Yocto Project release tarball.
The Yocto Project source tree contains Bitbake, Documentation, Meta-data and
other files.
The name of the top-level directory of the Yocto Project source tree
is derived from the Yocto Project release tarball.
For example, downloading and unpacking <filename>poky-bernard-5.0.1.tar.bz2</filename>
results in a Yocto Project source tree whose Yocto Project source directory is named
<filename>poky-bernard-5.0.1</filename>.</para></listitem>
<listitem><para><emphasis>Yocto Project Build Tree:</emphasis>
This term refers to the area where you run your builds.
The area is created when you source the Yocto Project setup environment script
that is found in the Yocto Project source directory
(e.g. <filename>poky-init-build-env</filename>).
You can create the Yocto Project build tree anywhere you want on your
development system.
Here is an example that creates the tree in <filename>mybuilds</filename>
and names the Yocto Project build directory <filename>YP-5.0.1</filename>:
<literallayout class='monospaced'>
$ source poky-bernard-5.0.1/poky-init-build-env $HOME/mybuilds/YP-5.0.1
</literallayout>
If you don't specifically name the build directory then Bitbake creates it
in the current directory and uses the name <filename>build</filename>.
Also, if you supply an existing directory then Bitbake uses that
directory as the Yocto Project build directory and populates the build tree
beneath it.</para></listitem>
</itemizedlist>
</para> </para>
<section id='installing-the-adt'> <section id='installing-the-adt'>
<title>Installing the ADT</title> <title>Installing the ADT</title>
<para>
You can install the ADT three ways.
However, we recommend configuring and running the ADT Installer script.
Running this script automates much of the process for you.
For example, the script allows you to install the QEMU emulator and
user-space NFS, define which root filesystem profiles to download,
and allows you to define the target sysroot location.
</para>
<note>
If you need to generate the ADT tarball you can do so using the following command:
<literallayout class='monospaced'>
$ bitbake adt-installer
</literallayout>
This command generates the file <filename>adt-installer.tar.bz2</filename>
in the <filename>../build/tmp/deploy/sdk</filename> directory.
</note>
<section id='configuring-and-running-the-adt-installer'> <para>
<title>Configuring and Running the ADT Installer</title> The following list describes how you can install the ADT, which includes the cross-toolchain.
Regardless of the installation you choose, however, you must source the cross-toolchain
environment setup script before you use the toolchain.
See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
section for more information.
<itemizedlist>
<listitem><para><emphasis>Use the ADT Installer Script:</emphasis>
This method is the recommended way to install the ADT because it
automates much of the process for you.
For example, you can configure the installation to install the QEMU emulator
and the user-space NFS, specify which root filesystem profiles to download,
and define the target sysroot location.
</para></listitem>
<listitem><para><emphasis>Use an Existing Toolchain Tarball:</emphasis>
Using this method you select and download an architecture-specific
toolchain tarball and then hand-install the toolchain.
If you use this method you just get the cross-toolchain and QEMU - you do not
get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
<listitem><para><emphasis>Use the Toolchain from Within a Yocto Project Build Tree:</emphasis>
If you already have a Yocto Project build tree you can install the cross-toolchain
using that tree.
However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
do not get any of the other benefits without taking separate steps.</para></listitem>
</itemizedlist>
</para>
<section id='using-the-adt-installer'>
<title>Using the ADT Installer</title>
<para> <para>
The ADT Installer is contained in a tarball that can be built using To run the ADT Installer you need to first get the ADT Installer tarball and then run the ADT
<filename>bitbake adt-installer</filename>. Installer Script.
Yocto Project has a pre-built ADT Installer tarball that you can download
from <filename>tmp/deploy/sdk</filename> located in the build directory.
</para> </para>
<note> <section id='getting-the-adt-installer-tarball'>
You can install and run the ADT Installer tarball in any directory you want. <title>Getting the ADT Installer Tarball</title>
</note>
<para> <para>
Before running the ADT Installer you need to configure it by editing The ADT Installer is contained in the ADT Installer tarball.
the <filename>adt-installer.conf</filename> file, which is located in the You can download the tarball into any directory from
directory where the ADT Installer tarball was installed. <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/adt-installer/'></ulink>.
Your configurations determine which kernel and filesystem image are downloaded. Or, you can use Bitbake to generate the tarball inside the existing Yocto Project build tree.
The following list describes the variables you can define for the ADT Installer. </para>
For configuration values and restrictions see the comments in
the <filename>adt-installer.conf</filename> file:
<itemizedlist> <para>
<listitem><para><filename>YOCTOADT_IPKG_REPO</filename> This area If you use Bitbake to generate the ADT Installer tarball, you must
includes the IPKG-based packages and the root filesystem upon which source the Yocto Project environment setup script located in the Yocto Project
the installation is based. source directory before running the Bitbake command that creates the tarball.
If you want to set up your own IPKG repository pointed to by </para>
<filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the
directory structure follows the same layout as the reference directory <para>
set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>. The following example commands download the Yocto Project release tarball, create the Yocto
Also, your repository needs to be accessible through HTTP. Project source tree, set up the environment while also creating the Yocto Project build tree,
</para></listitem> and finally run the Bitbake command that results in the tarball
<listitem><para><filename>YOCTOADT-TARGETS</filename> The machine <filename>~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
target architectures for which you want to set up cross-development <literallayout class='monospaced'>
environments. $ cd ~
</para></listitem> $ mkdir yocto-project
<listitem><para><filename>YOCTOADT_QEMU</filename> Indicates whether $ cd yocto-project
or not to install the emulator QEMU. $ wget http://www.yoctoproject.org/downloads/poky/poky-bernard-5.0.1.tar.bz2
</para></listitem> $ tar xjf poky-bernard-5.0.1.tar.bz2
<listitem><para><filename>YOCTOADT_NFS_UTIL</filename> Indicates whether $ source poky-bernard-5.0.1/poky-init-build-env poky-5.0.1-build
or not to install user-mode NFS. $ bitbake adt-installer
If you plan to use the Yocto Eclipse IDE plug-in against QEMU, </literallayout>
you should install NFS. </para>
</section>
<section id='configuring-and-running-the-adt-installer-script'>
<title>Configuring and Running the ADT Installer Script</title>
<para>
Before running the ADT Installer script you need to unpack the tarball.
You can unpack the tarball in any directory you wish.
Unpacking it creates the directory <filename>adt-installer</filename>,
which contains the ADT Installer script and its configuration file.
</para>
<para>
Before you run the script, however, you should examine the ADT Installer configuration
file (<filename>adt_installer</filename>) and be sure you are going to get what you want.
Your configurations determine which kernel and filesystem image are downloaded.
</para>
<para>
The following list describes the configurations you can define for the ADT Installer.
For configuration values and restrictions see the comments in
the <filename>adt-installer.conf</filename> file:
<itemizedlist>
<listitem><para><filename>YOCTOADT_IPKG_REPO</filename> This area
includes the IPKG-based packages and the root filesystem upon which
the installation is based.
If you want to set up your own IPKG repository pointed to by
<filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the
directory structure follows the same layout as the reference directory
set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
Also, your repository needs to be accessible through HTTP.
</para></listitem>
<listitem><para><filename>YOCTOADT-TARGETS</filename> The machine
target architectures for which you want to set up cross-development
environments.
</para></listitem>
<listitem><para><filename>YOCTOADT_QEMU</filename> Indicates whether
or not to install the emulator QEMU.
</para></listitem>
<listitem><para><filename>YOCTOADT_NFS_UTIL</filename> Indicates whether
or not to install user-mode NFS.
If you plan to use the Yocto Eclipse IDE plug-in against QEMU,
you should install NFS.
<note> <note>
To boot QEMU images using our userspace NFS server, you need To boot QEMU images using our userspace NFS server, you need
to be running portmap or rpcbind. to be running portmap or rpcbind.
@ -83,112 +168,131 @@
Your firewall settings may also have to be modified to allow Your firewall settings may also have to be modified to allow
NFS booting to work. NFS booting to work.
</note> </note>
</para></listitem> </para></listitem>
<listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root
filesystem images you want to download. filesystem images you want to download.
</para></listitem> </para></listitem>
<listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The
root filesystem used to extract and create the target sysroot. root filesystem used to extract and create the target sysroot.
</para></listitem> </para></listitem>
<listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The
location of the target sysroot that will be set up on the development machine. location of the target sysroot that will be set up on the development machine.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
After you have configured the <filename>adt-installer.conf</filename> file, After you have configured the <filename>adt_installer.conf</filename> file,
run the installer using the following command: run the installer using the following command:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ adt_installer $ adt_installer
</literallayout> </literallayout>
</para> </para>
<para> <note>
Once the installer begins to run you are asked whether you want to run in The ADT Installer requires the <filename>libtool</filename> package to complete.
interactive or silent mode. If you install the recommended packages as described in the
If you want to closely monitor the installation then choose “I” for interactive <ulink url='http://www.yoctoproject.org/docs/yocto-project-qs/yocto-project-qs.html'>
mode rather than “S” for silent mode. Yocto Project Quick Start</ulink> then you will have libtool installed.
Follow the prompts from the script to complete the installation. </note>
</para>
<para> <para>
Once the installation completes, the cross-toolchain is installed in Once the installer begins to run you are asked whether you want to run in
<filename>/opt/poky/$SDKVERSION</filename>. interactive or silent mode.
</para> If you want to closely monitor the installation then choose “I” for interactive
mode rather than “S” for silent mode.
Follow the prompts from the script to complete the installation.
</para>
<para> <para>
Before using the ADT you need to run the environment setup script for Once the installation completes, the ADT, which includes the cross-toolchain, is installed.
your target architecture also located in <filename>/opt/poky/$SDKVERSION</filename>. You will notice environment setup files for the cross-toolchain in
See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> <filename>/opt/poky/$SDKVERSION</filename>,
section for information. and image tarballs in the <filename>adt-installer</filename>
</para> directory according to your installer configurations, and the target sysroot located
according to the <filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> variable
also in your configuration file.
</para>
</section>
</section> </section>
<section id='using-an-existing-toolchain-tarball'> <section id='using-an-existing-toolchain-tarball'>
<title>Using an Existing Toolchain Tarball</title> <title>Using a Cross-Toolchain Tarball</title>
<para>
If you want to simply install the cross-toolchain by hand you can do so by using an existing
cross-toolchain tarball.
If you install the cross-toolchain by hand you will have to set up the sysroot separately.
</para>
<para> <para>
If you do not want to use the ADT Installer you can install the toolchain
and the sysroot by hand.
Follow these steps: Follow these steps:
<orderedlist> <orderedlist>
<listitem><para>Locate and download the architecture-specific toolchain <listitem><para>Go to
tarball from <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0'></ulink>. <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/toolchain'></ulink>
Look in the toolchain folder and then open up the folder that matches your and find the folder that matches your host development system
host development system (i.e. 'i686' for 32-bit machines or 'x86_64' (i.e. 'i686' for 32-bit machines or 'x86_64' for 64-bit machines).</para>
for 64-bit machines). </listitem>
Then, select the toolchain tarball whose name includes the appropriate <listitem><para>Go into that folder and download the toolchain tarball whose name
target architecture. includes the appropriate target architecture.
For example, if your host development system is an Intel-based 64-bit system and
you are going to use your cross-toolchain for an arm target go into the
<filename>x86_64</filename> folder and download the following tarball:
<literallayout class='monospaced'>
yocto-eglibc-x86_64-arm-toolchain-gmae-1.0.tar.bz2
</literallayout>
<note> <note>
If you need to build the toolchain tarball use the Alternatively you can build the toolchain tarball if you have a Yocto Project build tree.
<filename>bitbake meta-toolchain</filename> command after you have Use the <filename>bitbake meta-toolchain</filename> command after you have
sourced the poky-build-init script. sourced the <filename>poky-build-init script</filename> located in the Yocto Project
The tarball will be located in the build directory at source directory.
<filename>tmp/deploy/sdk</filename> after the build. When the <filename>bitbake</filename> command completes the toolchain tarball will
</note> be in <filename>tmp/deploy/sdk</filename> in the Yocto Project build tree.
</para></listitem> </note></para></listitem>
<listitem><para>Make sure you are in the root directory and then expand <listitem><para>Make sure you are in the root directory and then expand
the tarball. the tarball.
The tarball expands into the <filename>/opt/poky/$SDKVERSION</filename> directory. The tarball expands into <filename>/opt/poky/$SDKVERSION</filename>.
</para></listitem> Once the tarball in unpacked the cross-toolchain is installed.
<listitem><para>Set up the environment by sourcing the environment set up You will notice environment setup files for the cross-toolchain in the directory.
script.
See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
for information.
</para></listitem> </para></listitem>
</orderedlist> </orderedlist>
</para> </para>
</section> </section>
<section id='using-the-toolchain-from-within-the-build-tree'> <section id='using-the-toolchain-from-within-the-build-tree'>
<title>Using the Toolchain from Within the Build Tree</title> <title>Using Bitbake and the Yocto Project Build Tree</title>
<para> <para>
A final way of accessing the toolchain is from the build tree. A final way of installing just the cross-toolchain is to use Bitbake within an existing
The build tree can be set up to contain the architecture-specific cross toolchain. Yocto Project build tree.
To populate the build tree with the toolchain you need to run the following command: Follow these steps:
<literallayout class='monospaced'> <orderedlist>
$ bitbake meta-ide-support <listitem><para>Source the environment setup script located in the Yocto Project
</literallayout> source directory.
</para> The script has the string <filename>init-build-env</filename>
as part of the name.</para></listitem>
<para> <listitem><para>At this point you should be sure that the
Before running the command you need to be sure that the <filename>MACHINE</filename> variable
<filename>conf/local.conf</filename> file in the build directory has in the <filename>local.conf</filename> file is set for the target architecture.
the desired architecture specified for the <filename>MACHINE</filename> You can find the <filename>local.conf</filename> file in the Yocto Project source
variable. directory.
See the <filename>local.conf</filename> file for a list of values you Comments within the <filename>local.conf</filename> file list the values you
can supply for this variable. can use for the <filename>MACHINE</filename> variable.
You can populate the build tree with the cross-toolchains for more <note>You can populate the build tree with the cross-toolchains for more
than a single architecture. than a single architecture.
You just need to edit the <filename>local.conf</filename> file and re-run You just need to edit the <filename>MACHINE</filename> variable in the
the BitBake command. <filename>local.conf</filename> file and re-run the BitBake command.</note></para></listitem>
</para> <listitem><para>Run <filename>bitbake meta-ide-support</filename> to complete the
cross-toolchain installation.
<para> <note>If you change your working directory after you source the environment
Once the build tree has the toolchain you need to source the environment setup script and before you run the Bitbake command the command will not work.
setup script so that you can run the cross-tools without having to locate them. Be sure to run the Bitbake command immediately after checking or editing the
See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> <filename>local.conf</filename> but without changing your working directory.</note>
for information. Once Bitbake finishes, the cross-toolchain is installed.
You will notice environment setup files for the cross-toolchain in the
Yocto Project build tree in the <filename>tmp</filename> directory.
Setup script filenames contain the strings <filename>environment-setup</filename>.
</para></listitem>
</orderedlist>
</para> </para>
</section> </section>
</section> </section>
@ -196,7 +300,7 @@
<section id='setting-up-the-environment'> <section id='setting-up-the-environment'>
<title>Setting Up the Environment</title> <title>Setting Up the Environment</title>
<para> <para>
Before you can use the cross-toolchain you need to set up the environment by Before you can use the cross-toolchain you need to set up the toolchain environment by
sourcing the environment setup script. sourcing the environment setup script.
If you used adt_installer or used an existing ADT tarball to install the ADT, If you used adt_installer or used an existing ADT tarball to install the ADT,
then you can find this script in the <filename>/opt/poky/$SDKVERSION</filename> then you can find this script in the <filename>/opt/poky/$SDKVERSION</filename>