From 8419bb799e8d47d13d1893e85c3ffb0b97ee1382 Mon Sep 17 00:00:00 2001 From: Paul Eggleton Date: Wed, 10 Oct 2012 14:15:50 -0700 Subject: 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 Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/ref-variables.xml | 127 ++++++++++++------------ 1 file changed, 63 insertions(+), 64 deletions(-) (limited to 'documentation/poky-ref-manual') 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" - A list of required packages to install as part of the package being - built. + A list of required machine-specific packages to install as part of + the image being built. The build process depends on these packages being present. Furthermore, because this is a "machine essential" variable, the list of 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" This variable is similar to the MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS - variable with the exception that the package being built has a build + variable with the exception that the image being built has a build dependency on the variable's list of packages. In other words, the image will not build if a file in this list is not found. - For example, suppose you are building a runtime package that depends - on a certain disk driver. - In this case, you would use the following: + For example, suppose the machine for which you are building requires + a specific program to be run during boot to initialise the hardware. + In this case, assuming the package name for the program was + example-init, you would use the following in the + .conf file for the machine: - MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "<disk_driver>" + MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" @@ -1392,8 +1394,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" - A list of recommended packages to install as part of the package being - built. + A list of recommended machine-specific packages to install as part of + the image being built. The build process does not depend on these packages being present. Furthermore, because this is a "machine essential" variable, the list of 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" This variable is similar to the MACHINE_ESSENTIAL_EXTRA_RDEPENDS - variable with the exception that the package being built does not have a build + variable with the exception that the image being built does not have a build dependency on the variable's list of packages. - In other words, the image will build if a file in this list is not found. - However, because this is one of the "essential" variables, the resulting image - might not boot on the machine. - Or, if the machine does boot using the image, the machine might not be fully - functional. - - - Consider an example where you have a custom kernel with a disk driver - built into the kernel itself, rather than using the driver built as a module. - If you include the package that has the driver module as part of - the variable's list, the - build process will not find that package. - However, because these packages are "recommends" packages, the build will - not fail due to the missing package. - Not accounting for any other problems, the custom kernel would still boot the machine. + In other words, the image will still build if a package in this list is not found. + Typically, this variable is used to handle essential kernel modules, whose + functionality may be selected to be built into the kernel rather than as a module, + in which case a package will not be produced. + + + Consider an example where you have a custom kernel where a specific touchscreen + driver is required for the machine to be usable, but may be built as a module or + into the kernel depending on the kernel configuration. + If the driver is built as a module, you want it to be installed. + However if + the driver is built into the kernel you still want the build to succeed. + This variable sets up a "recommends" relationship so that in the latter case, + the build will not fail due to the missing package. + To accomplish this, assuming the package for the module was called + kernel-module-ab123, you would use the + following in the .conf file for the machine: + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" + - Some example packages of these machine essentials are flash, screen, keyboard, mouse, + Some examples of these machine essentials are flash, screen, keyboard, mouse, or touchscreen drivers (depending on the machine). - - For example, suppose you are building a runtime package that depends - on a mouse driver. - In this case, you would use the following: - - MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "<mouse_driver>" - - MACHINE_EXTRA_RDEPENDS - A list of optional but non-machine essential packages to install as - part of the package being built. - Even though these packages are not essential for the machine to boot, - the build process depends on them being present. + A list of machine-specific packages that are not essential for booting to install as + part of the image being built. + The build process for more fully-featured images depends on them being present. The impact of this variable affects all images based on packagegroup-base, which does not include the core-image-minimal or core-image-basic @@ -1451,22 +1449,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This variable is similar to the MACHINE_EXTRA_RRECOMMENDS - variable with the exception that the package being built has a build + variable with the exception that the image being built has a build dependency on the variable's list of packages. In other words, the image will not build if a file in this list is not found. - An example is a machine that might or might not have a WiFi card. - The package containing the WiFi support is not essential for the - machine to boot the image. - If it is not there, the machine will boot but not be able to use the - WiFi functionality. - However, if you include the package with the WiFi support as part of the - variable's package list, the build - process depends on finding the package. - In this case, you would use the following: + An example is a machine that has WiFi capability. + WiFi being enabled is not essential for the machine to boot the image. + However, if you are building a more fully-featured image, you want to enable + the WiFi. + The package containing the firmware for the WiFi hardware is always + expected to exist, so it is acceptable for the build process to depend upon + finding the package. + In this case, assuming the package for the firmware was called + wifidriver-firmware, you would use the following in the + .conf file for the machine: - MACHINE_EXTRA_RDEPENDS += "<wifi_driver>" + MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" @@ -1476,9 +1475,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" - A list of optional but non-machine essential packages to install as - part of the package being built. - The package being built has no build dependency on the list of packages + A list of machine-specific packages that are not essential for booting + to install as part of the image being built, if present. + The image being built has no build dependency on the list of packages with this variable. The impact of this variable affects only images based on packagegroup-base, which does not include the @@ -1488,23 +1487,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This variable is similar to the MACHINE_EXTRA_RDEPENDS - variable with the exception that the package being built does not have a build + variable with the exception that the image being built does not have a build dependency on the variable's list of packages. In other words, the image will build if a file in this list is not found. - An example is a machine that might or might not have a WiFi card. - The package containing the WiFi support is not essential for the - machine to boot the image. - If it is not there, the machine will boot but not be able to use the - WiFi functionality. - You are free to either include or not include the - the package with the WiFi support as part of the - variable's package list, the build - process does not depend on finding the package. - If you include the package, you would use the following: + An example is a machine that has WiFi capability. + WiFi being enabled is not essential for the machine to boot the image. + However if you are building a more fully-featured image, you want to enable + WiFi. + However, the package containing the WiFi kernel module will not be produced + if the WiFi driver is built into the kernel, in which case you still want the + build to succeed instead of failing because the package could not be found. + To accomplish this, assuming the package for the module was called + kernel-module-examplewifi, you would use the + following in the .conf file for the machine: - MACHINE_EXTRA_RRECOMMENDS += "<wifi_driver>" + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" -- cgit v1.2.3-54-g00ecf