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