diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-01-05 15:43:42 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-02-14 15:25:27 +0000 |
commit | 60cfd0785b2d64ec808e08ad9f716047542d8ba9 (patch) | |
tree | 7c103c1a8bab35c1e0814566fde3215936596290 /documentation/ref-manual/introduction.xml | |
parent | c06a654c1d14f20b31256298543e2e3504acc0a9 (diff) | |
download | poky-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.xml | 937 |
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 | <!-- | ||
936 | vim: expandtab tw=80 ts=4 | ||
937 | --> | ||