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:
parent
0fb1d6e620
commit
1bc65c7320
|
@ -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 += "<mouse_driver>"
|
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "<disk_driver>"
|
||||||
</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 += "<mouse_driver>"
|
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "<mouse_driver>"
|
||||||
</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 += "<wifi_driver>"
|
MACHINE_EXTRA_RDEPENDS += "<wifi_driver>"
|
||||||
</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 += "<wifi_driver>"
|
MACHINE_EXTRA_RRECOMMENDS += "<wifi_driver>"
|
||||||
</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 += "<wireless_package_name>"
|
RRECOMMENDS_${PN}-dev += "<wireless_package_name>"
|
||||||
</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>
|
||||||
|
|
Loading…
Reference in New Issue