sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

documentation/poky-ref-manual/ref-variables.xml: Variables updated 

This is the second pass for re-documenting RDEPENDS, RRECOMMENDS,
MACHINE_ESSENTIALS_EXTRA_RDEPENDS, MACHINE_ESSENTIALS_EXTRA_RRECOMMENDS,
MACHINE_EXTRA_RDEPENDS, and MACHINE_EXTRA_RRECOMMENDS.  These
variables are in dire need of better explanations and examples.

(From yocto-docs rev: cc60bd4c50c7b19209dae06307aec26e962cf476)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2011-09-28 09:11:01 -07:00 committed by Richard Purdie
parent de1dcde413
commit 66ddb69916
1 changed files with 92 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
documentation/poky-ref-manual/ref-variables.xml
View File

@ -666,23 +666,27 @@
<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm> <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
<glossdef> <glossdef>
<para> <para>
A list of packages that must be installed as part of the package being A list of required packages to install as part of the package being
built in order for the built.
resulting image to boot on the system. The build process depends on these packages being present.
The machine depends on these items - without them it will not boot. Furthermore, because this is a "machine essential" variable, the list of
If a package in this list cannot be found during the build, the build packages are essential for the machine to boot.
will not complete. The impact of this variable affects images based on <filename>task-core-boot</filename>,
Some examples of these machine essentials are flash, screen, keyboard, mouse, including the <filename>core-image-minimal</filename> image.
or touchscreen drivers (depending on the machine). </para>
<para>
This variable is similar to the
<link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link>
variable with the exception that the package 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.
</para> </para>
<para> <para>
For example, suppose you are building a runtime package that depends For example, suppose you are building a runtime package that depends
on a mouse driver. on a certain disk driver.
In this case, you would use the following In this case, you would use the following:
<filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename>
statement:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;mouse_driver&gt;" MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;disk_driver&gt;"
</literallayout> </literallayout>
</para> </para>
</glossdef> </glossdef>
@ -691,38 +695,45 @@
<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm> <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
<glossdef> <glossdef>
<para> <para>
A list of packages that must be installed as part of the package being A list of recommended packages to install as part of the package being
built in order for the built.
resulting image to boot on the system. The build process does not depend on these packages being present.
The machine depends on these items - without them it will not boot. Furthermore, because this is a "machine essential" variable, the list of
If a package in this list cannot be found during the build, the build packages are essential for the machine to boot.
will not complete. The impact of this variable affects images based on <filename>task-core-boot</filename>,
including the <filename>core-image-minimal</filename> image.
</para> </para>
<para> <para>
This variable is similar to the This variable is similar to the
<link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link> <link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link>
with the exception that the package being built does not have a build variable with the exception that the package being built does not have a build
dependency on the variable's list of packages. dependency on the variable's list of packages.
</para> In other words, the image will build if a file in this list is not found.
<para> However, because this is one of the "essential" variables, the resulting image
Someone help me out here... How can this list be "recommended" yet part might not boot on the machine.
of the machine essential list? Or, if the machine does boot using the image, the machine might not be fully
Seems to me that anything that is machine essential pretty much needs to functional.
be there.
The rest of this section needs an appropriate example.
</para> </para>
<para> <para>
Some examples of these machine essentials are flash, screen, keyboard, mouse, 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.
</para>
<para>
Some example packages of these machine essentials are flash, screen, keyboard, mouse,
or touchscreen drivers (depending on the machine). or touchscreen drivers (depending on the machine).
</para> </para>
<para> <para>
For example, suppose you are building a runtime package that depends For example, suppose you are building a runtime package that depends
on a mouse driver. on a mouse driver.
In this case, you would use the following In this case, you would use the following:
<filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename>
statement:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;mouse_driver&gt;" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "&lt;mouse_driver&gt;"
</literallayout> </literallayout>
</para> </para>
</glossdef> </glossdef>
@ -731,30 +742,32 @@
<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 packages that should be installed as part of the package A list of optional but non-machine essential packages to install as
being built in order for the part of the package being built.
resulting image to boot on the system and achieve full functionality. Even though these packages are not essential for the machine to boot,
Although the machine does not need these items in order to boot, if you want the the build process depends on them being present.
extra functionality they provide the package being built depends on them The impact of this variable affects all images based on
being there. <filename>task-base</filename>, which does not include the
If a package in this list cannot be found during the build, the build <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
will not complete. images.
</para> </para>
<para> <para>
I need a real-world example here.... This variable is similar to the
<link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link>
variable with the exception that the package 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.
</para> </para>
<para> <para>
An example of a machine extra is a WiFi driver. An example is a machine that might or might not have a WiFi card.
The machine may or may not have a WiFi card. The package containing the WiFi support is not essential for the
If it does, the package with the driver needs to be present for the card to work. machine to boot the image.
However, if the machine does not have a WiFi card, the machine will still boot. If it is not there, the machine will boot but not be able to use the
</para> WiFi functionality.
<para> However, if you include the package with the WiFi support as part of the
For example, suppose you are building a runtime package that depends variable's package list, the build
on a WiFi driver. process depends on finding the package.
In this case, you would use the following In this case, you would use the following:
<filename>MACHINE_EXTRA_RDEPENDS</filename>
statement:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;" MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;"
</literallayout> </literallayout>
@ -765,38 +778,35 @@
<glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm> <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
<glossdef> <glossdef>
<para> <para>
A list of packages that should be installed as part of the package A list of optional but non-machine essential packages to install as
being built in order for the part of the package being built.
machine to boot and achieve full functionality. The package being built has no build dependency on the list of packages
Although the machine does not need these items in order to boot, if you want the with this variable.
extra functionality they provide the package being built should include The impact of this variable affects only images based on
them. <filename>task-base</filename>, which does not include the
<filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
images.
</para> </para>
<para> <para>
This variable is similar to the This variable is similar to the
<link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link> <link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link>
with the exception that the package being built does not have a build variable with the exception that the package being built does not have a build
dependency on the variable's list of packages. dependency on the variable's list of packages.
If a package in this list cannot be found during the build, the build In other words, the image will build if a file in this list is not found.
will still continue.
</para> </para>
<para> <para>
I need a real-world example to use here please.... An example is a machine that might or might not have a WiFi card.
</para> The package containing the WiFi support is not essential for the
<para> machine to boot the image.
An example of a machine extra is a WiFi driver. If it is not there, the machine will boot but not be able to use the
The machine may or may not have a WiFi card. WiFi functionality.
If it does, the package with the driver needs to be present for the card to work. You are free to either include or not include the
However, if the machine does not have a WiFi card, the machine will still boot. the package with the WiFi support as part of the
</para> variable's package list, the build
<para> process does not depend on finding the package.
For example, suppose you are building a runtime package that depends If you include the package, you would use the following:
on a WiFi driver.
In this case, you would use the following
<filename>MACHINE_EXTRA_RDEPENDS</filename>
statement:
<literallayout class='monospaced'> <literallayout class='monospaced'>
MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;" MACHINE_EXTRA_RRECOMMENDS += "&lt;wifi_driver&gt;"
</literallayout> </literallayout>
</para> </para>
</glossdef> </glossdef>
@ -1015,9 +1025,9 @@
<glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
<glossdef> <glossdef>
<para> <para>
A list of packages that must be installed alongside a package being A list of packages that must be installed as part of a package being built.
built because the package being build has runtime dependencies on The package being built has a runtime dependency on the packages in the
them. variable's list.
In other words, in order for the package being built to run correctly, In other words, in order for the package being built to run correctly,
it depends on these listed packages. it depends on these listed packages.
If a package in this list cannot be found during the build, the build If a package in this list cannot be found during the build, the build
@ -1072,13 +1082,13 @@
A list of packages that extend the usability of a package being A list of packages that extend the usability of a package being
built. built.
The package being built does not depend on this list of packages in The package being built does not depend on this list of packages in
order to successfully built, but needs them for the extended usability. order to successfully build, but needs them for the extended usability.
To specify runtime dependencies for packages, see the To specify runtime dependencies for packages, see the
<link linkend='var-RDEPENDS'>RDEPENDS</link> variable. <link linkend='var-RDEPENDS'>RDEPENDS</link> variable.
</para> </para>
<para> <para>
The Yocto Project build process automatically installs the list of packages The Yocto Project build process automatically installs the list of packages
as part of the build package. as part of the built package.
However, you can remove them later if you want. However, you can remove them later if you want.
If, during the build, a package from the list cannot be found, the build If, during the build, a package from the list cannot be found, the build
process continues without an error. process continues without an error.
@ -1090,8 +1100,7 @@
whose usability is being extended. whose usability is being extended.
For example, suppose you are building a development package that is extended For example, suppose you are building a development package that is extended
to support wireless functionality. to support wireless functionality.
In this case, you would use the following <filename>RRECOMMENDS</filename> In this case, you would use the following:
statement:
<literallayout class='monospaced'> <literallayout class='monospaced'>
RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;" RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
</literallayout> </literallayout>
@ -1099,8 +1108,6 @@
appear as it would in the appear as it would in the
<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
renaming of the output package by classes like <filename>debian.bbclass</filename>. renaming of the output package by classes like <filename>debian.bbclass</filename>.
Also, you would provide the actual name of the package that supports the wireless
capabilities.
</para> </para>
</glossdef> </glossdef>
</glossentry> </glossentry>