summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-06-23 07:24:43 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-06-24 11:27:42 +0100
commit231f6bc327d76d541dbac565ea00987d2245f9d0 (patch)
tree023b501de09ce8a76d4522a66c4fa3056fd3767e /documentation
parentbb07dfe66274960f1ddb53323039d81ccd86b418 (diff)
downloadpoky-231f6bc327d76d541dbac565ea00987d2245f9d0.tar.gz
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/adt-manual/adt-prepare.xml390
1 files changed, 247 insertions, 143 deletions
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
index f27f603e1d..99085d2ae5 100644
--- a/documentation/adt-manual/adt-prepare.xml
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -6,74 +6,159 @@
6<title>Preparing to Use the Application Development Toolkit (ADT)</title> 6<title>Preparing to Use the Application Development Toolkit (ADT)</title>
7 7
8<para> 8<para>
9 In order to use the ADT it must be installed, the environment setup script must be 9 In order to use the ADT you must install it, source a script to set up the
10 sourced, and the kernel and filesystem image specific to the target architecture must exist. 10 environment, and be sure the kernel and filesystem image specific to the target architecture
11 This section describes how to install the ADT, set up the environment, and provides 11 exists.
12 some reference information on kernels and filesystem images. 12</para>
13
14<para>
15 This section describes how to be sure you meet these requirements.
16 Througout this section two important terms are used:
17 <itemizedlist>
18 <listitem><para><emphasis>Yocto Project Source Tree:</emphasis>
19 This term refers to the directory structure created as a result of downloading
20 and unpacking a Yocto Project release tarball.
21 The Yocto Project source tree contains Bitbake, Documentation, Meta-data and
22 other files.
23 The name of the top-level directory of the Yocto Project source tree
24 is derived from the Yocto Project release tarball.
25 For example, downloading and unpacking <filename>poky-bernard-5.0.1.tar.bz2</filename>
26 results in a Yocto Project source tree whose Yocto Project source directory is named
27 <filename>poky-bernard-5.0.1</filename>.</para></listitem>
28 <listitem><para><emphasis>Yocto Project Build Tree:</emphasis>
29 This term refers to the area where you run your builds.
30 The area is created when you source the Yocto Project setup environment script
31 that is found in the Yocto Project source directory
32 (e.g. <filename>poky-init-build-env</filename>).
33 You can create the Yocto Project build tree anywhere you want on your
34 development system.
35 Here is an example that creates the tree in <filename>mybuilds</filename>
36 and names the Yocto Project build directory <filename>YP-5.0.1</filename>:
37 <literallayout class='monospaced'>
38 $ source poky-bernard-5.0.1/poky-init-build-env $HOME/mybuilds/YP-5.0.1
39 </literallayout>
40 If you don't specifically name the build directory then Bitbake creates it
41 in the current directory and uses the name <filename>build</filename>.
42 Also, if you supply an existing directory then Bitbake uses that
43 directory as the Yocto Project build directory and populates the build tree
44 beneath it.</para></listitem>
45 </itemizedlist>
13</para> 46</para>
14 47
15<section id='installing-the-adt'> 48<section id='installing-the-adt'>
16 <title>Installing the ADT</title> 49 <title>Installing the ADT</title>
50
17 <para> 51 <para>
18 You can install the ADT three ways. 52 The following list describes how you can install the ADT, which includes the cross-toolchain.
19 However, we recommend configuring and running the ADT Installer script. 53 Regardless of the installation you choose, however, you must source the cross-toolchain
20 Running this script automates much of the process for you. 54 environment setup script before you use the toolchain.
21 For example, the script allows you to install the QEMU emulator and 55 See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
22 user-space NFS, define which root filesystem profiles to download, 56 section for more information.
23 and allows you to define the target sysroot location. 57 <itemizedlist>
58 <listitem><para><emphasis>Use the ADT Installer Script:</emphasis>
59 This method is the recommended way to install the ADT because it
60 automates much of the process for you.
61 For example, you can configure the installation to install the QEMU emulator
62 and the user-space NFS, specify which root filesystem profiles to download,
63 and define the target sysroot location.
64 </para></listitem>
65 <listitem><para><emphasis>Use an Existing Toolchain Tarball:</emphasis>
66 Using this method you select and download an architecture-specific
67 toolchain tarball and then hand-install the toolchain.
68 If you use this method you just get the cross-toolchain and QEMU - you do not
69 get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
70 <listitem><para><emphasis>Use the Toolchain from Within a Yocto Project Build Tree:</emphasis>
71 If you already have a Yocto Project build tree you can install the cross-toolchain
72 using that tree.
73 However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
74 do not get any of the other benefits without taking separate steps.</para></listitem>
75 </itemizedlist>
24 </para> 76 </para>
25 <note>
26 If you need to generate the ADT tarball you can do so using the following command:
27 <literallayout class='monospaced'>
28 $ bitbake adt-installer
29 </literallayout>
30 This command generates the file <filename>adt-installer.tar.bz2</filename>
31 in the <filename>../build/tmp/deploy/sdk</filename> directory.
32 </note>
33 77
34 <section id='configuring-and-running-the-adt-installer'> 78 <section id='using-the-adt-installer'>
35 <title>Configuring and Running the ADT Installer</title> 79 <title>Using the ADT Installer</title>
80
36 <para> 81 <para>
37 The ADT Installer is contained in a tarball that can be built using 82 To run the ADT Installer you need to first get the ADT Installer tarball and then run the ADT
38 <filename>bitbake adt-installer</filename>. 83 Installer Script.
39 Yocto Project has a pre-built ADT Installer tarball that you can download
40 from <filename>tmp/deploy/sdk</filename> located in the build directory.
41 </para> 84 </para>
42 85
43 <note> 86 <section id='getting-the-adt-installer-tarball'>
44 You can install and run the ADT Installer tarball in any directory you want. 87 <title>Getting the ADT Installer Tarball</title>
45 </note>
46 88
47 <para> 89 <para>
48 Before running the ADT Installer you need to configure it by editing 90 The ADT Installer is contained in the ADT Installer tarball.
49 the <filename>adt-installer.conf</filename> file, which is located in the 91 You can download the tarball into any directory from
50 directory where the ADT Installer tarball was installed. 92 <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/adt-installer/'></ulink>.
51 Your configurations determine which kernel and filesystem image are downloaded. 93 Or, you can use Bitbake to generate the tarball inside the existing Yocto Project build tree.
52 The following list describes the variables you can define for the ADT Installer. 94 </para>
53 For configuration values and restrictions see the comments in 95
54 the <filename>adt-installer.conf</filename> file: 96 <para>
55 97 If you use Bitbake to generate the ADT Installer tarball, you must
56 <itemizedlist> 98 source the Yocto Project environment setup script located in the Yocto Project
57 <listitem><para><filename>YOCTOADT_IPKG_REPO</filename> – This area 99 source directory before running the Bitbake command that creates the tarball.
58 includes the IPKG-based packages and the root filesystem upon which 100 </para>
59 the installation is based. 101
60 If you want to set up your own IPKG repository pointed to by 102 <para>
61 <filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the 103 The following example commands download the Yocto Project release tarball, create the Yocto
62 directory structure follows the same layout as the reference directory 104 Project source tree, set up the environment while also creating the Yocto Project build tree,
63 set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>. 105 and finally run the Bitbake command that results in the tarball
64 Also, your repository needs to be accessible through HTTP. 106 <filename>~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
65 </para></listitem> 107 <literallayout class='monospaced'>
66 <listitem><para><filename>YOCTOADT-TARGETS</filename> – The machine 108 $ cd ~
67 target architectures for which you want to set up cross-development 109 $ mkdir yocto-project
68 environments. 110 $ cd yocto-project
69 </para></listitem> 111 $ wget http://www.yoctoproject.org/downloads/poky/poky-bernard-5.0.1.tar.bz2
70 <listitem><para><filename>YOCTOADT_QEMU</filename> – Indicates whether 112 $ tar xjf poky-bernard-5.0.1.tar.bz2
71 or not to install the emulator QEMU. 113 $ source poky-bernard-5.0.1/poky-init-build-env poky-5.0.1-build
72 </para></listitem> 114 $ bitbake adt-installer
73 <listitem><para><filename>YOCTOADT_NFS_UTIL</filename> – Indicates whether 115 </literallayout>
74 or not to install user-mode NFS. 116 </para>
75 If you plan to use the Yocto Eclipse IDE plug-in against QEMU, 117
76 you should install NFS. 118 </section>
119
120 <section id='configuring-and-running-the-adt-installer-script'>
121 <title>Configuring and Running the ADT Installer Script</title>
122
123 <para>
124 Before running the ADT Installer script you need to unpack the tarball.
125 You can unpack the tarball in any directory you wish.
126 Unpacking it creates the directory <filename>adt-installer</filename>,
127 which contains the ADT Installer script and its configuration file.
128 </para>
129
130 <para>
131 Before you run the script, however, you should examine the ADT Installer configuration
132 file (<filename>adt_installer</filename>) and be sure you are going to get what you want.
133 Your configurations determine which kernel and filesystem image are downloaded.
134 </para>
135
136 <para>
137 The following list describes the configurations you can define for the ADT Installer.
138 For configuration values and restrictions see the comments in
139 the <filename>adt-installer.conf</filename> file:
140
141 <itemizedlist>
142 <listitem><para><filename>YOCTOADT_IPKG_REPO</filename> – This area
143 includes the IPKG-based packages and the root filesystem upon which
144 the installation is based.
145 If you want to set up your own IPKG repository pointed to by
146 <filename>YOCTOADT_IPKG_REPO</filename>, you need to be sure that the
147 directory structure follows the same layout as the reference directory
148 set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
149 Also, your repository needs to be accessible through HTTP.
150 </para></listitem>
151 <listitem><para><filename>YOCTOADT-TARGETS</filename> – The machine
152 target architectures for which you want to set up cross-development
153 environments.
154 </para></listitem>
155 <listitem><para><filename>YOCTOADT_QEMU</filename> – Indicates whether
156 or not to install the emulator QEMU.
157 </para></listitem>
158 <listitem><para><filename>YOCTOADT_NFS_UTIL</filename> – Indicates whether
159 or not to install user-mode NFS.
160 If you plan to use the Yocto Eclipse IDE plug-in against QEMU,
161 you should install NFS.
77 <note> 162 <note>
78 To boot QEMU images using our userspace NFS server, you need 163 To boot QEMU images using our userspace NFS server, you need
79 to be running portmap or rpcbind. 164 to be running portmap or rpcbind.
@@ -83,112 +168,131 @@
83 Your firewall settings may also have to be modified to allow 168 Your firewall settings may also have to be modified to allow
84 NFS booting to work. 169 NFS booting to work.
85 </note> 170 </note>
86 </para></listitem> 171 </para></listitem>
87 <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root 172 <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename> - The root
88 filesystem images you want to download. 173 filesystem images you want to download.
89 </para></listitem> 174 </para></listitem>
90 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The 175 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename> - The
91 root filesystem used to extract and create the target sysroot. 176 root filesystem used to extract and create the target sysroot.
92 </para></listitem> 177 </para></listitem>
93 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The 178 <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> - The
94 location of the target sysroot that will be set up on the development machine. 179 location of the target sysroot that will be set up on the development machine.
95 </para></listitem> 180 </para></listitem>
96 </itemizedlist> 181 </itemizedlist>
97 </para> 182 </para>
98 183
99 <para> 184 <para>
100 After you have configured the <filename>adt-installer.conf</filename> file, 185 After you have configured the <filename>adt_installer.conf</filename> file,
101 run the installer using the following command: 186 run the installer using the following command:
102 <literallayout class='monospaced'> 187 <literallayout class='monospaced'>
103 $ adt_installer 188 $ adt_installer
104 </literallayout> 189 </literallayout>
105 </para> 190 </para>
106 191
107 <para> 192 <note>
108 Once the installer begins to run you are asked whether you want to run in 193 The ADT Installer requires the <filename>libtool</filename> package to complete.
109 interactive or silent mode. 194 If you install the recommended packages as described in the
110 If you want to closely monitor the installation then choose “I” for interactive 195 <ulink url='http://www.yoctoproject.org/docs/yocto-project-qs/yocto-project-qs.html'>
111 mode rather than “S” for silent mode. 196 Yocto Project Quick Start</ulink> then you will have libtool installed.
112 Follow the prompts from the script to complete the installation. 197 </note>
113 </para>
114 198
115 <para> 199 <para>
116 Once the installation completes, the cross-toolchain is installed in 200 Once the installer begins to run you are asked whether you want to run in
117 <filename>/opt/poky/$SDKVERSION</filename>. 201 interactive or silent mode.
118 </para> 202 If you want to closely monitor the installation then choose “I” for interactive
203 mode rather than “S” for silent mode.
204 Follow the prompts from the script to complete the installation.
205 </para>
119 206
120 <para> 207 <para>
121 Before using the ADT you need to run the environment setup script for 208 Once the installation completes, the ADT, which includes the cross-toolchain, is installed.
122 your target architecture also located in <filename>/opt/poky/$SDKVERSION</filename>. 209 You will notice environment setup files for the cross-toolchain in
123 See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> 210 <filename>/opt/poky/$SDKVERSION</filename>,
124 section for information. 211 and image tarballs in the <filename>adt-installer</filename>
125 </para> 212 directory according to your installer configurations, and the target sysroot located
213 according to the <filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename> variable
214 also in your configuration file.
215 </para>
216
217 </section>
126 </section> 218 </section>
127 219
128 <section id='using-an-existing-toolchain-tarball'> 220 <section id='using-an-existing-toolchain-tarball'>
129 <title>Using an Existing Toolchain Tarball</title> 221 <title>Using a Cross-Toolchain Tarball</title>
222 <para>
223 If you want to simply install the cross-toolchain by hand you can do so by using an existing
224 cross-toolchain tarball.
225 If you install the cross-toolchain by hand you will have to set up the sysroot separately.
226 </para>
227
130 <para> 228 <para>
131 If you do not want to use the ADT Installer you can install the toolchain
132 and the sysroot by hand.
133 Follow these steps: 229 Follow these steps:
134 <orderedlist> 230 <orderedlist>
135 <listitem><para>Locate and download the architecture-specific toolchain 231 <listitem><para>Go to
136 tarball from <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0'></ulink>. 232 <ulink url='http://autobuilder.yoctoproject.org/downloads/yocto-1.0/toolchain'></ulink>
137 Look in the ‘toolchain’ folder and then open up the folder that matches your 233 and find the folder that matches your host development system
138 host development system (i.e. 'i686' for 32-bit machines or 'x86_64' 234 (i.e. 'i686' for 32-bit machines or 'x86_64' for 64-bit machines).</para>
139 for 64-bit machines). 235 </listitem>
140 Then, select the toolchain tarball whose name includes the appropriate 236 <listitem><para>Go into that folder and download the toolchain tarball whose name
141 target architecture. 237 includes the appropriate target architecture.
238 For example, if your host development system is an Intel-based 64-bit system and
239 you are going to use your cross-toolchain for an arm target go into the
240 <filename>x86_64</filename> folder and download the following tarball:
241 <literallayout class='monospaced'>
242 yocto-eglibc-x86_64-arm-toolchain-gmae-1.0.tar.bz2
243 </literallayout>
142 <note> 244 <note>
143 If you need to build the toolchain tarball use the 245 Alternatively you can build the toolchain tarball if you have a Yocto Project build tree.
144 <filename>bitbake meta-toolchain</filename> command after you have 246 Use the <filename>bitbake meta-toolchain</filename> command after you have
145 sourced the poky-build-init script. 247 sourced the <filename>poky-build-init script</filename> located in the Yocto Project
146 The tarball will be located in the build directory at 248 source directory.
147 <filename>tmp/deploy/sdk</filename> after the build. 249 When the <filename>bitbake</filename> command completes the toolchain tarball will
148 </note> 250 be in <filename>tmp/deploy/sdk</filename> in the Yocto Project build tree.
149 </para></listitem> 251 </note></para></listitem>
150 <listitem><para>Make sure you are in the root directory and then expand 252 <listitem><para>Make sure you are in the root directory and then expand
151 the tarball. 253 the tarball.
152 The tarball expands into the <filename>/opt/poky/$SDKVERSION</filename> directory. 254 The tarball expands into <filename>/opt/poky/$SDKVERSION</filename>.
153 </para></listitem> 255 Once the tarball in unpacked the cross-toolchain is installed.
154 <listitem><para>Set up the environment by sourcing the environment set up 256 You will notice environment setup files for the cross-toolchain in the directory.
155 script.
156 See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref>
157 for information.
158 </para></listitem> 257 </para></listitem>
159 </orderedlist> 258 </orderedlist>
160 </para> 259 </para>
161 </section> 260 </section>
162 261
163 <section id='using-the-toolchain-from-within-the-build-tree'> 262 <section id='using-the-toolchain-from-within-the-build-tree'>
164 <title>Using the Toolchain from Within the Build Tree</title> 263 <title>Using Bitbake and the Yocto Project Build Tree</title>
165 <para>
166 A final way of accessing the toolchain is from the build tree.
167 The build tree can be set up to contain the architecture-specific cross toolchain.
168 To populate the build tree with the toolchain you need to run the following command:
169 <literallayout class='monospaced'>
170 $ bitbake meta-ide-support
171 </literallayout>
172 </para>
173
174 <para>
175 Before running the command you need to be sure that the
176 <filename>conf/local.conf</filename> file in the build directory has
177 the desired architecture specified for the <filename>MACHINE</filename>
178 variable.
179 See the <filename>local.conf</filename> file for a list of values you
180 can supply for this variable.
181 You can populate the build tree with the cross-toolchains for more
182 than a single architecture.
183 You just need to edit the <filename>local.conf</filename> file and re-run
184 the BitBake command.
185 </para>
186
187 <para> 264 <para>
188 Once the build tree has the toolchain you need to source the environment 265 A final way of installing just the cross-toolchain is to use Bitbake within an existing
189 setup script so that you can run the cross-tools without having to locate them. 266 Yocto Project build tree.
190 See the <xref linkend='setting-up-the-environment'>“Setting Up the Environment”</xref> 267 Follow these steps:
191 for information. 268 <orderedlist>
269 <listitem><para>Source the environment setup script located in the Yocto Project
270 source directory.
271 The script has the string <filename>init-build-env</filename>
272 as part of the name.</para></listitem>
273 <listitem><para>At this point you should be sure that the
274 <filename>MACHINE</filename> variable
275 in the <filename>local.conf</filename> file is set for the target architecture.
276 You can find the <filename>local.conf</filename> file in the Yocto Project source
277 directory.
278 Comments within the <filename>local.conf</filename> file list the values you
279 can use for the <filename>MACHINE</filename> variable.
280 <note>You can populate the build tree with the cross-toolchains for more
281 than a single architecture.
282 You just need to edit the <filename>MACHINE</filename> variable in the
283 <filename>local.conf</filename> file and re-run the BitBake command.</note></para></listitem>
284 <listitem><para>Run <filename>bitbake meta-ide-support</filename> to complete the
285 cross-toolchain installation.
286 <note>If you change your working directory after you source the environment
287 setup script and before you run the Bitbake command the command will not work.
288 Be sure to run the Bitbake command immediately after checking or editing the
289 <filename>local.conf</filename> but without changing your working directory.</note>
290 Once Bitbake finishes, the cross-toolchain is installed.
291 You will notice environment setup files for the cross-toolchain in the
292 Yocto Project build tree in the <filename>tmp</filename> directory.
293 Setup script filenames contain the strings <filename>environment-setup</filename>.
294 </para></listitem>
295 </orderedlist>
192 </para> 296 </para>
193 </section> 297 </section>
194</section> 298</section>
@@ -196,7 +300,7 @@
196<section id='setting-up-the-environment'> 300<section id='setting-up-the-environment'>
197 <title>Setting Up the Environment</title> 301 <title>Setting Up the Environment</title>
198 <para> 302 <para>
199 Before you can use the cross-toolchain you need to set up the environment by 303 Before you can use the cross-toolchain you need to set up the toolchain environment by
200 sourcing the environment setup script. 304 sourcing the environment setup script.
201 If you used adt_installer or used an existing ADT tarball to install the ADT, 305 If you used adt_installer or used an existing ADT tarball to install the ADT,
202 then you can find this script in the <filename>/opt/poky/$SDKVERSION</filename> 306 then you can find this script in the <filename>/opt/poky/$SDKVERSION</filename>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-02 18:06:19 +0000