mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-30 12:29:55 +00:00
Code Issues Projects Releases Wiki Activity

documentation: poky-ref-manual - Variable descriptions edited.

Browse Source 
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>
This commit is contained in:
Paul Eggleton
2012-10-10 14:15:50 -07:00
committed by Richard Purdie
parent 985a13277d
commit 8419bb799e
1 changed files with 62 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/poky-ref-manual/ref-variables.xml
+62 -63
View File
@@ -1362,8 +1362,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef> <glossdef>
<para></para> <para></para>
<para> <para>
A list of required packages to install as part of the package being A list of required machine-specific packages to install as part of
built. the image being built.
The build process depends on these packages being present. The build process depends on these packages being present.
Furthermore, because this is a "machine essential" variable, the list of Furthermore, because this is a "machine essential" variable, the list of
packages are essential for the machine to boot. 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"
<para> <para>
This variable is similar to the This variable is similar to the
<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
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. 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. In other words, the image will not build if a file in this list is not found.
</para> </para>
<para> <para>
For example, suppose you are building a runtime package that depends For example, suppose the machine for which you are building requires
on a certain disk driver. a specific program to be run during boot to initialise the hardware.
In this case, you would use the following: In this case, assuming the package name for the program was
<filename>example-init</filename>, you would use the following in the
<filename>.conf</filename> file for the machine:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;disk_driver&gt;" MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
</literallayout> </literallayout>
</para> </para>
</glossdef> </glossdef>
@@ -1392,8 +1394,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef> <glossdef>
<para></para> <para></para>
<para> <para>
A list of recommended packages to install as part of the package being A list of recommended machine-specific packages to install as part of
built. the image being built.
The build process does not depend on these packages being present. The build process does not depend on these packages being present.
Furthermore, because this is a "machine essential" variable, the list of Furthermore, because this is a "machine essential" variable, the list of
packages are essential for the machine to boot. 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"
<para> <para>
This variable is similar to the This variable is similar to the
<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
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. dependency on the variable's list of packages.
In other words, the image will build if a file in this list is not found. In other words, the image will still build if a package in this list is not found.
However, because this is one of the "essential" variables, the resulting image Typically, this variable is used to handle essential kernel modules, whose
might not boot on the machine. functionality may be selected to be built into the kernel rather than as a module,
Or, if the machine does boot using the image, the machine might not be fully in which case a package will not be produced.
functional.
</para> </para>
<para> <para>
Consider an example where you have a custom kernel with a disk driver Consider an example where you have a custom kernel where a specific touchscreen
built into the kernel itself, rather than using the driver built as a module. driver is required for the machine to be usable, but may be built as a module or
If you include the package that has the driver module as part of into the kernel depending on the kernel configuration.
the variable's list, the If the driver is built as a module, you want it to be installed.
build process will not find that package. However if
However, because these packages are "recommends" packages, the build will the driver is built into the kernel you still want the build to succeed.
not fail due to the missing package. This variable sets up a "recommends" relationship so that in the latter case,
Not accounting for any other problems, the custom kernel would still boot the machine. the build will not fail due to the missing package.
</para> To accomplish this, assuming the package for the module was called
<para> <filename>kernel-module-ab123</filename>, you would use the
Some example packages of these machine essentials are flash, screen, keyboard, mouse, following in the <filename>.conf</filename> file for the machine:
or touchscreen drivers (depending on the machine).
</para>
<para>
For example, suppose you are building a runtime package that depends
on a mouse driver.
In this case, you would use the following:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "&lt;mouse_driver&gt;" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
</literallayout> </literallayout>
</para> </para>
<para>
Some examples of these machine essentials are flash, screen, keyboard, mouse,
or touchscreen drivers (depending on the machine).
</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
<glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
<glossdef> <glossdef>
<para> <para>
A list of optional but non-machine essential packages to install as A list of machine-specific packages that are not essential for booting to install as
part of the package being built. part of the image being built.
Even though these packages are not essential for the machine to boot, The build process for more fully-featured images depends on them being present.
the build process depends on them being present.
The impact of this variable affects all images based on The impact of this variable affects all images based on
<filename>packagegroup-base</filename>, which does not include the <filename>packagegroup-base</filename>, which does not include the
<filename>core-image-minimal</filename> or <filename>core-image-basic</filename> <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"
<para> <para>
This variable is similar to the This variable is similar to the
<filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
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. 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. In other words, the image will not build if a file in this list is not found.
</para> </para>
<para> <para>
An example is a machine that might or might not have a WiFi card. An example is a machine that has WiFi capability.
The package containing the WiFi support is not essential for the WiFi being enabled is not essential for the machine to boot the image.
machine to boot the image. However, if you are building a more fully-featured image, you want to enable
If it is not there, the machine will boot but not be able to use the the WiFi.
WiFi functionality. The package containing the firmware for the WiFi hardware is always
However, if you include the package with the WiFi support as part of the expected to exist, so it is acceptable for the build process to depend upon
variable's package list, the build finding the package.
process depends on finding the package. In this case, assuming the package for the firmware was called
In this case, you would use the following: <filename>wifidriver-firmware</filename>, you would use the following in the
<filename>.conf</filename> file for the machine:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;" MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
</literallayout> </literallayout>
</para> </para>
</glossdef> </glossdef>
@@ -1476,9 +1475,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef> <glossdef>
<para></para> <para></para>
<para> <para>
A list of optional but non-machine essential packages to install as A list of machine-specific packages that are not essential for booting
part of the package being built. to install as part of the image being built, if present.
The package being built has no build dependency on the list of packages The image being built has no build dependency on the list of packages
with this variable. with this variable.
The impact of this variable affects only images based on The impact of this variable affects only images based on
<filename>packagegroup-base</filename>, which does not include the <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"
<para> <para>
This variable is similar to the This variable is similar to the
<filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
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. dependency on the variable's list of packages.
In other words, the image will build if a file in this list is not found. In other words, the image will build if a file in this list is not found.
</para> </para>
<para> <para>
An example is a machine that might or might not have a WiFi card. An example is a machine that has WiFi capability.
The package containing the WiFi support is not essential for the WiFi being enabled is not essential for the machine to boot the image.
machine to boot the image. However if you are building a more fully-featured image, you want to enable
If it is not there, the machine will boot but not be able to use the WiFi.
WiFi functionality. However, the package containing the WiFi kernel module will not be produced
You are free to either include or not include the if the WiFi driver is built into the kernel, in which case you still want the
the package with the WiFi support as part of the build to succeed instead of failing because the package could not be found.
variable's package list, the build To accomplish this, assuming the package for the module was called
process does not depend on finding the package. <filename>kernel-module-examplewifi</filename>, you would use the
If you include the package, you would use the following: following in the <filename>.conf</filename> file for the machine:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_EXTRA_RRECOMMENDS += "&lt;wifi_driver&gt;" MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
</literallayout> </literallayout>
</para> </para>
</glossdef> </glossdef>