summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/introduction.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-05 15:43:42 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:27 +0000
commit60cfd0785b2d64ec808e08ad9f716047542d8ba9 (patch)
tree7c103c1a8bab35c1e0814566fde3215936596290 /documentation/ref-manual/introduction.xml
parentc06a654c1d14f20b31256298543e2e3504acc0a9 (diff)
downloadpoky-60cfd0785b2d64ec808e08ad9f716047542d8ba9.tar.gz
ref-manual: Separated terms into separate chapter
Pulling out some introductory information from the old "Introduction" chapter of the ref-manual has isolated the system requirements and term definitions sections. I have decided to create a new chapter for terms as they are a reference item. This leaves system requirements also alone as a new chapter. So, I dumped the introduction.xml chapter in favor of the two new chapters. (From yocto-docs rev: 35c41b3008845c94e10be19b37409b0d1a469ff5) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/introduction.xml')
-rw-r--r--documentation/ref-manual/introduction.xml937
1 files changed, 0 insertions, 937 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
deleted file mode 100644
index 098dbc8a22..0000000000
--- a/documentation/ref-manual/introduction.xml
+++ /dev/null
@@ -1,937 +0,0 @@
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='ref-manual-intro'>
6<title>Introduction</title>
7
8<section id='ref-welcome'>
9 <title>Welcome</title>
10
11 <para>
12 Welcome to the Yocto Project Reference Manual.
13 This manual provides reference information for the current release
14 of the Yocto Project.
15 This manual is best used after you have an understanding
16 of the basics of the Yocto Project.
17 The manual is neither meant to be read as a starting point to the
18 Yocto Project nor read from start to finish.
19 Use this manual to find concepts, variable definitions, class
20 descriptions, and so forth as needed during the course of using
21 the Yocto Project.
22 </para>
23
24 <para>
25 For introductory information on the Yocto Project, see the
26 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the
27 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#overview-development-environment'>Yocto Project Development Environment</ulink>"
28 chapter in the Yocto Project Overview Manual.
29 </para>
30
31 <para>
32 If you want to use the Yocto Project to test run building an image
33 without having to understand concepts, work through the
34 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
35 You can find "how-to" information in the
36 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>.
37 <note><title>Tip</title>
38 For more information about the Yocto Project Documentation set,
39 see the
40 "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
41 section.
42 </note>
43 </para>
44</section>
45
46<section id='intro-requirements'>
47<title>System Requirements</title>
48 <para>
49 For general Yocto Project system requirements, see the
50 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section
51 in the Yocto Project Quick Start.
52 The remainder of this section provides details on system requirements
53 not covered in the Yocto Project Quick Start.
54 </para>
55
56 <section id='detailed-supported-distros'>
57 <title>Supported Linux Distributions</title>
58
59 <para>
60 Currently, the Yocto Project is supported on the following
61 distributions:
62 <note>
63 <para>
64 Yocto Project releases are tested against the stable Linux
65 distributions in the following list.
66 The Yocto Project should work on other distributions but
67 validation is not performed against them.
68 </para>
69
70 <para>
71 In particular, the Yocto Project does not support
72 and currently has no plans to support
73 rolling-releases or development distributions due to their
74 constantly changing nature.
75 We welcome patches and bug reports, but keep in mind that
76 our priority is on the supported platforms listed below.
77 </para>
78
79 <para>
80 If you encounter problems, please go to
81 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
82 and submit a bug.
83 We are interested in hearing about your experience.
84 </para>
85 </note>
86 <itemizedlist>
87<!--
88 <listitem><para>Ubuntu 10.04</para></listitem>
89 <listitem><para>Ubuntu 11.10</para></listitem>
90 <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
91 <listitem><para>Ubuntu 13.10</para></listitem> -->
92 <listitem><para>Ubuntu 14.04 (LTS)</para></listitem>
93 <listitem><para>Ubuntu 14.10</para></listitem>
94 <listitem><para>Ubuntu 15.04</para></listitem>
95 <listitem><para>Ubuntu 15.10</para></listitem>
96 <listitem><para>Ubuntu 16.04</para></listitem>
97<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>
98 <listitem><para>Fedora 17 (Spherical)</para></listitem>
99 <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
100 <listitem><para>Fedora release 20 (Heisenbug)</para></listitem> -->
101 <listitem><para>Fedora release 22</para></listitem>
102 <listitem><para>Fedora release 23</para></listitem>
103<!-- <listitem><para>Fedora release 24</para></listitem>
104 <listitem><para>CentOS release 5.6 (Final)</para></listitem>
105 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
106 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
107 <listitem><para>CentOS release 6.3 (Final)</para></listitem>
108 <listitem><para>CentOS release 6.x</para></listitem> -->
109 <listitem><para>CentOS release 7.x</para></listitem>
110<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>
111 <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> -->
112 <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
113 <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
114<!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
115 <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
116 <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
117 <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
118 <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>
119 <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem> -->
120<!-- <listitem><para>openSUSE 11.4</para></listitem>
121 <listitem><para>openSUSE 12.1</para></listitem>
122 <listitem><para>openSUSE 12.2</para></listitem>
123 <listitem><para>openSUSE 12.3</para></listitem>
124 <listitem><para>openSUSE 13.1</para></listitem> -->
125 <listitem><para>openSUSE 13.2</para></listitem>
126 <listitem><para>openSUSE 42.1</para></listitem>
127 </itemizedlist>
128 </para>
129
130 <note>
131 While the Yocto Project Team attempts to ensure all Yocto Project
132 releases are one hundred percent compatible with each officially
133 supported Linux distribution, instances might exist where you
134 encounter a problem while using the Yocto Project on a specific
135 distribution.
136 </note>
137 </section>
138
139 <section id='required-packages-for-the-host-development-system'>
140 <title>Required Packages for the Host Development System</title>
141
142 <para>
143 The list of packages you need on the host development system can
144 be large when covering all build scenarios using the Yocto Project.
145 This section provides required packages according to
146 Linux distribution and function.
147 </para>
148
149 <section id='ubuntu-packages'>
150 <title>Ubuntu and Debian</title>
151
152 <para>
153 The following list shows the required packages by function
154 given a supported Ubuntu or Debian Linux distribution:
155 <note>
156 If your build system has the
157 <filename>oss4-dev</filename> package installed, you
158 might experience QEMU build failures due to the package
159 installing its own custom
160 <filename>/usr/include/linux/soundcard.h</filename> on
161 the Debian system.
162 If you run into this situation, either of the following
163 solutions exist:
164 <literallayout class='monospaced'>
165 $ sudo apt-get build-dep qemu
166 $ sudo apt-get remove oss4-dev
167 </literallayout>
168 </note>
169 <itemizedlist>
170 <listitem><para><emphasis>Essentials:</emphasis>
171 Packages needed to build an image on a headless
172 system:
173 <literallayout class='monospaced'>
174 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
175 </literallayout></para></listitem>
176 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
177 Packages recommended if the host system has graphics
178 support or if you are going to use the Eclipse
179 IDE:
180 <literallayout class='monospaced'>
181 $ sudo apt-get install libsdl1.2-dev xterm
182 </literallayout></para></listitem>
183 <listitem><para><emphasis>Documentation:</emphasis>
184 Packages needed if you are going to build out the
185 Yocto Project documentation manuals:
186 <literallayout class='monospaced'>
187 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
188 </literallayout></para></listitem>
189 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
190 Packages needed if you are going to run
191 <filename>oe-selftest</filename>:
192 <literallayout class='monospaced'>
193 $ sudo apt-get install python-git
194 </literallayout>
195 </para></listitem>
196 </itemizedlist>
197 </para>
198 </section>
199
200 <section id='fedora-packages'>
201 <title>Fedora Packages</title>
202
203 <para>
204 The following list shows the required packages by function
205 given a supported Fedora Linux distribution:
206 <itemizedlist>
207 <listitem><para><emphasis>Essentials:</emphasis>
208 Packages needed to build an image for a headless
209 system:
210 <literallayout class='monospaced'>
211 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
212 </literallayout></para></listitem>
213 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
214 Packages recommended if the host system has graphics
215 support or if you are going to use the Eclipse
216 IDE:
217 <literallayout class='monospaced'>
218 $ sudo dnf install SDL-devel xterm
219 </literallayout></para></listitem>
220 <listitem><para><emphasis>Documentation:</emphasis>
221 Packages needed if you are going to build out the
222 Yocto Project documentation manuals:
223 <literallayout class='monospaced'>
224 $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \
225 docbook-dtds docbook-utils fop libxslt dblatex xmlto
226 </literallayout></para></listitem>
227 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
228 Packages needed if you are going to run
229 <filename>oe-selftest</filename>:
230 <literallayout class='monospaced'>
231 $ sudo dnf install python3-GitPython
232 </literallayout>
233 </para></listitem>
234 </itemizedlist>
235 </para>
236 </section>
237
238 <section id='opensuse-packages'>
239 <title>openSUSE Packages</title>
240
241 <para>
242 The following list shows the required packages by function
243 given a supported openSUSE Linux distribution:
244 <itemizedlist>
245 <listitem><para><emphasis>Essentials:</emphasis>
246 Packages needed to build an image for a headless
247 system:
248 <literallayout class='monospaced'>
249 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
250 </literallayout></para></listitem>
251 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
252 Packages recommended if the host system has graphics
253 support or if you are going to use the Eclipse
254 IDE:
255 <literallayout class='monospaced'>
256 $ sudo zypper install libSDL-devel xterm
257 </literallayout></para></listitem>
258 <listitem><para><emphasis>Documentation:</emphasis>
259 Packages needed if you are going to build out the
260 Yocto Project documentation manuals:
261 <literallayout class='monospaced'>
262 $ sudo zypper install make dblatex xmlto
263 </literallayout></para></listitem>
264 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
265 Packages needed if you are going to run
266 <filename>oe-selftest</filename>:
267 <literallayout class='monospaced'>
268 $ sudo zypper install python-GitPython
269 </literallayout></para></listitem>
270 </itemizedlist>
271 <note>
272 Sanity testing, through the
273 <link linkend='ref-classes-testimage*'>testimage</link>
274 classes, does not work on systems using the
275 <ulink url='https://en.opensuse.org/Portal:Wicked'>Wicked</ulink>
276 network manager.
277 </note>
278 </para>
279 </section>
280
281 <section id='centos-packages'>
282 <title>CentOS Packages</title>
283
284 <para>
285 The following list shows the required packages by function
286 given a supported CentOS Linux distribution:
287 <note>
288 For CentOS 6.x, some of the versions of the components
289 provided by the distribution are too old (e.g. Git, Python,
290 and tar).
291 It is recommended that you install the buildtools in order
292 to provide versions that will work with the OpenEmbedded
293 build system.
294 For information on how to install the buildtools tarball,
295 see the
296 "<link linkend='required-git-tar-and-python-versions'>Required Git, Tar, and Python Versions</link>"
297 section.
298 </note>
299 <itemizedlist>
300 <listitem><para><emphasis>Essentials:</emphasis>
301 Packages needed to build an image for a headless
302 system:
303 <literallayout class='monospaced'>
304 $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
305 </literallayout>
306 <note><title>Notes</title>
307 <itemizedlist>
308 <listitem><para>
309 Extra Packages for Enterprise Linux
310 (i.e. <filename>epel-release</filename>)
311 is a collection of packages from Fedora
312 built on RHEL/CentOS for easy installation
313 of packages not included in enterprise
314 Linux by default.
315 You need to install these packages
316 separately.
317 </para></listitem>
318 <listitem><para>
319 The <filename>makecache</filename> command
320 consumes additional Metadata from
321 <filename>epel-release</filename>.
322 </para></listitem>
323 </itemizedlist>
324 </note>
325 </para></listitem>
326 <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>
327 Packages recommended if the host system has graphics
328 support or if you are going to use the Eclipse
329 IDE:
330 <literallayout class='monospaced'>
331 $ sudo yum install SDL-devel xterm
332 </literallayout></para></listitem>
333 <listitem><para><emphasis>Documentation:</emphasis>
334 Packages needed if you are going to build out the
335 Yocto Project documentation manuals:
336 <literallayout class='monospaced'>
337 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
338 docbook-dtds docbook-utils fop libxslt dblatex xmlto
339 </literallayout></para></listitem>
340 <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>
341 Packages needed if you are going to run
342 <filename>oe-selftest</filename>:
343 <literallayout class='monospaced'>
344 $ sudo yum install GitPython
345 </literallayout>
346 </para></listitem>
347 </itemizedlist>
348 </para>
349 </section>
350 </section>
351
352 <section id='required-git-tar-and-python-versions'>
353 <title>Required Git, tar, and Python Versions</title>
354
355 <para>
356 In order to use the build system, your host development system
357 must meet the following version requirements for Git, tar, and
358 Python:
359 <itemizedlist>
360 <listitem><para>Git 1.8.3.1 or greater</para></listitem>
361 <listitem><para>tar 1.27 or greater</para></listitem>
362 <listitem><para>Python 3.4.0 or greater</para></listitem>
363 </itemizedlist>
364 </para>
365
366 <para>
367 If your host development system does not meet all these requirements,
368 you can resolve this by installing a <filename>buildtools</filename>
369 tarball that contains these tools.
370 You can get the tarball one of two ways: download a pre-built
371 tarball or use BitBake to build the tarball.
372 </para>
373
374 <section id='downloading-a-pre-built-buildtools-tarball'>
375 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
376
377 <para>
378 Downloading and running a pre-built buildtools installer is
379 the easiest of the two methods by which you can get these tools:
380 <orderedlist>
381 <listitem><para>
382 Locate and download the <filename>*.sh</filename> at
383 <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.
384 </para></listitem>
385 <listitem><para>
386 Execute the installation script.
387 Here is an example:
388 <literallayout class='monospaced'>
389 $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
390 </literallayout>
391 During execution, a prompt appears that allows you to
392 choose the installation directory.
393 For example, you could choose the following:
394 <literallayout class='monospaced'>
395 /home/<replaceable>your-username</replaceable>/buildtools
396 </literallayout>
397 </para></listitem>
398 <listitem><para>
399 Source the tools environment setup script by using a
400 command like the following:
401 <literallayout class='monospaced'>
402 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
403 </literallayout>
404 Of course, you need to supply your installation directory and be
405 sure to use the right file (i.e. i585 or x86-64).
406 </para>
407 <para>
408 After you have sourced the setup script,
409 the tools are added to <filename>PATH</filename>
410 and any other environment variables required to run the
411 tools are initialized.
412 The results are working versions versions of Git, tar,
413 Python and <filename>chrpath</filename>.
414 </para></listitem>
415 </orderedlist>
416 </para>
417 </section>
418
419 <section id='building-your-own-buildtools-tarball'>
420 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
421
422 <para>
423 Building and running your own buildtools installer applies
424 only when you have a build host that can already run BitBake.
425 In this case, you use that machine to build the
426 <filename>.sh</filename> file and then
427 take steps to transfer and run it on a
428 machine that does not meet the minimal Git, tar, and Python
429 requirements.
430 </para>
431
432 <para>
433 Here are the steps to take to build and run your own
434 buildtools installer:
435 <orderedlist>
436 <listitem><para>
437 On the machine that is able to run BitBake,
438 be sure you have set up your build environment with
439 the setup script
440 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
441 </para></listitem>
442 <listitem><para>
443 Run the BitBake command to build the tarball:
444 <literallayout class='monospaced'>
445 $ bitbake buildtools-tarball
446 </literallayout>
447 <note>
448 The
449 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
450 variable in your <filename>local.conf</filename> file
451 determines whether you build tools for a 32-bit
452 or 64-bit system.
453 </note>
454 Once the build completes, you can find the
455 <filename>.sh</filename> file that installs
456 the tools in the <filename>tmp/deploy/sdk</filename>
457 subdirectory of the
458 <link linkend='build-directory'>Build Directory</link>.
459 The installer file has the string "buildtools"
460 in the name.
461 </para></listitem>
462 <listitem><para>
463 Transfer the <filename>.sh</filename> file from the
464 build host to the machine that does not meet the
465 Git, tar, or Python requirements.
466 </para></listitem>
467 <listitem><para>
468 On the machine that does not meet the requirements,
469 run the <filename>.sh</filename> file
470 to install the tools.
471 Here is an example:
472 <literallayout class='monospaced'>
473 $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
474 </literallayout>
475 During execution, a prompt appears that allows you to
476 choose the installation directory.
477 For example, you could choose the following:
478 <literallayout class='monospaced'>
479 /home/<replaceable>your_username</replaceable>/buildtools
480 </literallayout>
481 </para></listitem>
482 <listitem><para>
483 Source the tools environment setup script by using a
484 command like the following:
485 <literallayout class='monospaced'>
486 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
487 </literallayout>
488 Of course, you need to supply your installation directory and be
489 sure to use the right file (i.e. i585 or x86-64).
490 </para>
491 <para>
492 After you have sourced the setup script,
493 the tools are added to <filename>PATH</filename>
494 and any other environment variables required to run the
495 tools are initialized.
496 The results are working versions versions of Git, tar,
497 Python and <filename>chrpath</filename>.
498 </para></listitem>
499 </orderedlist>
500 </para>
501 </section>
502 </section>
503</section>
504
505<section id='yocto-project-terms'>
506 <title>Yocto Project Terms</title>
507
508 <para>
509 Following is a list of terms and definitions users new to the Yocto
510 Project development environment might find helpful.
511 While some of these terms are universal, the list includes them
512 just in case:
513 <itemizedlist>
514 <listitem><para>
515 <emphasis>Append Files:</emphasis>
516 Files that append build information to a recipe file.
517 Append files are known as BitBake append files and
518 <filename>.bbappend</filename> files.
519 The OpenEmbedded build system expects every append file to have
520 a corresponding recipe (<filename>.bb</filename>) file.
521 Furthermore, the append file and corresponding recipe file
522 must use the same root filename.
523 The filenames can differ only in the file type suffix used
524 (e.g.
525 <filename>formfactor_0.0.bb</filename> and
526 <filename>formfactor_0.0.bbappend</filename>).</para>
527
528 <para>Information in append files extends or overrides the
529 information in the similarly-named recipe file.
530 For an example of an append file in use, see the
531 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
532 section in the Yocto Project Development Tasks Manual.
533 <note>
534 Append files can also use wildcard patterns in their
535 version numbers so they can be applied to more than one
536 version of the underlying recipe file.
537 </note>
538 </para></listitem>
539 <listitem><para id='bitbake-term'>
540 <emphasis>BitBake:</emphasis>
541 The task executor and scheduler used by the OpenEmbedded build
542 system to build images.
543 For more information on BitBake, see the
544 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
545 </para></listitem>
546 <listitem><para id='board-support-package-bsp-term'>
547 <emphasis>Board Support Package (BSP):</emphasis>
548 A group of drivers, definitions, and other components that
549 provide support for a specific hardware configuration.
550 For more information on BSPs, see the
551 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
552 </para></listitem>
553 <listitem>
554 <para id='build-directory'>
555 <emphasis>Build Directory:</emphasis>
556 This term refers to the area used by the OpenEmbedded build
557 system for builds.
558 The area is created when you <filename>source</filename> the
559 setup environment script that is found in the Source Directory
560 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
561 The
562 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
563 variable points to the Build Directory.</para>
564
565 <para>You have a lot of flexibility when creating the Build
566 Directory.
567 Following are some examples that show how to create the
568 directory.
569 The examples assume your
570 <link linkend='source-directory'>Source Directory</link> is
571 named <filename>poky</filename>:
572 <itemizedlist>
573 <listitem><para>Create the Build Directory inside your
574 Source Directory and let the name of the Build
575 Directory default to <filename>build</filename>:
576 <literallayout class='monospaced'>
577 $ cd $HOME/poky
578 $ source &OE_INIT_FILE;
579 </literallayout>
580 </para></listitem>
581 <listitem><para>Create the Build Directory inside your
582 home directory and specifically name it
583 <filename>test-builds</filename>:
584 <literallayout class='monospaced'>
585 $ cd $HOME
586 $ source poky/&OE_INIT_FILE; test-builds
587 </literallayout>
588 </para></listitem>
589 <listitem><para>
590 Provide a directory path and specifically name the
591 Build Directory.
592 Any intermediate folders in the pathname must exist.
593 This next example creates a Build Directory named
594 <filename>YP-&POKYVERSION;</filename>
595 in your home directory within the existing
596 directory <filename>mybuilds</filename>:
597 <literallayout class='monospaced'>
598 $cd $HOME
599 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
600 </literallayout>
601 </para></listitem>
602 </itemizedlist>
603 <note>
604 By default, the Build Directory contains
605 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
606 which is a temporary directory the build system uses for
607 its work.
608 <filename>TMPDIR</filename> cannot be under NFS.
609 Thus, by default, the Build Directory cannot be under NFS.
610 However, if you need the Build Directory to be under NFS,
611 you can set this up by setting <filename>TMPDIR</filename>
612 in your <filename>local.conf</filename> file
613 to use a local drive.
614 Doing so effectively separates <filename>TMPDIR</filename>
615 from <filename>TOPDIR</filename>, which is the Build
616 Directory.
617 </note>
618 </para></listitem>
619 <listitem><para id='hardware-build-system-term'>
620 <emphasis>Build System:</emphasis>
621 The system used to build images in a Yocto Project
622 Development environment.
623 The build system is sometimes referred to as the
624 development host.
625 </para></listitem>
626 <listitem><para>
627 <emphasis>Classes:</emphasis>
628 Files that provide for logic encapsulation and inheritance so
629 that commonly used patterns can be defined once and then
630 easily used in multiple recipes.
631 For reference information on the Yocto Project classes, see the
632 "<link linkend='ref-classes'>Classes</link>" chapter.
633 Class files end with the <filename>.bbclass</filename>
634 filename extension.
635 </para></listitem>
636 <listitem><para>
637 <emphasis>Configuration File:</emphasis>
638 Configuration information in various <filename>.conf</filename>
639 files provides global definitions of variables.
640 The <filename>conf/local.conf</filename> configuration file in
641 the
642 <link linkend='build-directory'>Build Directory</link>
643 contains user-defined variables that affect every build.
644 The <filename>meta-poky/conf/distro/poky.conf</filename>
645 configuration file defines Yocto "distro" configuration
646 variables used only when building with this policy.
647 Machine configuration files, which
648 are located throughout the
649 <link linkend='source-directory'>Source Directory</link>, define
650 variables for specific hardware and are only used when building
651 for that target (e.g. the
652 <filename>machine/beaglebone.conf</filename> configuration
653 file defines variables for the Texas Instruments ARM Cortex-A8
654 development board).
655 Configuration files end with a <filename>.conf</filename>
656 filename extension.
657 </para></listitem>
658 <listitem><para id='cross-development-toolchain'>
659 <emphasis>Cross-Development Toolchain:</emphasis>
660 In general, a cross-development toolchain is a collection of
661 software development tools and utilities that run on one
662 architecture and allow you to develop software for a
663 different, or targeted, architecture.
664 These toolchains contain cross-compilers, linkers, and
665 debuggers that are specific to the target architecture.</para>
666
667 <para>The Yocto Project supports two different cross-development
668 toolchains:
669 <itemizedlist>
670 <listitem><para>
671 A toolchain only used by and within
672 BitBake when building an image for a target
673 architecture.
674 </para></listitem>
675 <listitem><para>A relocatable toolchain used outside of
676 BitBake by developers when developing applications
677 that will run on a targeted device.
678 </para></listitem>
679 </itemizedlist></para>
680
681 <para>Creation of these toolchains is simple and automated.
682 For information on toolchain concepts as they apply to the
683 Yocto Project, see the
684 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
685 section.
686 You can also find more information on using the
687 relocatable toolchain in the
688 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
689 manual.
690 </para></listitem>
691 <listitem><para>
692 <emphasis>Image:</emphasis>
693 An image is an artifact of the BitBake build process given
694 a collection of recipes and related Metadata.
695 Images are the binary output that run on specific hardware or
696 QEMU and are used for specific use-cases.
697 For a list of the supported image types that the Yocto Project
698 provides, see the
699 "<link linkend='ref-images'>Images</link>"
700 chapter.
701 </para></listitem>
702 <listitem><para>
703 <emphasis>Layer:</emphasis>
704 A collection of recipes representing the core,
705 a BSP, or an application stack.
706 For a discussion specifically on BSP Layers, see the
707 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
708 section in the Yocto Project Board Support Packages (BSP)
709 Developer's Guide.
710 </para></listitem>
711 <listitem><para id='metadata'>
712 <emphasis>Metadata:</emphasis>
713 The files that BitBake parses when building an image.
714 In general, Metadata includes recipes, classes, and
715 configuration files.
716 In the context of the kernel ("kernel Metadata"), the
717 term refers to the kernel config fragments and features
718 contained in the
719 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
720 Git repository.
721 </para></listitem>
722 <listitem><para id='oe-core'>
723 <emphasis>OE-Core:</emphasis>
724 A core set of Metadata originating with OpenEmbedded (OE)
725 that is shared between OE and the Yocto Project.
726 This Metadata is found in the <filename>meta</filename>
727 directory of the
728 <link linkend='source-directory'>Source Directory</link>.
729 </para></listitem>
730 <listitem><para id='build-system-term'>
731 <emphasis>OpenEmbedded Build System:</emphasis>
732 The build system specific to the Yocto Project.
733 The OpenEmbedded build system is based on another project known
734 as "Poky", which uses
735 <link linkend='bitbake-term'>BitBake</link> as the task
736 executor.
737 Throughout the Yocto Project documentation set, the
738 OpenEmbedded build system is sometimes referred to simply
739 as "the build system".
740 If other build systems, such as a host or target build system
741 are referenced, the documentation clearly states the
742 difference.
743 <note>
744 For some historical information about Poky, see the
745 <link linkend='poky'>Poky</link> term.
746 </note>
747 </para></listitem>
748 <listitem><para>
749 <emphasis>Package:</emphasis>
750 In the context of the Yocto Project, this term refers to a
751 recipe's packaged output produced by BitBake (i.e. a
752 "baked recipe").
753 A package is generally the compiled binaries produced from the
754 recipe's sources.
755 You "bake" something by running it through BitBake.</para>
756
757 <para>It is worth noting that the term "package" can,
758 in general, have subtle meanings.
759 For example, the packages referred to in the
760 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
761 section in the Yocto Project Quick Start are compiled binaries
762 that, when installed, add functionality to your Linux
763 distribution.</para>
764
765 <para>Another point worth noting is that historically within
766 the Yocto Project, recipes were referred to as packages - thus,
767 the existence of several BitBake variables that are seemingly
768 mis-named,
769 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
770 <link linkend='var-PV'><filename>PV</filename></link>, and
771 <link linkend='var-PE'><filename>PE</filename></link>).
772 </para></listitem>
773 <listitem><para>
774 <emphasis>Package Groups:</emphasis>
775 Arbitrary groups of software Recipes.
776 You use package groups to hold recipes that, when built,
777 usually accomplish a single task.
778 For example, a package group could contain the recipes for a
779 company’s proprietary or value-add software.
780 Or, the package group could contain the recipes that enable
781 graphics.
782 A package group is really just another recipe.
783 Because package group files are recipes, they end with the
784 <filename>.bb</filename> filename extension.
785 </para></listitem>
786 <listitem><para id='poky'>
787 <emphasis>Poky:</emphasis>
788 The term "poky", which is pronounced
789 <emphasis>Pah</emphasis>-kee, can mean several things:
790 <itemizedlist>
791 <listitem><para>
792 In its most general sense, poky is an open-source
793 project that was initially developed by OpenedHand.
794 OpenedHand developed poky off of the existing
795 OpenEmbedded build system to create a commercially
796 supportable build system for embedded Linux.
797 After Intel Corporation acquired OpenedHand, the
798 poky project became the basis for the Yocto Project's
799 build system.
800 </para></listitem>
801 <listitem><para>
802 Within the Yocto Project
803 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>,
804 "poky" exists as a separate Git
805 repository from which you can clone to yield a local
806 Git repository that is a copy on your host system.
807 Thus, "poky" can refer to the upstream or
808 local copy of the files used for development within
809 the Yocto Project.
810 </para></listitem>
811 <listitem><para>
812 Finally, "poky" can refer to the default
813 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
814 (i.e. distribution) created when you use the Yocto
815 Project in conjunction with the
816 <filename>poky</filename> repository to build an image.
817 </para></listitem>
818 </itemizedlist>
819 </para></listitem>
820 <listitem><para>
821 <emphasis>Recipe:</emphasis>
822 A set of instructions for building packages.
823 A recipe describes where you get source code, which patches
824 to apply, how to configure the source, how to compile it and so on.
825 Recipes also describe dependencies for libraries or for other
826 recipes.
827 Recipes represent the logical unit of execution, the software
828 to build, the images to build, and use the
829 <filename>.bb</filename> file extension.
830 </para></listitem>
831 <listitem><para id='reference-kit-term'>
832 <emphasis>Reference Kit:</emphasis>
833 A working example of a system, which includes a
834 <link linkend='board-support-package-bsp-term'>BSP</link>
835 as well as a
836 <link linkend='hardware-build-system-term'>build system</link>
837 and other components, that can work on specific hardware.
838 </para></listitem>
839 <listitem>
840 <para id='source-directory'>
841 <emphasis>Source Directory:</emphasis>
842 This term refers to the directory structure created as a result
843 of creating a local copy of the <filename>poky</filename> Git
844 repository <filename>git://git.yoctoproject.org/poky</filename>
845 or expanding a released <filename>poky</filename> tarball.
846 <note>
847 Creating a local copy of the <filename>poky</filename>
848 Git repository is the recommended method for setting up
849 your Source Directory.
850 </note>
851 Sometimes you might hear the term "poky directory" used to refer
852 to this directory structure.
853 <note>
854 The OpenEmbedded build system does not support file or
855 directory names that contain spaces.
856 Be sure that the Source Directory you use does not contain
857 these types of names.
858 </note></para>
859
860 <para>The Source Directory contains BitBake, Documentation,
861 Metadata and other files that all support the Yocto Project.
862 Consequently, you must have the Source Directory in place on
863 your development system in order to do any development using
864 the Yocto Project.</para>
865
866 <para>When you create a local copy of the Git repository, you
867 can name the repository anything you like.
868 Throughout much of the documentation, "poky"
869 is used as the name of the top-level folder of the local copy of
870 the poky Git repository.
871 So, for example, cloning the <filename>poky</filename> Git
872 repository results in a local Git repository whose top-level
873 folder is also named "poky".</para>
874
875 <para>While it is not recommended that you use tarball expansion
876 to set up the Source Directory, if you do, the top-level
877 directory name of the Source Directory is derived from the
878 Yocto Project release tarball.
879 For example, downloading and unpacking
880 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
881 Source Directory whose root folder is named
882 <filename>&YOCTO_POKY;</filename>.</para>
883
884 <para>It is important to understand the differences between the
885 Source Directory created by unpacking a released tarball as
886 compared to cloning
887 <filename>git://git.yoctoproject.org/poky</filename>.
888 When you unpack a tarball, you have an exact copy of the files
889 based on the time of release - a fixed release point.
890 Any changes you make to your local files in the Source Directory
891 are on top of the release and will remain local only.
892 On the other hand, when you clone the <filename>poky</filename>
893 Git repository, you have an active development repository with
894 access to the upstream repository's branches and tags.
895 In this case, any local changes you make to the local
896 Source Directory can be later applied to active development
897 branches of the upstream <filename>poky</filename> Git
898 repository.</para>
899
900 <para>For more information on concepts related to Git
901 repositories, branches, and tags, see the
902 "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
903 section in the Yocto Project Overview Manual.
904 </para></listitem>
905 <listitem><para><emphasis>Task:</emphasis>
906 A unit of execution for BitBake (e.g.
907 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
908 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
909 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
910 and so forth).
911 </para></listitem>
912 <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
913 A web interface to the Yocto Project's
914 <link linkend='build-system-term'>OpenEmbedded Build System</link>.
915 The interface enables you to configure and run your builds.
916 Information about builds is collected and stored in a database.
917 For information on Toaster, see the
918 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>.
919 </para></listitem>
920 <listitem><para>
921 <emphasis>Upstream:</emphasis>
922 A reference to source code or repositories
923 that are not local to the development system but located in a
924 master area that is controlled by the maintainer of the source
925 code.
926 For example, in order for a developer to work on a particular
927 piece of code, they need to first get a copy of it from an
928 "upstream" source.
929 </para></listitem>
930 </itemizedlist>
931 </para>
932</section>
933
934</chapter>
935<!--
936vim: expandtab tw=80 ts=4
937-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-07-30 20:25:20 +0000