summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/introduction.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/introduction.xml')
-rw-r--r--documentation/ref-manual/introduction.xml556
1 files changed, 556 insertions, 0 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
new file mode 100644
index 0000000000..f48489a563
--- /dev/null
+++ b/documentation/ref-manual/introduction.xml
@@ -0,0 +1,556 @@
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='intro'>
6<title>Introduction</title>
7
8<section id='intro-welcome'>
9 <title>Introduction</title>
10
11 <para>
12 This manual provides reference information for the current release of the Yocto Project.
13 The Yocto Project is an open-source collaboration project focused on embedded Linux
14 developers.
15 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
16 is based on the Poky project, to construct complete Linux images.
17 You can find complete introductory and getting started information on the Yocto Project
18 by reading the
19 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
20 For task-based information using the Yocto Project, see the
21 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
22 and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
23 For Board Support Package (BSP) structure information, see the
24 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
25 You can find information on tracing and profiling in the
26 <ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual'>Yocto Project Profiling and Tracing Manual</ulink>.
27 For information on BitBake, which is the task execution tool the
28 OpenEmbedded build system is based on, see the
29 <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.
30 Finally, you can also find lots of Yocto Project information on the
31 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
32 </para>
33</section>
34
35<section id='intro-manualoverview'>
36 <title>Documentation Overview</title>
37 <para>
38 This reference manual consists of the following:
39 <itemizedlist>
40 <listitem><para><emphasis>
41 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis>
42 Provides an overview of the components that make up the Yocto Project
43 followed by information about debugging images created in the Yocto Project.
44 </para></listitem>
45 <listitem><para><emphasis>
46 <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:</emphasis>
47 Provides a more detailed look at the Yocto Project development
48 environment within the context of development.
49 </para></listitem>
50 <listitem><para><emphasis>
51 <link linkend='technical-details'>Technical Details</link>:</emphasis>
52 Describes fundamental Yocto Project components as well as an explanation
53 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
54 </para></listitem>
55 <listitem><para><emphasis>
56 <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:</emphasis>
57 Describes release-specific information that helps you move from
58 one Yocto Project Release to another.
59 </para></listitem>
60 <listitem><para><emphasis>
61 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
62 Describes the
63 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created
64 either by unpacking a released Yocto Project tarball on your host development system,
65 or by cloning the upstream
66 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
67 </para></listitem>
68 <listitem><para><emphasis>
69 <link linkend='ref-classes'>Classes</link>:</emphasis>
70 Describes the classes used in the Yocto Project.</para></listitem>
71 <listitem><para><emphasis>
72 <link linkend='ref-images'>Images</link>:</emphasis>
73 Describes the standard images that the Yocto Project supports.
74 </para></listitem>
75 <listitem><para><emphasis>
76 <link linkend='ref-features'>Features</link>:</emphasis>
77 Describes mechanisms for creating distribution, machine, and image
78 features during the build process using the OpenEmbedded build system.</para></listitem>
79 <listitem><para><emphasis>
80 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
81 Presents most variables used by the OpenEmbedded build system, which
82 uses BitBake.
83 Entries describe the function of the variable and how to apply them.
84 </para></listitem>
85 <listitem><para><emphasis>
86 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
87 Provides variable locality or context.</para></listitem>
88 <listitem><para><emphasis>
89 <link linkend='faq'>FAQ</link>:</emphasis>
90 Provides answers for commonly asked questions in the Yocto Project
91 development environment.</para></listitem>
92 <listitem><para><emphasis>
93 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
94 Provides guidance on how you can contribute back to the Yocto
95 Project.</para></listitem>
96 </itemizedlist>
97 </para>
98</section>
99
100
101<section id='intro-requirements'>
102<title>System Requirements</title>
103 <para>
104 For general Yocto Project system requirements, see the
105 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
106 in the Yocto Project Quick Start.
107 The remainder of this section provides details on system requirements
108 not covered in the Yocto Project Quick Start.
109 </para>
110
111 <section id='detailed-supported-distros'>
112 <title>Supported Linux Distributions</title>
113
114 <para>
115 Currently, the Yocto Project is supported on the following
116 distributions:
117 <note>
118 <para>
119 Yocto Project releases are tested against the stable Linux
120 distributions in the following list.
121 The Yocto Project should work on other distributions but
122 validation is not performed against them.
123 </para>
124
125 <para>
126 In particular, the Yocto Project does not support
127 and currently has no plans to support
128 rolling-releases or development distributions due to their
129 constantly changing nature.
130 We welcome patches and bug reports, but keep in mind that
131 our priority is on the supported platforms listed below.
132 </para>
133
134 <para>
135 If you encounter problems, please go to
136 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
137 and submit a bug.
138 We are interested in hearing about your experience.
139 </para>
140 </note>
141 <itemizedlist>
142<!-- <listitem><para>Ubuntu 10.04</para></listitem>
143 <listitem><para>Ubuntu 11.10</para></listitem> -->
144 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
145 <listitem><para>Ubuntu 13.10</para></listitem>
146 <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
147<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
148 <listitem><para>Fedora 17 (Spherical)</para></listitem> -->
149 <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
150 <listitem><para>Fedora release 20 (Heisenbug)</para></listitem>
151<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>
152 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
153 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
154 <listitem><para>CentOS release 6.3 (Final)</para></listitem> -->
155 <listitem><para>CentOS release 6.4</para></listitem>
156 <listitem><para>CentOS release 6.5</para></listitem>
157<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> -->
158 <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem>
159 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
160 <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
161 <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
162 <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
163<!-- <listitem><para>openSUSE 11.4</para></listitem>
164 <listitem><para>openSUSE 12.1</para></listitem> -->
165 <listitem><para>openSUSE 12.2</para></listitem>
166 <listitem><para>openSUSE 12.3</para></listitem>
167 <listitem><para>openSUSE 13.1</para></listitem>
168 </itemizedlist>
169 </para>
170
171 <note>
172 While the Yocto Project Team attempts to ensure all Yocto Project
173 releases are one hundred percent compatible with each officially
174 supported Linux distribution, instances might exist where you
175 encounter a problem while using the Yocto Project on a specific
176 distribution.
177 For example, the CentOS 6.4 distribution does not include the
178 Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are
179 required to run
180 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
181 </note>
182 </section>
183
184 <section id='required-packages-for-the-host-development-system'>
185 <title>Required Packages for the Host Development System</title>
186
187 <para>
188 The list of packages you need on the host development system can
189 be large when covering all build scenarios using the Yocto Project.
190 This section provides required packages according to
191 Linux distribution and function.
192 </para>
193
194 <section id='ubuntu-packages'>
195 <title>Ubuntu and Debian</title>
196
197 <para>
198 The following list shows the required packages by function
199 given a supported Ubuntu or Debian Linux distribution:
200 <itemizedlist>
201 <listitem><para><emphasis>Essentials:</emphasis>
202 Packages needed to build an image on a headless
203 system:
204 <literallayout class='monospaced'>
205 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
206 </literallayout></para></listitem>
207 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
208 Packages recommended if the host system has graphics
209 support or if you are going to use the Eclipse
210 IDE:
211 <literallayout class='monospaced'>
212 $ sudo apt-get install libsdl1.2-dev xterm
213 </literallayout></para></listitem>
214 <listitem><para><emphasis>Documentation:</emphasis>
215 Packages needed if you are going to build out the
216 Yocto Project documentation manuals:
217 <literallayout class='monospaced'>
218 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
219 </literallayout></para></listitem>
220 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
221 Packages needed if you are going to be using the
222 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
223 <literallayout class='monospaced'>
224 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
225 </literallayout></para></listitem>
226 </itemizedlist>
227 </para>
228 </section>
229
230 <section id='fedora-packages'>
231 <title>Fedora Packages</title>
232
233 <para>
234 The following list shows the required packages by function
235 given a supported Fedora Linux distribution:
236 <itemizedlist>
237 <listitem><para><emphasis>Essentials:</emphasis>
238 Packages needed to build an image for a headless
239 system:
240 <literallayout class='monospaced'>
241 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
242 </literallayout></para></listitem>
243 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
244 Packages recommended if the host system has graphics
245 support or if you are going to use the Eclipse
246 IDE:
247 <literallayout class='monospaced'>
248 $ sudo yum install SDL-devel xterm perl-Thread-Queue
249 </literallayout></para></listitem>
250 <listitem><para><emphasis>Documentation:</emphasis>
251 Packages needed if you are going to build out the
252 Yocto Project documentation manuals:
253 <literallayout class='monospaced'>
254 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
255 docbook-dtds docbook-utils fop libxslt dblatex xmlto
256 </literallayout></para></listitem>
257 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
258 Packages needed if you are going to be using the
259 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
260 <literallayout class='monospaced'>
261 $ sudo yum install autoconf automake libtool glib2-devel
262 </literallayout></para></listitem>
263 </itemizedlist>
264 </para>
265 </section>
266
267 <section id='opensuse-packages'>
268 <title>openSUSE Packages</title>
269
270 <para>
271 The following list shows the required packages by function
272 given a supported openSUSE Linux distribution:
273 <itemizedlist>
274 <listitem><para><emphasis>Essentials:</emphasis>
275 Packages needed to build an image for a headless
276 system:
277 <literallayout class='monospaced'>
278 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
279 </literallayout></para></listitem>
280 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
281 Packages recommended if the host system has graphics
282 support or if you are going to use the Eclipse
283 IDE:
284 <literallayout class='monospaced'>
285 $ sudo zypper install libSDL-devel xterm
286 </literallayout></para></listitem>
287 <listitem><para><emphasis>Documentation:</emphasis>
288 Packages needed if you are going to build out the
289 Yocto Project documentation manuals:
290 <literallayout class='monospaced'>
291 $ sudo zypper install make fop xsltproc dblatex xmlto
292 </literallayout></para></listitem>
293 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
294 Packages needed if you are going to be using the
295 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
296 <literallayout class='monospaced'>
297 $ sudo zypper install autoconf automake libtool glib2-devel
298 </literallayout></para></listitem>
299 </itemizedlist>
300 </para>
301 </section>
302
303 <section id='centos-packages'>
304 <title>CentOS Packages</title>
305
306 <para>
307 The following list shows the required packages by function
308 given a supported CentOS Linux distribution:
309 <note>Depending on the CentOS version you are using, other requirements
310 and dependencies might exist.
311 For details, you should look at the CentOS sections on the
312 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
313 wiki page.
314 </note>
315 <itemizedlist>
316 <listitem><para><emphasis>Essentials:</emphasis>
317 Packages needed to build an image for a headless
318 system:
319 <literallayout class='monospaced'>
320 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
321 </literallayout></para></listitem>
322 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
323 Packages recommended if the host system has graphics
324 support or if you are going to use the Eclipse
325 IDE:
326 <literallayout class='monospaced'>
327 $ sudo yum install SDL-devel xterm
328 </literallayout></para></listitem>
329 <listitem><para><emphasis>Documentation:</emphasis>
330 Packages needed if you are going to build out the
331 Yocto Project documentation manuals:
332 <literallayout class='monospaced'>
333 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
334 docbook-dtds docbook-utils fop libxslt dblatex xmlto
335 </literallayout></para></listitem>
336 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
337 Packages needed if you are going to be using the
338 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
339 <literallayout class='monospaced'>
340 $ sudo yum install autoconf automake libtool glib2-devel
341 </literallayout></para></listitem>
342 </itemizedlist>
343 </para>
344 </section>
345 </section>
346
347 <section id='required-git-tar-and-python-versions'>
348 <title>Required Git, tar, and Python Versions</title>
349
350 <para>
351 In order to use the build system, your host development system
352 must meet the following version requirements for Git, tar, and
353 Python:
354 <itemizedlist>
355 <listitem><para>Git 1.7.5 or greater</para></listitem>
356 <listitem><para>tar 1.24 or greater</para></listitem>
357 <listitem><para>Python 2.7.3 or greater not including
358 Python 3.x, which is not supported.</para></listitem>
359 </itemizedlist>
360 </para>
361
362 <para>
363 If your host development system does not meet all these requirements,
364 you can resolve this by installing a <filename>buildtools</filename>
365 tarball that contains these tools.
366 You can get the tarball one of two ways: download a pre-built
367 tarball or use BitBake to build the tarball.
368 </para>
369
370 <section id='downloading-a-pre-built-buildtools-tarball'>
371 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
372
373 <para>
374 Downloading and running a pre-built buildtools installer is
375 the easiest of the two methods by which you can get these tools:
376 <orderedlist>
377 <listitem><para>
378 Locate and download the <filename>*.sh</filename> at
379 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
380 </para></listitem>
381 <listitem><para>
382 Execute the installation script.
383 Here is an example:
384 <literallayout class='monospaced'>
385 $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
386 </literallayout>
387 During execution, a prompt appears that allows you to
388 choose the installation directory.
389 For example, you could choose the following:
390 <literallayout class='monospaced'>
391 /home/your-username/buildtools
392 </literallayout>
393 </para></listitem>
394 <listitem><para>
395 Source the tools environment setup script by using a
396 command like the following:
397 <literallayout class='monospaced'>
398 $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
399 </literallayout>
400 Of course, you need to supply your installation directory and be
401 sure to use the right file (i.e. i585 or x86-64).
402 </para>
403 <para>
404 After you have sourced the setup script,
405 the tools are added to <filename>PATH</filename>
406 and any other environment variables required to run the
407 tools are initialized.
408 The results are working versions versions of Git, tar,
409 Python and <filename>chrpath</filename>.
410 </para></listitem>
411 </orderedlist>
412 </para>
413 </section>
414
415 <section id='building-your-own-buildtools-tarball'>
416 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
417
418 <para>
419 Building and running your own buildtools installer applies
420 only when you have a build host that can already run BitBake.
421 In this case, you use that machine to build the
422 <filename>.sh</filename> file and then
423 take steps to transfer and run it on a
424 machine that does not meet the minimal Git, tar, and Python
425 requirements.
426 </para>
427
428 <para>
429 Here are the steps to take to build and run your own
430 buildtools installer:
431 <orderedlist>
432 <listitem><para>
433 On the machine that is able to run BitBake,
434 be sure you have set up your build environment with
435 the setup script
436 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
437 or
438 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
439 </para></listitem>
440 <listitem><para>
441 Run the BitBake command to build the tarball:
442 <literallayout class='monospaced'>
443 $ bitbake buildtools-tarball
444 </literallayout>
445 <note>
446 The
447 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
448 variable in your <filename>local.conf</filename> file
449 determines whether you build tools for a 32-bit
450 or 64-bit system.
451 </note>
452 Once the build completes, you can find the
453 <filename>.sh</filename> file that installs
454 the tools in the <filename>tmp/deploy/sdk</filename>
455 subdirectory of the
456 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
457 The installer file has the string "buildtools"
458 in the name.
459 </para></listitem>
460 <listitem><para>
461 Transfer the <filename>.sh</filename> file from the
462 build host to the machine that does not meet the
463 Git, tar, or Python requirements.
464 </para></listitem>
465 <listitem><para>
466 On the machine that does not meet the requirements,
467 run the <filename>.sh</filename> file
468 to install the tools.
469 Here is an example:
470 <literallayout class='monospaced'>
471 $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
472 </literallayout>
473 During execution, a prompt appears that allows you to
474 choose the installation directory.
475 For example, you could choose the following:
476 <literallayout class='monospaced'>
477 /home/your-username/buildtools
478 </literallayout>
479 </para></listitem>
480 <listitem><para>
481 Source the tools environment setup script by using a
482 command like the following:
483 <literallayout class='monospaced'>
484 $ source /home/your-username/buildtools/environment-setup-i586-poky-linux
485 </literallayout>
486 Of course, you need to supply your installation directory and be
487 sure to use the right file (i.e. i585 or x86-64).
488 </para>
489 <para>
490 After you have sourced the setup script,
491 the tools are added to <filename>PATH</filename>
492 and any other environment variables required to run the
493 tools are initialized.
494 The results are working versions versions of Git, tar,
495 Python and <filename>chrpath</filename>.
496 </para></listitem>
497 </orderedlist>
498 </para>
499 </section>
500 </section>
501</section>
502
503<section id='intro-getit'>
504 <title>Obtaining the Yocto Project</title>
505 <para>
506 The Yocto Project development team makes the Yocto Project available through a number
507 of methods:
508 <itemizedlist>
509 <listitem><para><emphasis>Source Repositories:</emphasis>
510 Working from a copy of the upstream
511 <filename>poky</filename> repository is the
512 preferred method for obtaining and using a Yocto Project
513 release.
514 You can view the Yocto Project Source Repositories at
515 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
516 In particular, you can find the
517 <filename>poky</filename> repository at
518 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
519 </para></listitem>
520 <listitem><para><emphasis>Releases:</emphasis> Stable, tested
521 releases are available as tarballs through
522 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
523 <listitem><para><emphasis>Nightly Builds:</emphasis> These
524 tarball releases are available at
525 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
526 These builds include Yocto Project releases, meta-toolchain
527 tarball installation scripts, and experimental builds.
528 </para></listitem>
529 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can
530 find tarball releases of the Yocto Project and supported BSPs
531 at the
532 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
533 Along with these downloads, you can find lots of other
534 information at this site.
535 </para></listitem>
536 </itemizedlist>
537 </para>
538</section>
539
540<section id='intro-getit-dev'>
541 <title>Development Checkouts</title>
542 <para>
543 Development using the Yocto Project requires a local
544 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
545 You can set up the Source Directory by cloning a copy of the upstream
546 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> Git repository.
547 For information on how to do this, see the
548 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
549 section in the Yocto Project Development Manual.
550 </para>
551</section>
552
553</chapter>
554<!--
555vim: expandtab tw=80 ts=4
556-->