summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-start.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-start.xml')
-rw-r--r--documentation/dev-manual/dev-manual-start.xml238
1 files changed, 119 insertions, 119 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 11d4adca9f..299a02d581 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -7,14 +7,14 @@
7<title>Getting Started with the Yocto Project</title> 7<title>Getting Started with the Yocto Project</title>
8 8
9<para> 9<para>
10 This chapter introduces the Yocto Project and gives you an idea of what you need to get started. 10 This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
11 You can find enough information to set up your development host and build or use images for 11 You can find enough information to set up your development host and build or use images for
12 hardware supported by the Yocto Project by reading the 12 hardware supported by the Yocto Project by reading the
13 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. 13 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
14</para> 14</para>
15 15
16<para> 16<para>
17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides 17 The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
18 some higher-level concepts you might want to consider. 18 some higher-level concepts you might want to consider.
19</para> 19</para>
20 20
@@ -22,24 +22,24 @@
22 <title>Introducing the Yocto Project</title> 22 <title>Introducing the Yocto Project</title>
23 23
24 <para> 24 <para>
25 The Yocto Project is an open-source collaboration project focused on embedded Linux development. 25 The Yocto Project is an open-source collaboration project focused on embedded Linux development.
26 The project currently provides a build system, which is 26 The project currently provides a build system, which is
27 referred to as the OpenEmbedded build system in the Yocto Project documentation. 27 referred to as the OpenEmbedded build system in the Yocto Project documentation.
28 The Yocto Project provides various ancillary tools suitable for the embedded developer 28 The Yocto Project provides various ancillary tools suitable for the embedded developer
29 and also features the Sato reference User Interface, which is optimized for 29 and also features the Sato reference User Interface, which is optimized for
30 stylus driven, low-resolution screens. 30 stylus driven, low-resolution screens.
31 </para> 31 </para>
32 32
33 <para> 33 <para>
34 You can use the OpenEmbedded build system, which uses 34 You can use the OpenEmbedded build system, which uses
35 BitBake to develop complete Linux 35 BitBake to develop complete Linux
36 images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, 36 images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
37 x86 and x86-64. 37 x86 and x86-64.
38 While the Yocto Project does not provide a strict testing framework, 38 While the Yocto Project does not provide a strict testing framework,
39 it does provide or generate for you artifacts that let you perform target-level and 39 it does provide or generate for you artifacts that let you perform target-level and
40 emulated testing and debugging. 40 emulated testing and debugging.
41 Additionally, if you are an <trademark class='trade'>Eclipse</trademark> 41 Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
42 IDE user, you can install an Eclipse Yocto Plug-in to allow you to 42 IDE user, you can install an Eclipse Yocto Plug-in to allow you to
43 develop within that familiar environment. 43 develop within that familiar environment.
44 </para> 44 </para>
45</section> 45</section>
@@ -50,59 +50,59 @@
50 <para> 50 <para>
51 Here is what you need to get set up to use the Yocto Project: 51 Here is what you need to get set up to use the Yocto Project:
52 <itemizedlist> 52 <itemizedlist>
53 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current 53 <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current
54 Linux-based host system. 54 Linux-based host system.
55 You will have the best results with a recent release of Fedora, 55 You will have the best results with a recent release of Fedora,
56 OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project 56 OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
57 and officially supported. 57 and officially supported.
58 For a list of the distributions under validation and their status, see the 58 For a list of the distributions under validation and their status, see the
59 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section 59 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
60 in the Yocto Project Reference Manual and the wiki page at 60 in the Yocto Project Reference Manual and the wiki page at
61 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para> 61 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
62 <para> 62 <para>
63 You should also have about 100 gigabytes of free disk space for building images. 63 You should also have about 100 gigabytes of free disk space for building images.
64 </para></listitem> 64 </para></listitem>
65 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system 65 <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system
66 requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). 66 requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
67 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" 67 See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
68 section in the Yocto Project Quick Start for the exact package 68 section in the Yocto Project Quick Start for the exact package
69 requirements and the installation commands to install them 69 requirements and the installation commands to install them
70 for the supported distributions.</para></listitem> 70 for the supported distributions.</para></listitem>
71 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> 71 <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
72 You need a release of the Yocto Project. 72 You need a release of the Yocto Project.
73 You set up a with local <link linkend='source-directory'>Source Directory</link> 73 You set up a with local <link linkend='source-directory'>Source Directory</link>
74 one of two ways depending on whether you 74 one of two ways depending on whether you
75 are going to contribute back into the Yocto Project or not. 75 are going to contribute back into the Yocto Project or not.
76 <note> 76 <note>
77 Regardless of the method you use, this manual refers to the resulting local 77 Regardless of the method you use, this manual refers to the resulting local
78 hierarchical set of files as the "Source Directory." 78 hierarchical set of files as the "Source Directory."
79 </note> 79 </note>
80 <itemizedlist> 80 <itemizedlist>
81 <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute 81 <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute
82 back into the Yocto Project, you can simply download a Yocto Project release you want 82 back into the Yocto Project, you can simply download a Yocto Project release you want
83 from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>. 83 from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>.
84 Once you have the tarball, just extract it into a directory of your choice.</para> 84 Once you have the tarball, just extract it into a directory of your choice.</para>
85 <para>For example, the following command extracts the Yocto Project &DISTRO; 85 <para>For example, the following command extracts the Yocto Project &DISTRO;
86 release tarball 86 release tarball
87 into the current working directory and sets up the local Source Directory 87 into the current working directory and sets up the local Source Directory
88 with a top-level folder named <filename>&YOCTO_POKY;</filename>: 88 with a top-level folder named <filename>&YOCTO_POKY;</filename>:
89 <literallayout class='monospaced'> 89 <literallayout class='monospaced'>
90 $ tar xfj &YOCTO_POKY_TARBALL; 90 $ tar xfj &YOCTO_POKY_TARBALL;
91 </literallayout></para> 91 </literallayout></para>
92 <para>This method does not produce a local Git repository. 92 <para>This method does not produce a local Git repository.
93 Instead, you simply end up with a snapshot of the release.</para></listitem> 93 Instead, you simply end up with a snapshot of the release.</para></listitem>
94 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing 94 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing
95 back into the Yocto Project or you simply want to keep up 95 back into the Yocto Project or you simply want to keep up
96 with the latest developments, you should use Git commands to set up a local 96 with the latest developments, you should use Git commands to set up a local
97 Git repository of the upstream <filename>poky</filename> source repository. 97 Git repository of the upstream <filename>poky</filename> source repository.
98 Doing so creates a repository with a complete history of changes and allows 98 Doing so creates a repository with a complete history of changes and allows
99 you to easily submit your changes upstream to the project. 99 you to easily submit your changes upstream to the project.
100 Because you cloned the repository, you have access to all the Yocto Project development 100 Because you cloned the repository, you have access to all the Yocto Project development
101 branches and tag names used in the upstream repository.</para> 101 branches and tag names used in the upstream repository.</para>
102 <para>The following transcript shows how to clone the <filename>poky</filename> 102 <para>The following transcript shows how to clone the <filename>poky</filename>
103 Git repository into the current working directory. 103 Git repository into the current working directory.
104 <note>You can view the Yocto Project Source Repositories at 104 <note>You can view the Yocto Project Source Repositories at
105 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note> 105 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
106 The command creates the local repository in a directory named <filename>poky</filename>. 106 The command creates the local repository in a directory named <filename>poky</filename>.
107 For information on Git used within the Yocto Project, see the 107 For information on Git used within the Yocto Project, see the
108 "<link linkend='git'>Git</link>" section. 108 "<link linkend='git'>Git</link>" section.
@@ -120,27 +120,27 @@
120 wiki page</ulink>, which describes how to create both <filename>poky</filename> 120 wiki page</ulink>, which describes how to create both <filename>poky</filename>
121 and <filename>meta-intel</filename> Git repositories.</para></listitem> 121 and <filename>meta-intel</filename> Git repositories.</para></listitem>
122 </itemizedlist></para></listitem> 122 </itemizedlist></para></listitem>
123 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis> 123 <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
124 If you are going to be making modifications to a supported Yocto Project kernel, you 124 If you are going to be making modifications to a supported Yocto Project kernel, you
125 need to establish local copies of the source. 125 need to establish local copies of the source.
126 You can find Git repositories of supported Yocto Project Kernels organized under 126 You can find Git repositories of supported Yocto Project Kernels organized under
127 "Yocto Linux Kernel" in the Yocto Project Source Repositories at 127 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
128 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> 128 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
129 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then 129 <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
130 copying that cloned repository. 130 copying that cloned repository.
131 You can create the bare clone and the copy of the bare clone anywhere you like. 131 You can create the bare clone and the copy of the bare clone anywhere you like.
132 For simplicity, it is recommended that you create these structures outside of the 132 For simplicity, it is recommended that you create these structures outside of the
133 Source Directory (usually <filename>poky</filename>).</para> 133 Source Directory (usually <filename>poky</filename>).</para>
134 <para>As an example, the following transcript shows how to create the bare clone 134 <para>As an example, the following transcript shows how to create the bare clone
135 of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of 135 of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of
136 that clone. 136 that clone.
137 <note>When you have a local Yocto Project kernel Git repository, you can 137 <note>When you have a local Yocto Project kernel Git repository, you can
138 reference that repository rather than the upstream Git repository as 138 reference that repository rather than the upstream Git repository as
139 part of the <filename>clone</filename> command. 139 part of the <filename>clone</filename> command.
140 Doing so can speed up the process.</note></para> 140 Doing so can speed up the process.</note></para>
141 <para>In the following example, the bare clone is named 141 <para>In the following example, the bare clone is named
142 <filename>linux-yocto-3.4.git</filename>, while the 142 <filename>linux-yocto-3.4.git</filename>, while the
143 copy is named <filename>my-linux-yocto-3.4-work</filename>: 143 copy is named <filename>my-linux-yocto-3.4-work</filename>:
144 <literallayout class='monospaced'> 144 <literallayout class='monospaced'>
145 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git 145 $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git
146 Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/ 146 Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/
@@ -158,20 +158,20 @@
158 </literallayout></para></listitem> 158 </literallayout></para></listitem>
159 <listitem id='poky-extras-repo'><para><emphasis> 159 <listitem id='poky-extras-repo'><para><emphasis>
160 The <filename>poky-extras</filename> Git Repository</emphasis>: 160 The <filename>poky-extras</filename> Git Repository</emphasis>:
161 The <filename>poky-extras</filename> Git repository contains metadata needed 161 The <filename>poky-extras</filename> Git repository contains metadata needed
162 only if you are modifying and building the kernel image. 162 only if you are modifying and building the kernel image.
163 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>) 163 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
164 files that you 164 files that you
165 edit to point to your locally modified kernel source files and to build the kernel 165 edit to point to your locally modified kernel source files and to build the kernel
166 image. 166 image.
167 Pointing to these local files is much more efficient than requiring a download of the 167 Pointing to these local files is much more efficient than requiring a download of the
168 kernel's source files from upstream each time you make changes to the kernel.</para> 168 kernel's source files from upstream each time you make changes to the kernel.</para>
169 <para>You can find the <filename>poky-extras</filename> Git Repository in the 169 <para>You can find the <filename>poky-extras</filename> Git Repository in the
170 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at 170 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
171 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. 171 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
172 It is good practice to create this Git repository inside the Source Directory.</para> 172 It is good practice to create this Git repository inside the Source Directory.</para>
173 <para>Following is an example that creates the <filename>poky-extras</filename> Git 173 <para>Following is an example that creates the <filename>poky-extras</filename> Git
174 repository inside the Source Directory, which is named <filename>poky</filename> 174 repository inside the Source Directory, which is named <filename>poky</filename>
175 in this case: 175 in this case:
176 <literallayout class='monospaced'> 176 <literallayout class='monospaced'>
177 $ cd ~/poky 177 $ cd ~/poky
@@ -183,21 +183,21 @@
183 Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done. 183 Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done.
184 Resolving deltas: 100% (192/192), done. 184 Resolving deltas: 100% (192/192), done.
185 </literallayout></para></listitem> 185 </literallayout></para></listitem>
186 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board 186 <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
187 Support Packages (BSPs):</emphasis> 187 Support Packages (BSPs):</emphasis>
188 The Yocto Project provides a layer called <filename>meta-intel</filename> and 188 The Yocto Project provides a layer called <filename>meta-intel</filename> and
189 it is maintained in its own separate Git repository. 189 it is maintained in its own separate Git repository.
190 The <filename>meta-intel</filename> layer contains many supported 190 The <filename>meta-intel</filename> layer contains many supported
191 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para> 191 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
192 <para>Similar considerations exist for setting up the <filename>meta-intel</filename> 192 <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
193 layer. 193 layer.
194 You can get set up for BSP development one of two ways: tarball extraction or 194 You can get set up for BSP development one of two ways: tarball extraction or
195 with a local Git repository. 195 with a local Git repository.
196 It is a good idea to use the same method that you used to set up the Source Directory. 196 It is a good idea to use the same method that you used to set up the Source Directory.
197 Regardless of the method you use, the Yocto Project uses the following BSP layer 197 Regardless of the method you use, the Yocto Project uses the following BSP layer
198 naming scheme: 198 naming scheme:
199 <literallayout class='monospaced'> 199 <literallayout class='monospaced'>
200 meta-&lt;BSP_name&gt; 200 meta-&lt;BSP_name&gt;
201 </literallayout> 201 </literallayout>
202 where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name. 202 where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
203 Here are some examples: 203 Here are some examples:
@@ -211,22 +211,22 @@
211 section in the Yocto Project Board Support Package (BSP) Developer's Guide for more 211 section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
212 information on BSP Layers. 212 information on BSP Layers.
213 <itemizedlist> 213 <itemizedlist>
214 <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released 214 <listitem><para><emphasis>Tarball Extraction:</emphasis> You can download any released
215 BSP tarball from the same 215 BSP tarball from the same
216 <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used 216 <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used
217 to get the Yocto Project release. 217 to get the Yocto Project release.
218 Once you have the tarball, just extract it into a directory of your choice. 218 Once you have the tarball, just extract it into a directory of your choice.
219 Again, this method just produces a snapshot of the BSP layer in the form 219 Again, this method just produces a snapshot of the BSP layer in the form
220 of a hierarchical directory structure.</para></listitem> 220 of a hierarchical directory structure.</para></listitem>
221 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working 221 <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working
222 with a local Git repository for your Source Directory, you should also use this method 222 with a local Git repository for your Source Directory, you should also use this method
223 to set up the <filename>meta-intel</filename> Git repository. 223 to set up the <filename>meta-intel</filename> Git repository.
224 You can locate the <filename>meta-intel</filename> Git repository in the 224 You can locate the <filename>meta-intel</filename> Git repository in the
225 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at 225 "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
226 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> 226 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
227 <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside 227 <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
228 the Source Directory. 228 the Source Directory.
229 For example, the following transcript shows the steps to clone the 229 For example, the following transcript shows the steps to clone the
230 <filename>meta-intel</filename> 230 <filename>meta-intel</filename>
231 Git repository inside the local <filename>poky</filename> Git repository. 231 Git repository inside the local <filename>poky</filename> Git repository.
232 <literallayout class='monospaced'> 232 <literallayout class='monospaced'>
@@ -239,15 +239,15 @@
239 Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done. 239 Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done.
240 Resolving deltas: 100% (1689/1689), done. 240 Resolving deltas: 100% (1689/1689), done.
241 </literallayout></para> 241 </literallayout></para>
242 <para>The same 242 <para>The same
243 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'> 243 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
244 wiki page</ulink> referenced earlier covers how to 244 wiki page</ulink> referenced earlier covers how to
245 set up the <filename>meta-intel</filename> Git repository.</para></listitem> 245 set up the <filename>meta-intel</filename> Git repository.</para></listitem>
246 </itemizedlist></para></listitem> 246 </itemizedlist></para></listitem>
247 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing 247 <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis> If you are developing
248 applications using the Eclipse Integrated Development Environment (IDE), 248 applications using the Eclipse Integrated Development Environment (IDE),
249 you will need this plug-in. 249 you will need this plug-in.
250 See the 250 See the
251 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>" 251 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
252 section for more information.</para></listitem> 252 section for more information.</para></listitem>
253 </itemizedlist> 253 </itemizedlist>
@@ -258,8 +258,8 @@
258 <title>Building Images</title> 258 <title>Building Images</title>
259 259
260 <para> 260 <para>
261 The build process creates an entire Linux distribution, including the toolchain, from source. 261 The build process creates an entire Linux distribution, including the toolchain, from source.
262 For more information on this topic, see the 262 For more information on this topic, see the
263 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" 263 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
264 section in the Yocto Project Quick Start. 264 section in the Yocto Project Quick Start.
265 </para> 265 </para>
@@ -267,27 +267,27 @@
267 <para> 267 <para>
268 The build process is as follows: 268 The build process is as follows:
269 <orderedlist> 269 <orderedlist>
270 <listitem><para>Make sure you have set up the Source Directory described in the 270 <listitem><para>Make sure you have set up the Source Directory described in the
271 previous section.</para></listitem> 271 previous section.</para></listitem>
272 <listitem><para>Initialize the build environment by sourcing a build environment 272 <listitem><para>Initialize the build environment by sourcing a build environment
273 script.</para></listitem> 273 script.</para></listitem>
274 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, 274 <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
275 which is found in the 275 which is found in the
276 <link linkend='build-directory'>Build Directory</link>, 276 <link linkend='build-directory'>Build Directory</link>,
277 is set up how you want it. 277 is set up how you want it.
278 This file defines many aspects of the build environment including 278 This file defines many aspects of the build environment including
279 the target machine architecture through the 279 the target machine architecture through the
280 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, 280 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
281 the development machine's processor use through the 281 the development machine's processor use through the
282 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and 282 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
283 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and 283 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
284 a centralized tarball download directory through the 284 a centralized tarball download directory through the
285 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> 285 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
286 <listitem><para>Build the image using the <filename>bitbake</filename> command. 286 <listitem><para>Build the image using the <filename>bitbake</filename> command.
287 If you want information on BitBake, see the user manual inculded in the 287 If you want information on BitBake, see the user manual inculded in the
288 <filename>bitbake/doc/manual</filename> directory of the 288 <filename>bitbake/doc/manual</filename> directory of the
289 <link linkend='source-directory'>Source Directory</link>.</para></listitem> 289 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
290 <listitem><para>Run the image either on the actual hardware or using the QEMU 290 <listitem><para>Run the image either on the actual hardware or using the QEMU
291 emulator.</para></listitem> 291 emulator.</para></listitem>
292 </orderedlist> 292 </orderedlist>
293 </para> 293 </para>
@@ -297,8 +297,8 @@
297 <title>Using Pre-Built Binaries and QEMU</title> 297 <title>Using Pre-Built Binaries and QEMU</title>
298 298
299 <para> 299 <para>
300 Another option you have to get started is to use pre-built binaries. 300 Another option you have to get started is to use pre-built binaries.
301 The Yocto Project provides many types of binaries with each release. 301 The Yocto Project provides many types of binaries with each release.
302 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" 302 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
303 chapter in the Yocto Project Reference Manual 303 chapter in the Yocto Project Reference Manual
304 for descriptions of the types of binaries that ship with a Yocto Project 304 for descriptions of the types of binaries that ship with a Yocto Project
@@ -306,51 +306,51 @@
306 </para> 306 </para>
307 307
308 <para> 308 <para>
309 Using a pre-built binary is ideal for developing software applications to run on your 309 Using a pre-built binary is ideal for developing software applications to run on your
310 target hardware. 310 target hardware.
311 To do this, you need to be able to access the appropriate cross-toolchain tarball for 311 To do this, you need to be able to access the appropriate cross-toolchain tarball for
312 the architecture on which you are developing. 312 the architecture on which you are developing.
313 If you are using an SDK type image, the image ships with the complete toolchain native to 313 If you are using an SDK type image, the image ships with the complete toolchain native to
314 the architecture. 314 the architecture.
315 If you are not using an SDK type image, you need to separately download and 315 If you are not using an SDK type image, you need to separately download and
316 install the stand-alone Yocto Project cross-toolchain tarball. 316 install the stand-alone Yocto Project cross-toolchain tarball.
317 </para> 317 </para>
318 318
319 <para> 319 <para>
320 Regardless of the type of image you are using, you need to download the pre-built kernel 320 Regardless of the type of image you are using, you need to download the pre-built kernel
321 that you will boot in the QEMU emulator and then download and extract the target root 321 that you will boot in the QEMU emulator and then download and extract the target root
322 filesystem for your target machine’s architecture. 322 filesystem for your target machine’s architecture.
323 You can get architecture-specific binaries and filesystems from 323 You can get architecture-specific binaries and filesystems from
324 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>. 324 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
325 You can get installation scripts for stand-alone toolchains from 325 You can get installation scripts for stand-alone toolchains from
326 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>. 326 <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
327 Once you have all your files, you set up the environment to emulate the hardware 327 Once you have all your files, you set up the environment to emulate the hardware
328 by sourcing an environment setup script. 328 by sourcing an environment setup script.
329 Finally, you start the QEMU emulator. 329 Finally, you start the QEMU emulator.
330 You can find details on all these steps in the 330 You can find details on all these steps in the
331 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" 331 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
332 section of the Yocto Project Quick Start. 332 section of the Yocto Project Quick Start.
333 </para> 333 </para>
334 334
335 <para> 335 <para>
336 Using QEMU to emulate your hardware can result in speed issues 336 Using QEMU to emulate your hardware can result in speed issues
337 depending on the target and host architecture mix. 337 depending on the target and host architecture mix.
338 For example, using the <filename>qemux86</filename> image in the emulator 338 For example, using the <filename>qemux86</filename> image in the emulator
339 on an Intel-based 32-bit (x86) host machine is fast because the target and 339 on an Intel-based 32-bit (x86) host machine is fast because the target and
340 host architectures match. 340 host architectures match.
341 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based 341 On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
342 host can be slower. 342 host can be slower.
343 But, you still achieve faithful emulation of ARM-specific issues. 343 But, you still achieve faithful emulation of ARM-specific issues.
344 </para> 344 </para>
345 345
346 <para> 346 <para>
347 To speed things up, the QEMU images support using <filename>distcc</filename> 347 To speed things up, the QEMU images support using <filename>distcc</filename>
348 to call a cross-compiler outside the emulated system. 348 to call a cross-compiler outside the emulated system.
349 If you used <filename>runqemu</filename> to start QEMU, and the 349 If you used <filename>runqemu</filename> to start QEMU, and the
350 <filename>distccd</filename> application is present on the host system, any 350 <filename>distccd</filename> application is present on the host system, any
351 BitBake cross-compiling toolchain available from the build system is automatically 351 BitBake cross-compiling toolchain available from the build system is automatically
352 used from within QEMU simply by calling <filename>distcc</filename>. 352 used from within QEMU simply by calling <filename>distcc</filename>.
353 You can accomplish this by defining the cross-compiler variable 353 You can accomplish this by defining the cross-compiler variable
354 (e.g. <filename>export CC="distcc"</filename>). 354 (e.g. <filename>export CC="distcc"</filename>).
355 Alternatively, if you are using a suitable SDK image or the appropriate 355 Alternatively, if you are using a suitable SDK image or the appropriate
356 stand-alone toolchain is present in <filename>/opt/poky</filename>, 356 stand-alone toolchain is present in <filename>/opt/poky</filename>,
@@ -358,27 +358,27 @@
358 </para> 358 </para>
359 359
360 <note> 360 <note>
361 Several mechanisms exist that let you connect to the system running on the 361 Several mechanisms exist that let you connect to the system running on the
362 QEMU emulator: 362 QEMU emulator:
363 <itemizedlist> 363 <itemizedlist>
364 <listitem><para>QEMU provides a framebuffer interface that makes standard 364 <listitem><para>QEMU provides a framebuffer interface that makes standard
365 consoles available.</para></listitem> 365 consoles available.</para></listitem>
366 <listitem><para>Generally, headless embedded devices have a serial port. 366 <listitem><para>Generally, headless embedded devices have a serial port.
367 If so, you can configure the operating system of the running image 367 If so, you can configure the operating system of the running image
368 to use that port to run a console. 368 to use that port to run a console.
369 The connection uses standard IP networking.</para></listitem> 369 The connection uses standard IP networking.</para></listitem>
370 <listitem><para>SSH servers exist in some QEMU images. 370 <listitem><para>SSH servers exist in some QEMU images.
371 The <filename>core-image-sato</filename> QEMU image has a Dropbear secure 371 The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
372 shell (ssh) server that runs with the root password disabled. 372 shell (ssh) server that runs with the root password disabled.
373 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images 373 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
374 have OpenSSH instead of Dropbear. 374 have OpenSSH instead of Dropbear.
375 Including these SSH servers allow you to use standard <filename>ssh</filename> and 375 Including these SSH servers allow you to use standard <filename>ssh</filename> and
376 <filename>scp</filename> commands. 376 <filename>scp</filename> commands.
377 The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh 377 The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh
378 server.</para></listitem> 378 server.</para></listitem>
379 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session 379 <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
380 using a local copy of the root filesystem on the host. 380 using a local copy of the root filesystem on the host.
381 In order to make this connection, you must extract a root filesystem tarball by using the 381 In order to make this connection, you must extract a root filesystem tarball by using the
382 <filename>runqemu-extract-sdk</filename> command. 382 <filename>runqemu-extract-sdk</filename> command.
383 After running the command, you must then point the <filename>runqemu</filename> 383 After running the command, you must then point the <filename>runqemu</filename>
384 script to the extracted directory instead of a root filesystem image file.</para></listitem> 384 script to the extracted directory instead of a root filesystem image file.</para></listitem>