summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorPaul Eggleton <paul.eggleton@linux.intel.com>2012-10-10 14:15:50 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-10-15 14:45:47 +0100
commit8419bb799e8d47d13d1893e85c3ffb0b97ee1382 (patch)
treee89be1bb5b40ae7c55cc277c6642b79f5701809c /documentation
parent985a13277d004799ae368adc9bee365435e96eff (diff)
downloadpoky-8419bb799e8d47d13d1893e85c3ffb0b97ee1382.tar.gz
documentation: poky-ref-manual - Variable descriptions edited.
Adjust the descriptions so that it is clearer that these are specific to a machine and should appear in the machine's .conf file, and are intended to affect the image contents, not the dependencies of a specific package. Also change the examples so that they demonstrate more realistic usage scenarios for these variables. (From yocto-docs rev: 3c3b8b117b09d78637ae8c4d27f77194cf197ea9) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml127
1 files changed, 63 insertions, 64 deletions
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index abeec67415..bc3d286f52 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1362,8 +1362,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1362 <glossdef> 1362 <glossdef>
1363 <para></para> 1363 <para></para>
1364 <para> 1364 <para>
1365 A list of required packages to install as part of the package being 1365 A list of required machine-specific packages to install as part of
1366 built. 1366 the image being built.
1367 The build process depends on these packages being present. 1367 The build process depends on these packages being present.
1368 Furthermore, because this is a "machine essential" variable, the list of 1368 Furthermore, because this is a "machine essential" variable, the list of
1369 packages are essential for the machine to boot. 1369 packages are essential for the machine to boot.
@@ -1373,16 +1373,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1373 <para> 1373 <para>
1374 This variable is similar to the 1374 This variable is similar to the
1375 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> 1375 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
1376 variable with the exception that the package being built has a build 1376 variable with the exception that the image being built has a build
1377 dependency on the variable's list of packages. 1377 dependency on the variable's list of packages.
1378 In other words, the image will not build if a file in this list is not found. 1378 In other words, the image will not build if a file in this list is not found.
1379 </para> 1379 </para>
1380 <para> 1380 <para>
1381 For example, suppose you are building a runtime package that depends 1381 For example, suppose the machine for which you are building requires
1382 on a certain disk driver. 1382 a specific program to be run during boot to initialise the hardware.
1383 In this case, you would use the following: 1383 In this case, assuming the package name for the program was
1384 <filename>example-init</filename>, you would use the following in the
1385 <filename>.conf</filename> file for the machine:
1384 <literallayout class='monospaced'> 1386 <literallayout class='monospaced'>
1385 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;disk_driver&gt;" 1387 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
1386 </literallayout> 1388 </literallayout>
1387 </para> 1389 </para>
1388 </glossdef> 1390 </glossdef>
@@ -1392,8 +1394,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1392 <glossdef> 1394 <glossdef>
1393 <para></para> 1395 <para></para>
1394 <para> 1396 <para>
1395 A list of recommended packages to install as part of the package being 1397 A list of recommended machine-specific packages to install as part of
1396 built. 1398 the image being built.
1397 The build process does not depend on these packages being present. 1399 The build process does not depend on these packages being present.
1398 Furthermore, because this is a "machine essential" variable, the list of 1400 Furthermore, because this is a "machine essential" variable, the list of
1399 packages are essential for the machine to boot. 1401 packages are essential for the machine to boot.
@@ -1403,46 +1405,42 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1403 <para> 1405 <para>
1404 This variable is similar to the 1406 This variable is similar to the
1405 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> 1407 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
1406 variable with the exception that the package being built does not have a build 1408 variable with the exception that the image being built does not have a build
1407 dependency on the variable's list of packages. 1409 dependency on the variable's list of packages.
1408 In other words, the image will build if a file in this list is not found. 1410 In other words, the image will still build if a package in this list is not found.
1409 However, because this is one of the "essential" variables, the resulting image 1411 Typically, this variable is used to handle essential kernel modules, whose
1410 might not boot on the machine. 1412 functionality may be selected to be built into the kernel rather than as a module,
1411 Or, if the machine does boot using the image, the machine might not be fully 1413 in which case a package will not be produced.
1412 functional. 1414 </para>
1413 </para> 1415 <para>
1414 <para> 1416 Consider an example where you have a custom kernel where a specific touchscreen
1415 Consider an example where you have a custom kernel with a disk driver 1417 driver is required for the machine to be usable, but may be built as a module or
1416 built into the kernel itself, rather than using the driver built as a module. 1418 into the kernel depending on the kernel configuration.
1417 If you include the package that has the driver module as part of 1419 If the driver is built as a module, you want it to be installed.
1418 the variable's list, the 1420 However if
1419 build process will not find that package. 1421 the driver is built into the kernel you still want the build to succeed.
1420 However, because these packages are "recommends" packages, the build will 1422 This variable sets up a "recommends" relationship so that in the latter case,
1421 not fail due to the missing package. 1423 the build will not fail due to the missing package.
1422 Not accounting for any other problems, the custom kernel would still boot the machine. 1424 To accomplish this, assuming the package for the module was called
1425 <filename>kernel-module-ab123</filename>, you would use the
1426 following in the <filename>.conf</filename> file for the machine:
1427 <literallayout class='monospaced'>
1428 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
1429 </literallayout>
1423 </para> 1430 </para>
1424 <para> 1431 <para>
1425 Some example packages of these machine essentials are flash, screen, keyboard, mouse, 1432 Some examples of these machine essentials are flash, screen, keyboard, mouse,
1426 or touchscreen drivers (depending on the machine). 1433 or touchscreen drivers (depending on the machine).
1427 </para> 1434 </para>
1428 <para>
1429 For example, suppose you are building a runtime package that depends
1430 on a mouse driver.
1431 In this case, you would use the following:
1432 <literallayout class='monospaced'>
1433 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "&lt;mouse_driver&gt;"
1434 </literallayout>
1435 </para>
1436 </glossdef> 1435 </glossdef>
1437 </glossentry> 1436 </glossentry>
1438 1437
1439 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> 1438 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
1440 <glossdef> 1439 <glossdef>
1441 <para> 1440 <para>
1442 A list of optional but non-machine essential packages to install as 1441 A list of machine-specific packages that are not essential for booting to install as
1443 part of the package being built. 1442 part of the image being built.
1444 Even though these packages are not essential for the machine to boot, 1443 The build process for more fully-featured images depends on them being present.
1445 the build process depends on them being present.
1446 The impact of this variable affects all images based on 1444 The impact of this variable affects all images based on
1447 <filename>packagegroup-base</filename>, which does not include the 1445 <filename>packagegroup-base</filename>, which does not include the
1448 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename> 1446 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
@@ -1451,22 +1449,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1451 <para> 1449 <para>
1452 This variable is similar to the 1450 This variable is similar to the
1453 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> 1451 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
1454 variable with the exception that the package being built has a build 1452 variable with the exception that the image being built has a build
1455 dependency on the variable's list of packages. 1453 dependency on the variable's list of packages.
1456 In other words, the image will not build if a file in this list is not found. 1454 In other words, the image will not build if a file in this list is not found.
1457 </para> 1455 </para>
1458 <para> 1456 <para>
1459 An example is a machine that might or might not have a WiFi card. 1457 An example is a machine that has WiFi capability.
1460 The package containing the WiFi support is not essential for the 1458 WiFi being enabled is not essential for the machine to boot the image.
1461 machine to boot the image. 1459 However, if you are building a more fully-featured image, you want to enable
1462 If it is not there, the machine will boot but not be able to use the 1460 the WiFi.
1463 WiFi functionality. 1461 The package containing the firmware for the WiFi hardware is always
1464 However, if you include the package with the WiFi support as part of the 1462 expected to exist, so it is acceptable for the build process to depend upon
1465 variable's package list, the build 1463 finding the package.
1466 process depends on finding the package. 1464 In this case, assuming the package for the firmware was called
1467 In this case, you would use the following: 1465 <filename>wifidriver-firmware</filename>, you would use the following in the
1466 <filename>.conf</filename> file for the machine:
1468 <literallayout class='monospaced'> 1467 <literallayout class='monospaced'>
1469 MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;" 1468 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
1470 </literallayout> 1469 </literallayout>
1471 </para> 1470 </para>
1472 </glossdef> 1471 </glossdef>
@@ -1476,9 +1475,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1476 <glossdef> 1475 <glossdef>
1477 <para></para> 1476 <para></para>
1478 <para> 1477 <para>
1479 A list of optional but non-machine essential packages to install as 1478 A list of machine-specific packages that are not essential for booting
1480 part of the package being built. 1479 to install as part of the image being built, if present.
1481 The package being built has no build dependency on the list of packages 1480 The image being built has no build dependency on the list of packages
1482 with this variable. 1481 with this variable.
1483 The impact of this variable affects only images based on 1482 The impact of this variable affects only images based on
1484 <filename>packagegroup-base</filename>, which does not include the 1483 <filename>packagegroup-base</filename>, which does not include the
@@ -1488,23 +1487,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1488 <para> 1487 <para>
1489 This variable is similar to the 1488 This variable is similar to the
1490 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> 1489 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
1491 variable with the exception that the package being built does not have a build 1490 variable with the exception that the image being built does not have a build
1492 dependency on the variable's list of packages. 1491 dependency on the variable's list of packages.
1493 In other words, the image will build if a file in this list is not found. 1492 In other words, the image will build if a file in this list is not found.
1494 </para> 1493 </para>
1495 <para> 1494 <para>
1496 An example is a machine that might or might not have a WiFi card. 1495 An example is a machine that has WiFi capability.
1497 The package containing the WiFi support is not essential for the 1496 WiFi being enabled is not essential for the machine to boot the image.
1498 machine to boot the image. 1497 However if you are building a more fully-featured image, you want to enable
1499 If it is not there, the machine will boot but not be able to use the 1498 WiFi.
1500 WiFi functionality. 1499 However, the package containing the WiFi kernel module will not be produced
1501 You are free to either include or not include the 1500 if the WiFi driver is built into the kernel, in which case you still want the
1502 the package with the WiFi support as part of the 1501 build to succeed instead of failing because the package could not be found.
1503 variable's package list, the build 1502 To accomplish this, assuming the package for the module was called
1504 process does not depend on finding the package. 1503 <filename>kernel-module-examplewifi</filename>, you would use the
1505 If you include the package, you would use the following: 1504 following in the <filename>.conf</filename> file for the machine:
1506 <literallayout class='monospaced'> 1505 <literallayout class='monospaced'>
1507 MACHINE_EXTRA_RRECOMMENDS += "&lt;wifi_driver&gt;" 1506 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
1508 </literallayout> 1507 </literallayout>
1509 </para> 1508 </para>
1510 </glossdef> 1509 </glossdef>