summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/introduction.xml
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:46:05 +0100
committerAdrian Dudau <adrian.dudau@enea.com>2013-12-12 13:47:32 +0100
commit14b00ff23a912494edc7f146e668c40ca82b8508 (patch)
treef7f4e592ccb935bc312cfa0cfc3c0cbbe444970d /documentation/ref-manual/introduction.xml
downloadyocto-docs-master.tar.gz
initial commit of Enea Linux 3.1HEADmaster
Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/ref-manual/introduction.xml')
-rw-r--r--documentation/ref-manual/introduction.xml439
1 files changed, 439 insertions, 0 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
new file mode 100644
index 0000000..8232ba8
--- /dev/null
+++ b/documentation/ref-manual/introduction.xml
@@ -0,0 +1,439 @@
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 also find lots of Yocto Project information on the
26 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
27 </para>
28</section>
29
30<section id='intro-manualoverview'>
31 <title>Documentation Overview</title>
32 <para>
33 This reference manual consists of the following:
34 <itemizedlist>
35 <listitem><para><emphasis>
36 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis>
37 Provides an overview of the components that make up the Yocto Project
38 followed by information about debugging images created in the Yocto Project.
39 </para></listitem>
40 <listitem><para><emphasis>
41 <link linkend='technical-details'>Technical Details</link>:</emphasis>
42 Describes fundamental Yocto Project components as well as an explanation
43 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
44 </para></listitem>
45 <listitem><para><emphasis>
46 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
47 Describes the
48 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created
49 either by unpacking a released Yocto Project tarball on your host development system,
50 or by cloning the upstream
51 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
52 </para></listitem>
53 <listitem><para><emphasis>
54 <link linkend='ref-bitbake'>BitBake</link>:</emphasis>
55 Provides an overview of the BitBake tool and its role within
56 the Yocto Project.</para></listitem>
57 <listitem><para><emphasis>
58 <link linkend='ref-classes'>Classes</link>:</emphasis>
59 Describes the classes used in the Yocto Project.</para></listitem>
60 <listitem><para><emphasis>
61 <link linkend='ref-images'>Images</link>:</emphasis>
62 Describes the standard images that the Yocto Project supports.
63 </para></listitem>
64 <listitem><para><emphasis>
65 <link linkend='ref-features'>Features</link>:</emphasis>
66 Describes mechanisms for creating distribution, machine, and image
67 features during the build process using the OpenEmbedded build system.</para></listitem>
68 <listitem><para><emphasis>
69 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
70 Presents most variables used by the OpenEmbedded build system, which
71 uses BitBake.
72 Entries describe the function of the variable and how to apply them.
73 </para></listitem>
74 <listitem><para><emphasis>
75 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
76 Provides variable locality or context.</para></listitem>
77 <listitem><para><emphasis>
78 <link linkend='faq'>FAQ</link>:</emphasis>
79 Provides answers for commonly asked questions in the Yocto Project
80 development environment.</para></listitem>
81 <listitem><para><emphasis>
82 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
83 Provides guidance on how you can contribute back to the Yocto
84 Project.</para></listitem>
85 </itemizedlist>
86 </para>
87</section>
88
89
90<section id='intro-requirements'>
91<title>System Requirements</title>
92 <para>
93 For general Yocto Project system requirements, see the
94 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
95 in the Yocto Project Quick Start.
96 The remainder of this section provides details on system requirements
97 not covered in the Yocto Project Quick Start.
98 </para>
99
100 <section id='detailed-supported-distros'>
101 <title>Supported Linux Distributions</title>
102
103 <para>
104 Currently, the Yocto Project is supported on the following
105 distributions:
106 <note>
107 <para>
108 Yocto Project releases are tested against the stable Linux
109 distributions in the following list.
110 The Yocto Project should work on other distributions but
111 validation is not performed against them.
112 </para>
113
114 <para>
115 In particular, the Yocto Project does not support
116 and currently has no plans to support
117 rolling-releases or development distributions due to their
118 constantly changing nature.
119 We welcome patches and bug reports, but keep in mind that
120 our priority is on the supported platforms listed below.
121 </para>
122
123 <para>
124 If you encounter problems, please go to
125 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
126 and submit a bug.
127 We are interested in hearing about your experience.
128 </para>
129 </note>
130 <itemizedlist>
131<!-- <listitem><para>Ubuntu 10.04</para></listitem>
132 <listitem><para>Ubuntu 11.10</para></listitem> -->
133 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
134 <listitem><para>Ubuntu 12.10</para></listitem>
135 <listitem><para>Ubuntu 13.04</para></listitem>
136<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
137 <listitem><para>Fedora 17 (Spherical)</para></listitem> -->
138 <listitem><para>Fedora release 18 (Spherical Cow)</para></listitem>
139 <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
140<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>
141 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
142 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
143 <listitem><para>CentOS release 6.3 (Final)</para></listitem> -->
144 <listitem><para>CentOS release 6.4</para></listitem>
145<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> -->
146 <listitem><para>Debian GNU/Linux 6.0.7 (Squeeze)</para></listitem>
147 <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem>
148 <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
149<!-- <listitem><para>openSUSE 11.4</para></listitem>
150 <listitem><para>openSUSE 12.1</para></listitem> -->
151 <listitem><para>openSUSE 12.2</para></listitem>
152 <listitem><para>openSUSE 12.3</para></listitem>
153 </itemizedlist>
154 </para>
155
156 <note>
157 While the Yocto Project Team attempts to ensure all Yocto Project
158 releases are one hundred percent compatible with each officially
159 supported Linux distribution, instances might exist where you
160 encounter a problem while using the Yocto Project on a specific
161 distribution.
162 For example, the CentOS 6.4 distribution does not include the
163 Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are
164 required to run
165 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
166 </note>
167 </section>
168
169 <section id='required-packages-for-the-host-development-system'>
170 <title>Required Packages for the Host Development System</title>
171
172 <para>
173 The list of packages you need on the host development system can
174 be large when covering all build scenarios using the Yocto Project.
175 This section provides required packages according to
176 Linux distribution and function.
177 </para>
178
179 <section id='ubuntu-packages'>
180 <title>Ubuntu and Debian</title>
181
182 <para>
183 The following list shows the required packages by function
184 given a supported Ubuntu or Debian Linux distribution:
185 <itemizedlist>
186 <listitem><para><emphasis>Essentials:</emphasis>
187 Packages needed to build an image on a headless
188 system:
189 <literallayout class='monospaced'>
190 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
191 </literallayout></para></listitem>
192 <listitem><para><emphasis>Graphical Extras:</emphasis>
193 Packages recommended if the host system has graphics support:
194 <literallayout class='monospaced'>
195 $ sudo apt-get install libsdl1.2-dev xterm
196 </literallayout></para></listitem>
197 <listitem><para><emphasis>Documentation:</emphasis>
198 Packages needed if you are going to build out the
199 Yocto Project documentation manuals:
200 <literallayout class='monospaced'>
201 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
202 </literallayout></para></listitem>
203 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
204 Packages needed if you are going to be using the
205 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
206 <literallayout class='monospaced'>
207 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
208 </literallayout></para></listitem>
209 </itemizedlist>
210 </para>
211 </section>
212
213 <section id='fedora-packages'>
214 <title>Fedora Packages</title>
215
216 <para>
217 The following list shows the required packages by function
218 given a supported Fedora Linux distribution:
219 <itemizedlist>
220 <listitem><para><emphasis>Essentials:</emphasis>
221 Packages needed to build an image for a headless
222 system:
223 <literallayout class='monospaced'>
224 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
225 </literallayout></para></listitem>
226 <listitem><para><emphasis>Graphical Extras:</emphasis>
227 Packages recommended if the host system has graphics support:
228 <literallayout class='monospaced'>
229 $ sudo yum install SDL-devel xterm
230 </literallayout></para></listitem>
231 <listitem><para><emphasis>Documentation:</emphasis>
232 Packages needed if you are going to build out the
233 Yocto Project documentation manuals:
234 <literallayout class='monospaced'>
235 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
236 docbook-dtds docbook-utils fop libxslt dblatex xmlto
237 </literallayout></para></listitem>
238 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
239 Packages needed if you are going to be using the
240 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
241 <literallayout class='monospaced'>
242 $ sudo yum install autoconf automake libtool glib2-devel
243 </literallayout></para></listitem>
244 </itemizedlist>
245 </para>
246 </section>
247
248 <section id='opensuse-packages'>
249 <title>openSUSE Packages</title>
250
251 <para>
252 The following list shows the required packages by function
253 given a supported openSUSE Linux distribution:
254 <itemizedlist>
255 <listitem><para><emphasis>Essentials:</emphasis>
256 Packages needed to build an image for a headless
257 system:
258 <literallayout class='monospaced'>
259 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
260 </literallayout></para></listitem>
261 <listitem><para><emphasis>Graphical Extras:</emphasis>
262 Packages recommended if the host system has graphics support:
263 <literallayout class='monospaced'>
264 $ sudo zypper install libSDL-devel xterm
265 </literallayout></para></listitem>
266 <listitem><para><emphasis>Documentation:</emphasis>
267 Packages needed if you are going to build out the
268 Yocto Project documentation manuals:
269 <literallayout class='monospaced'>
270 $ sudo zypper install make fop xsltproc dblatex xmlto
271 </literallayout></para></listitem>
272 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
273 Packages needed if you are going to be using the
274 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
275 <literallayout class='monospaced'>
276 $ sudo zypper install autoconf automake libtool glib2-devel
277 </literallayout></para></listitem>
278 </itemizedlist>
279 </para>
280 </section>
281
282 <section id='centos-packages'>
283 <title>CentOS Packages</title>
284
285 <para>
286 The following list shows the required packages by function
287 given a supported CentOS Linux distribution:
288 <note>Depending on the CentOS version you are using, other requirements
289 and dependencies might exist.
290 For details, you should look at the CentOS sections on the
291 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
292 wiki page.
293 </note>
294 <itemizedlist>
295 <listitem><para><emphasis>Essentials:</emphasis>
296 Packages needed to build an image for a headless
297 system:
298 <literallayout class='monospaced'>
299 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
300 </literallayout></para></listitem>
301 <listitem><para><emphasis>Graphical Extras:</emphasis>
302 Packages recommended if the host system has graphics support:
303 <literallayout class='monospaced'>
304 $ sudo yum install SDL-devel xterm
305 </literallayout></para></listitem>
306 <listitem><para><emphasis>Documentation:</emphasis>
307 Packages needed if you are going to build out the
308 Yocto Project documentation manuals:
309 <literallayout class='monospaced'>
310 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
311 docbook-dtds docbook-utils fop libxslt dblatex xmlto
312 </literallayout></para></listitem>
313 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
314 Packages needed if you are going to be using the
315 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
316 <literallayout class='monospaced'>
317 $ sudo yum install autoconf automake libtool glib2-devel
318 </literallayout></para></listitem>
319 </itemizedlist>
320 </para>
321 </section>
322 </section>
323
324 <section id='required-git-tar-and-python-versions'>
325 <title>Required Git, tar, and Python Versions</title>
326
327 <para>
328 In order to use the build system, your host development system
329 must meet the following version requirements for Git, tar, and
330 Python:
331 <itemizedlist>
332 <listitem><para>Git 1.7.5 or greater</para></listitem>
333 <listitem><para>tar 1.24 or greater</para></listitem>
334 <listitem><para>Python 2.7.3 or greater not including
335 Python 3.x, which is not supported.</para></listitem>
336 </itemizedlist>
337 </para>
338
339 <para>
340 If your host development system does not meet all these requirements,
341 you can resolve this by either downloading a pre-built tarball
342 containing these tools, or building such a tarball on another
343 system.
344 Regardless of the method, once you have the tarball, you simply
345 install it somewhere on your system, such as a directory in your
346 home directory, and then source the environment script provided,
347 which adds the tools into <filename>PATH</filename> and sets
348 any other environment variables required to run the tools.
349 Doing so gives you working versions of Git, tar, Python and
350 <filename>chrpath</filename>.
351 </para>
352
353 <para>
354 If downloading a pre-built tarball, locate the
355 <filename>*.sh</filename> at
356 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
357 </para>
358
359 <para>
360 If building your own tarball, do so using this command:
361 <literallayout class='monospaced'>
362 $ bitbake buildtools-tarball
363 </literallayout>
364 <note>
365 The <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
366 variable determines whether you build tools for a 32-bit
367 or 64-bit system.
368 </note>
369 Once the build completes, you can find the file that installs the
370 the tools in the <filename>tmp/deploy/sdk</filename> subdirectory
371 of the
372 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
373 The file used to install the tarball has the string "buildtools"
374 in the name.
375 </para>
376
377 <para>
378 After you have either built the tarball or downloaded it, you need
379 to install it.
380 Install the tools by executing the <filename>*.sh</filename> file.
381 During execution, a prompt appears that allows you to choose the
382 installation directory.
383 For example, you could choose the following:
384 <literallayout class='monospaced'>
385 /home/your-username/sdk
386 </literallayout>
387 </para>
388
389 <para>
390 The final step before you can actually use the tools is to source
391 the tools environment with a command like the following:
392 <literallayout class='monospaced'>
393 $ source /home/your-username/sdk/environment-setup-i586-poky-linux
394 </literallayout>
395 Of course, you need to supply your installation directory and be
396 sure to use the right file (i.e. i585 or x86-64).
397 </para>
398 </section>
399</section>
400
401<section id='intro-getit'>
402 <title>Obtaining the Yocto Project</title>
403 <para>
404 The Yocto Project development team makes the Yocto Project available through a number
405 of methods:
406 <itemizedlist>
407 <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through
408 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
409 <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
410 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
411 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
412 experimental builds.</para></listitem>
413 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
414 of the Yocto Project and supported BSPs at the
415 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
416 Along with these downloads, you can find lots of other information at this site.
417 </para></listitem>
418 </itemizedlist>
419 </para>
420</section>
421
422<section id='intro-getit-dev'>
423 <title>Development Checkouts</title>
424 <para>
425 Development using the Yocto Project requires a local
426 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
427 You can set up the Source Directory by downloading a Yocto Project release tarball and unpacking it,
428 or by cloning a copy of the upstream
429 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
430 For information on both these methods, see the
431 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
432 section in the Yocto Project Development Manual.
433 </para>
434</section>
435
436</chapter>
437<!--
438vim: expandtab tw=80 ts=4
439-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-13 05:53:38 +0000