summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/bitbake-user-manual')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml93
1 files changed, 55 insertions, 38 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
index 8514f23f25..641c6e0af0 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml
@@ -331,38 +331,55 @@
331 </section> 331 </section>
332 332
333 <section id='bb-bitbake-providers'> 333 <section id='bb-bitbake-providers'>
334 <title>Preferences and Providers</title> 334 <title>Providers</title>
335 335
336 <para> 336 <para>
337 Assuming BitBake has been instructed to execute a target 337 Assuming BitBake has been instructed to execute a target
338 and that all the recipe files have been parsed, BitBake 338 and that all the recipe files have been parsed, BitBake
339 starts to figure out how to build the target. 339 starts to figure out how to build the target.
340 BitBake starts by looking through the 340 BitBake looks through the <filename>PROVIDES</filename> list
341 for each of the recipes.
342 A <filename>PROVIDES</filename> list is the list of names by which
343 the recipe can be known.
344 Each recipe's <filename>PROVIDES</filename> list is created
345 implicitly through the recipe's
346 <link linkend='var-PN'><filename>PN</filename></link> variable
347 and explicitly through the recipe's
341 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> 348 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
342 set in recipe files. 349 variable, which is optional.
343 The default <filename>PROVIDES</filename> for a recipe is its name
344 (<link linkend='var-PN'><filename>PN</filename></link>),
345 however, a recipe can provide multiple things.
346 </para> 350 </para>
347 351
348 <para> 352 <para>
349 As an example of adding an extra provider, suppose a recipe named 353 When a recipe uses <filename>PROVIDES</filename>, that recipe's
350 <filename>foo_1.0.bb</filename> contained the following: 354 functionality can be found under an alternative name or names other
355 than the implicit <filename>PN</filename> name.
356 As an example, suppose a recipe named <filename>keyboard_1.0.bb</filename>
357 contained the following:
351 <literallayout class='monospaced'> 358 <literallayout class='monospaced'>
352 PROVIDES += "virtual/bar_1.0" 359 PROVIDES += "fullkeyboard"
353 </literallayout> 360 </literallayout>
354 The recipe now provides both "foo_1.0" and "virtual/bar_1.0". 361 The <filename>PROVIDES</filename> list for this recipe becomes
355 The "virtual/" namespace is often used to denote cases where 362 "keyboard", which is implicit, and "fullkeyboard", which is explicit.
356 multiple providers are expected with the user choosing between 363 Consequently, the functionality found in
357 them. 364 <filename>keyboard_1.0.bb</filename> can be found under two
358 Kernels and toolchain components are common cases of this in 365 different names.
359 OpenEmbedded. 366 </para>
367 </section>
368
369 <section id='bb-bitbake-preferences'>
370 <title>Preferences</title>
371
372 <para>
373 The <filename>PROVIDES</filename> list is only part of the solution
374 for figuring out a target's recipes.
375 Because targets might have multiple providers, BitBake needs
376 to prioritize providers by determining provider preferences.
360 </para> 377 </para>
361 378
362 <para> 379 <para>
363 Sometimes a target might have multiple providers. 380 A common example in which a target has multiple providers
364 A common example is "virtual/kernel", which is provided by each 381 is "virtual/kernel", which is on the
365 kernel recipe. 382 <filename>PROVIDES</filename> list for each kernel recipe.
366 Each machine often selects the best kernel provider by using a 383 Each machine often selects the best kernel provider by using a
367 line similar to the following in the machine configuration file: 384 line similar to the following in the machine configuration file:
368 <literallayout class='monospaced'> 385 <literallayout class='monospaced'>
@@ -377,7 +394,7 @@
377 394
378 <para> 395 <para>
379 Understanding how providers are chosen is made complicated by the fact 396 Understanding how providers are chosen is made complicated by the fact
380 that multiple versions might exist. 397 that multiple versions might exist for a given provider.
381 BitBake defaults to the highest version of a provider. 398 BitBake defaults to the highest version of a provider.
382 Version comparisons are made using the same method as Debian. 399 Version comparisons are made using the same method as Debian.
383 You can use the 400 You can use the
@@ -386,13 +403,19 @@
386 You can influence the order by using the 403 You can influence the order by using the
387 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link> 404 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
388 variable. 405 variable.
406 </para>
407
408 <para>
389 By default, files have a preference of "0". 409 By default, files have a preference of "0".
390 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the 410 Setting <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
391 recipe unlikely to be used unless it is explicitly referenced. 411 recipe unlikely to be used unless it is explicitly referenced.
392 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the recipe is used. 412 Setting <filename>DEFAULT_PREFERENCE</filename> to "1" makes it
393 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting. 413 likely the recipe is used.
394 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental recipe 414 <filename>PREFERRED_VERSION</filename> overrides any
395 versions until they have undergone sufficient testing to be considered stable. 415 <filename>DEFAULT_PREFERENCE</filename> setting.
416 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer
417 and more experimental recipe versions until they have undergone
418 sufficient testing to be considered stable.
396 </para> 419 </para>
397 420
398 <para> 421 <para>
@@ -401,18 +424,16 @@
401 version, unless otherwise specified. 424 version, unless otherwise specified.
402 If the recipe in question has a 425 If the recipe in question has a
403 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link> 426 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
404 set lower than 427 set lower than the other recipes (default is 0), then
405 the other recipes (default is 0), then it will not be 428 it will not be selected.
406 selected.
407 This allows the person or persons maintaining 429 This allows the person or persons maintaining
408 the repository of recipe files to specify 430 the repository of recipe files to specify
409 their preference for the default selected version. 431 their preference for the default selected version.
410 In addition, the user can specify their preferred version. 432 Additionally, the user can specify their preferred version.
411 </para> 433 </para>
412 434
413 <para> 435 <para>
414 If the first recipe is named <filename>a_1.1.bb</filename>, 436 If the first recipe is named <filename>a_1.1.bb</filename>, then the
415 then the
416 <link linkend='var-PN'><filename>PN</filename></link> variable 437 <link linkend='var-PN'><filename>PN</filename></link> variable
417 will be set to “a”, and the 438 will be set to “a”, and the
418 <link linkend='var-PV'><filename>PV</filename></link> 439 <link linkend='var-PV'><filename>PV</filename></link>
@@ -420,19 +441,15 @@
420 </para> 441 </para>
421 442
422 <para> 443 <para>
423 If we then have a recipe named <filename>a_1.2.bb</filename>, BitBake 444 Thus, if a recipe named <filename>a_1.2.bb</filename> exists, BitBake
424 will choose 1.2 by default. 445 will choose 1.2 by default.
425 However, if we define the following variable in a 446 However, if you define the following variable in a
426 <filename>.conf</filename> file that BitBake parses, we 447 <filename>.conf</filename> file that BitBake parses, you
427 can change that. 448 can change that preference:
428 <literallayout class='monospaced'> 449 <literallayout class='monospaced'>
429 PREFERRED_VERSION_a = "1.1" 450 PREFERRED_VERSION_a = "1.1"
430 </literallayout> 451 </literallayout>
431 </para> 452 </para>
432
433 <para>
434 In summary, BitBake has created a list of providers, which is prioritized, for each target.
435 </para>
436 </section> 453 </section>
437 454
438 <section id='bb-bitbake-dependencies'> 455 <section id='bb-bitbake-dependencies'>