diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2017-06-13 16:14:51 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-06-22 09:16:42 +0100 |
commit | 45b16e35b606cfd2c4ab7f89ebe91e43995acb2a (patch) | |
tree | 0b0399cb502f85ab8f85ddd4bbe07614071ae08e /documentation/ref-manual/introduction.xml | |
parent | dccca9af475effc9389844f2a9a0466c035569ce (diff) | |
download | poky-45b16e35b606cfd2c4ab7f89ebe91e43995acb2a.tar.gz |
documentation: Fixed links to "bitbake-term"
Fixes [YOCTO #11630]
Moving the "Yocto Project Terms" section from the dev-manual to
the ref-manual. Doing so caused all the links to the id
"bitbake-term" to break. These had to be individually fixed.
Discovered two unresolved references that were a consequence of
moving that section to the ref-manual. These were fixed as well.
(From yocto-docs rev: 829ca6b64562f00a69f3956e9636c7edaa90ce16)
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 | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index 7423467150..58ee073868 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml | |||
@@ -39,6 +39,354 @@ | |||
39 | </para> | 39 | </para> |
40 | </section> | 40 | </section> |
41 | 41 | ||
42 | <section id='yocto-project-terms'> | ||
43 | <title>Yocto Project Terms</title> | ||
44 | |||
45 | <para> | ||
46 | Following is a list of terms and definitions users new to the Yocto Project development | ||
47 | environment might find helpful. | ||
48 | While some of these terms are universal, the list includes them just in case: | ||
49 | <itemizedlist> | ||
50 | <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to | ||
51 | a recipe file. | ||
52 | Append files are known as BitBake append files and <filename>.bbappend</filename> files. | ||
53 | The OpenEmbedded build system expects every append file to have a corresponding | ||
54 | recipe (<filename>.bb</filename>) file. | ||
55 | Furthermore, the append file and corresponding recipe file | ||
56 | must use the same root filename. | ||
57 | The filenames can differ only in the file type suffix used (e.g. | ||
58 | <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). | ||
59 | </para> | ||
60 | <para>Information in append files extends or overrides the | ||
61 | information in the similarly-named recipe file. | ||
62 | For an example of an append file in use, see the | ||
63 | "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>" | ||
64 | section in the Yocto Project Development Manual. | ||
65 | <note> | ||
66 | Append files can also use wildcard patterns in their version numbers | ||
67 | so they can be applied to more than one version of the underlying recipe file. | ||
68 | </note> | ||
69 | </para></listitem> | ||
70 | <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> | ||
71 | The task executor and scheduler used by the OpenEmbedded build | ||
72 | system to build images. | ||
73 | For more information on BitBake, see the | ||
74 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
75 | </para></listitem> | ||
76 | <listitem> | ||
77 | <para id='build-directory'><emphasis>Build Directory:</emphasis> | ||
78 | This term refers to the area used by the OpenEmbedded build | ||
79 | system for builds. | ||
80 | The area is created when you <filename>source</filename> the | ||
81 | setup environment script that is found in the Source Directory | ||
82 | (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> | ||
83 | or | ||
84 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). | ||
85 | The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> | ||
86 | variable points to the Build Directory.</para> | ||
87 | |||
88 | <para> | ||
89 | You have a lot of flexibility when creating the Build | ||
90 | Directory. | ||
91 | Following are some examples that show how to create the | ||
92 | directory. | ||
93 | The examples assume your | ||
94 | <link linkend='source-directory'>Source Directory</link> is | ||
95 | named <filename>poky</filename>: | ||
96 | <itemizedlist> | ||
97 | <listitem><para>Create the Build Directory inside your | ||
98 | Source Directory and let the name of the Build | ||
99 | Directory default to <filename>build</filename>: | ||
100 | <literallayout class='monospaced'> | ||
101 | $ cd $HOME/poky | ||
102 | $ source &OE_INIT_FILE; | ||
103 | </literallayout></para></listitem> | ||
104 | <listitem><para>Create the Build Directory inside your | ||
105 | home directory and specifically name it | ||
106 | <filename>test-builds</filename>: | ||
107 | <literallayout class='monospaced'> | ||
108 | $ cd $HOME | ||
109 | $ source poky/&OE_INIT_FILE; test-builds | ||
110 | </literallayout></para></listitem> | ||
111 | <listitem><para> | ||
112 | Provide a directory path and | ||
113 | specifically name the Build Directory. | ||
114 | Any intermediate folders in the pathname must | ||
115 | exist. | ||
116 | This next example creates a Build Directory named | ||
117 | <filename>YP-&POKYVERSION;</filename> | ||
118 | in your home directory within the existing | ||
119 | directory <filename>mybuilds</filename>: | ||
120 | <literallayout class='monospaced'> | ||
121 | $cd $HOME | ||
122 | $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; | ||
123 | </literallayout></para></listitem> | ||
124 | </itemizedlist> | ||
125 | <note> | ||
126 | By default, the Build Directory contains | ||
127 | <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, | ||
128 | which is a temporary directory the build system uses for | ||
129 | its work. | ||
130 | <filename>TMPDIR</filename> cannot be under NFS. | ||
131 | Thus, by default, the Build Directory cannot be under NFS. | ||
132 | However, if you need the Build Directory to be under NFS, | ||
133 | you can set this up by setting <filename>TMPDIR</filename> | ||
134 | in your <filename>local.conf</filename> file | ||
135 | to use a local drive. | ||
136 | Doing so effectively separates <filename>TMPDIR</filename> | ||
137 | from <filename>TOPDIR</filename>, which is the Build | ||
138 | Directory. | ||
139 | </note> | ||
140 | </para></listitem> | ||
141 | <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation | ||
142 | and inheritance so that commonly used patterns can be defined once and then easily used | ||
143 | in multiple recipes. | ||
144 | For reference information on the Yocto Project classes, see the | ||
145 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the | ||
146 | Yocto Project Reference Manual. | ||
147 | Class files end with the <filename>.bbclass</filename> filename extension. | ||
148 | </para></listitem> | ||
149 | <listitem><para><emphasis>Configuration File:</emphasis> | ||
150 | Configuration information in various <filename>.conf</filename> | ||
151 | files provides global definitions of variables. | ||
152 | The <filename>conf/local.conf</filename> configuration file in | ||
153 | the | ||
154 | <link linkend='build-directory'>Build Directory</link> | ||
155 | contains user-defined variables that affect every build. | ||
156 | The <filename>meta-poky/conf/distro/poky.conf</filename> | ||
157 | configuration file defines Yocto "distro" configuration | ||
158 | variables used only when building with this policy. | ||
159 | Machine configuration files, which | ||
160 | are located throughout the | ||
161 | <link linkend='source-directory'>Source Directory</link>, define | ||
162 | variables for specific hardware and are only used when building | ||
163 | for that target (e.g. the | ||
164 | <filename>machine/beaglebone.conf</filename> configuration | ||
165 | file defines variables for the Texas Instruments ARM Cortex-A8 | ||
166 | development board). | ||
167 | Configuration files end with a <filename>.conf</filename> | ||
168 | filename extension. | ||
169 | </para></listitem> | ||
170 | <listitem><para id='cross-development-toolchain'> | ||
171 | <emphasis>Cross-Development Toolchain:</emphasis> | ||
172 | In general, a cross-development toolchain is a collection of | ||
173 | software development tools and utilities that run on one | ||
174 | architecture and allow you to develop software for a | ||
175 | different, or targeted, architecture. | ||
176 | These toolchains contain cross-compilers, linkers, and | ||
177 | debuggers that are specific to the target architecture. | ||
178 | </para> | ||
179 | |||
180 | <para>The Yocto Project supports two different cross-development | ||
181 | toolchains: | ||
182 | <itemizedlist> | ||
183 | <listitem><para>A toolchain only used by and within | ||
184 | BitBake when building an image for a target | ||
185 | architecture.</para></listitem> | ||
186 | <listitem><para>A relocatable toolchain used outside of | ||
187 | BitBake by developers when developing applications | ||
188 | that will run on a targeted device. | ||
189 | </para></listitem> | ||
190 | </itemizedlist> | ||
191 | </para> | ||
192 | |||
193 | <para> | ||
194 | Creation of these toolchains is simple and automated. | ||
195 | For information on toolchain concepts as they apply to the | ||
196 | Yocto Project, see the | ||
197 | "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" | ||
198 | section in the Yocto Project Reference Manual. | ||
199 | You can also find more information on using the | ||
200 | relocatable toolchain in the | ||
201 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. | ||
202 | </para></listitem> | ||
203 | <listitem><para><emphasis>Image:</emphasis> | ||
204 | An image is an artifact of the BitBake build process given | ||
205 | a collection of recipes and related Metadata. | ||
206 | Images are the binary output that run on specific hardware or | ||
207 | QEMU and are used for specific use-cases. | ||
208 | For a list of the supported image types that the Yocto Project provides, see the | ||
209 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
210 | chapter in the Yocto Project Reference Manual.</para></listitem> | ||
211 | <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, | ||
212 | a BSP, or an application stack. | ||
213 | For a discussion specifically on BSP Layers, see the | ||
214 | "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" | ||
215 | section in the Yocto Project Board Support Packages (BSP) | ||
216 | Developer's Guide.</para></listitem> | ||
217 | <listitem><para id='metadata'><emphasis>Metadata:</emphasis> | ||
218 | The files that BitBake parses when building an image. | ||
219 | In general, Metadata includes recipes, classes, and | ||
220 | configuration files. | ||
221 | In the context of the kernel ("kernel Metadata"), | ||
222 | it refers to Metadata in the <filename>meta</filename> | ||
223 | branches of the kernel source Git repositories. | ||
224 | </para></listitem> | ||
225 | <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating | ||
226 | with OpenEmbedded (OE) that is shared between OE and the Yocto Project. | ||
227 | This Metadata is found in the <filename>meta</filename> directory of the | ||
228 | <link linkend='source-directory'>Source Directory</link>.</para></listitem> | ||
229 | <listitem><para id='build-system-term'><emphasis>OpenEmbedded Build System:</emphasis> | ||
230 | The build system specific to the Yocto Project. | ||
231 | The OpenEmbedded build system is based on another project known | ||
232 | as "Poky", which uses | ||
233 | <link linkend='bitbake-term'>BitBake</link> as the task | ||
234 | executor. | ||
235 | Throughout the Yocto Project documentation set, the | ||
236 | OpenEmbedded build system is sometimes referred to simply | ||
237 | as "the build system". | ||
238 | If other build systems, such as a host or target build system | ||
239 | are referenced, the documentation clearly states the | ||
240 | difference. | ||
241 | <note> | ||
242 | For some historical information about Poky, see the | ||
243 | <link linkend='poky'>Poky</link> term. | ||
244 | </note> | ||
245 | </para></listitem> | ||
246 | <listitem><para><emphasis>Package:</emphasis> | ||
247 | In the context of the Yocto Project, this term refers to a | ||
248 | recipe's packaged output produced by BitBake (i.e. a | ||
249 | "baked recipe"). | ||
250 | A package is generally the compiled binaries produced from the | ||
251 | recipe's sources. | ||
252 | You "bake" something by running it through BitBake.</para> | ||
253 | <para>It is worth noting that the term "package" can, in general, have subtle | ||
254 | meanings. For example, the packages referred to in the | ||
255 | "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" section are | ||
256 | compiled binaries that, when installed, add functionality to your Linux | ||
257 | distribution.</para> | ||
258 | <para>Another point worth noting is that historically within the Yocto Project, | ||
259 | recipes were referred to as packages - thus, the existence of several BitBake | ||
260 | variables that are seemingly mis-named, | ||
261 | (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, | ||
262 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and | ||
263 | <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). | ||
264 | </para></listitem> | ||
265 | <listitem><para><emphasis>Package Groups:</emphasis> | ||
266 | Arbitrary groups of software Recipes. | ||
267 | You use package groups to hold recipes that, when built, | ||
268 | usually accomplish a single task. | ||
269 | For example, a package group could contain the recipes for a | ||
270 | company’s proprietary or value-add software. | ||
271 | Or, the package group could contain the recipes that enable | ||
272 | graphics. | ||
273 | A package group is really just another recipe. | ||
274 | Because package group files are recipes, they end with the | ||
275 | <filename>.bb</filename> filename extension.</para></listitem> | ||
276 | <listitem><para id='poky'><emphasis>Poky:</emphasis> | ||
277 | The term "poky" can mean several things. | ||
278 | In its most general sense, it is an open-source | ||
279 | project that was initially developed by OpenedHand. | ||
280 | With OpenedHand, poky was developed off of the existing | ||
281 | OpenEmbedded build system becoming a commercially | ||
282 | supportable build system for embedded Linux. | ||
283 | After Intel Corporation acquired OpenedHand, the | ||
284 | project poky became the basis for the Yocto Project's | ||
285 | build system.</para> | ||
286 | <para>Within the Yocto Project source repositories, | ||
287 | <filename>poky</filename> exists as a separate Git | ||
288 | repository you can clone to yield a local copy on your | ||
289 | host system. | ||
290 | Thus, "poky" can refer to the local copy of the Source | ||
291 | Directory used for development within the Yocto | ||
292 | Project.</para> | ||
293 | <para>Finally, "poky" can refer to the default | ||
294 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> | ||
295 | (i.e. distribution) created when you use the Yocto | ||
296 | Project in conjunction with the | ||
297 | <filename>poky</filename> repository to build an image. | ||
298 | </para></listitem> | ||
299 | <listitem><para><emphasis>Recipe:</emphasis> | ||
300 | A set of instructions for building packages. | ||
301 | A recipe describes where you get source code, which patches | ||
302 | to apply, how to configure the source, how to compile it and so on. | ||
303 | Recipes also describe dependencies for libraries or for other | ||
304 | recipes. | ||
305 | Recipes represent the logical unit of execution, the software | ||
306 | to build, the images to build, and use the | ||
307 | <filename>.bb</filename> file extension. | ||
308 | </para></listitem> | ||
309 | <listitem> | ||
310 | <para id='source-directory'><emphasis>Source Directory:</emphasis> | ||
311 | This term refers to the directory structure created as a result | ||
312 | of creating a local copy of the <filename>poky</filename> Git | ||
313 | repository <filename>git://git.yoctoproject.org/poky</filename> | ||
314 | or expanding a released <filename>poky</filename> tarball. | ||
315 | <note> | ||
316 | Creating a local copy of the <filename>poky</filename> | ||
317 | Git repository is the recommended method for setting up | ||
318 | your Source Directory. | ||
319 | </note> | ||
320 | Sometimes you might hear the term "poky directory" used to refer | ||
321 | to this directory structure. | ||
322 | <note> | ||
323 | The OpenEmbedded build system does not support file or | ||
324 | directory names that contain spaces. | ||
325 | Be sure that the Source Directory you use does not contain | ||
326 | these types of names. | ||
327 | </note></para> | ||
328 | |||
329 | <para>The Source Directory contains BitBake, Documentation, | ||
330 | Metadata and other files that all support the Yocto Project. | ||
331 | Consequently, you must have the Source Directory in place on | ||
332 | your development system in order to do any development using | ||
333 | the Yocto Project.</para> | ||
334 | |||
335 | <para>When you create a local copy of the Git repository, you | ||
336 | can name the repository anything you like. | ||
337 | Throughout much of the documentation, "poky" | ||
338 | is used as the name of the top-level folder of the local copy of | ||
339 | the poky Git repository. | ||
340 | So, for example, cloning the <filename>poky</filename> Git | ||
341 | repository results in a local Git repository whose top-level | ||
342 | folder is also named "poky".</para> | ||
343 | |||
344 | <para>While it is not recommended that you use tarball expansion | ||
345 | to set up the Source Directory, if you do, the top-level | ||
346 | directory name of the Source Directory is derived from the | ||
347 | Yocto Project release tarball. | ||
348 | For example, downloading and unpacking | ||
349 | <filename>&YOCTO_POKY_TARBALL;</filename> results in a | ||
350 | Source Directory whose root folder is named | ||
351 | <filename>&YOCTO_POKY;</filename>.</para> | ||
352 | |||
353 | <para>It is important to understand the differences between the | ||
354 | Source Directory created by unpacking a released tarball as | ||
355 | compared to cloning | ||
356 | <filename>git://git.yoctoproject.org/poky</filename>. | ||
357 | When you unpack a tarball, you have an exact copy of the files | ||
358 | based on the time of release - a fixed release point. | ||
359 | Any changes you make to your local files in the Source Directory | ||
360 | are on top of the release and will remain local only. | ||
361 | On the other hand, when you clone the <filename>poky</filename> | ||
362 | Git repository, you have an active development repository with | ||
363 | access to the upstream repository's branches and tags. | ||
364 | In this case, any local changes you make to the local | ||
365 | Source Directory can be later applied to active development | ||
366 | branches of the upstream <filename>poky</filename> Git | ||
367 | repository.</para> | ||
368 | |||
369 | <para>For more information on concepts related to Git | ||
370 | repositories, branches, and tags, see the | ||
371 | "<ulink url='&YOCTO_DOCS_DEV_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>" | ||
372 | section in the Yocto Project Development Manual. | ||
373 | </para></listitem> | ||
374 | <listitem><para><emphasis>Task:</emphasis> | ||
375 | A unit of execution for BitBake (e.g. | ||
376 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>, | ||
377 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>, | ||
378 | <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>, | ||
379 | and so forth). | ||
380 | </para></listitem> | ||
381 | <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories | ||
382 | that are not local to the development system but located in a master area that is controlled | ||
383 | by the maintainer of the source code. | ||
384 | For example, in order for a developer to work on a particular piece of code, they need to | ||
385 | first get a copy of it from an "upstream" source.</para></listitem> | ||
386 | </itemizedlist> | ||
387 | </para> | ||
388 | </section> | ||
389 | |||
42 | <section id='intro-manualoverview'> | 390 | <section id='intro-manualoverview'> |
43 | <title>Documentation Overview</title> | 391 | <title>Documentation Overview</title> |
44 | <para> | 392 | <para> |