* [yocto-docs][PATCH 01/11] documentation: dev-manual: fix spelling
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 02/11] documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH Paul Eggleton
` (10 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
sence -> sense
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/dev-manual/dev-manual-newbie.xml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 9b922b1..20cf234 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -325,7 +325,7 @@
<ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
</para></listitem>
<listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
- In its most general sence, it is an open-source project that was initially developed
+ In its most general sense, it is an open-source project that was initially developed
by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
build system becoming a build system for embedded images.
After Intel Corporation aquired OpenedHand, the project poky became the basis for
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 02/11] documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 01/11] documentation: dev-manual: fix spelling Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 03/11] documentation: poky-ref-manual: improve MACHINE_* variable descriptions Paul Eggleton
` (9 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
LICENSE_PATH is the correct variable to use for 1.3 - see:
https://bugzilla.yoctoproject.org/show_bug.cgi?id=3118
Fixes documentation for [YOCTO #3118].
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index fd04017..62c2596 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1327,15 +1327,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
</glossdef>
</glossentry>
- <glossentry id='var-LICENSE_DIR'><glossterm>LICENSE_DIR</glossterm>
+ <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
<glossdef>
<para>Path to additional licenses used during the build.
By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
to define the directory that holds common license text used during the build.
- The <filename>LICENSE_DIR</filename> variable allows you to extend that
+ The <filename>LICENSE_PATH</filename> variable allows you to extend that
location to other areas that have additional licenses:
<literallayout class='monospaced'>
- LICENSE_DIR += "/path/to/additional/common/licenses"
+ LICENSE_PATH += "/path/to/additional/common/licenses"
</literallayout></para>
</glossdef>
</glossentry>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 03/11] documentation: poky-ref-manual: improve MACHINE_* variable descriptions
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 01/11] documentation: dev-manual: fix spelling Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 02/11] documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 04/11] documentation: poky-ref-manual: extend description of MACHINE variable Paul Eggleton
` (8 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
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.
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 124 +++++++++++------------
1 file changed, 60 insertions(+), 64 deletions(-)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 62c2596..af1c9e1 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1354,8 +1354,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef>
<para></para>
<para>
- 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.
@@ -1365,16 +1365,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<para>
This variable is similar to the
<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.
In other words, the image will not build if a file in this list is not found.
</para>
<para>
- 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 you are building for requires
+ a specific program to be run during boot to initialise the hardware.
+ In this case, assuming the package name for the program was
+ <filename>example-init</filename>, you would use the following in the
+ .conf file for the machine:
<literallayout class='monospaced'>
- MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "<disk_driver>"
+ MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
</literallayout>
</para>
</glossdef>
@@ -1384,8 +1386,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef>
<para></para>
<para>
- 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.
@@ -1395,46 +1397,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<para>
This variable is similar to the
<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.
- 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.
- </para>
- <para>
- 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.
+ </para>
+ <para>
+ 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
+ <filename>kernel-module-ab123</filename>, you would use the
+ following in the .conf file for the machine:
+ <literallayout class='monospaced'>
+ MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
+ </literallayout>
</para>
<para>
- 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).
</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'>
- MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "<mouse_driver>"
- </literallayout>
- </para>
</glossdef>
</glossentry>
<glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
<glossdef>
<para>
- 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
<filename>packagegroup-base</filename>, which does not include the
<filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
@@ -1443,22 +1440,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<para>
This variable is similar to the
<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.
In other words, the image will not build if a file in this list is not found.
</para>
<para>
- 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
+ it. 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
+ <filename>wifidriver-firmware</filename>, you would use the following in the
+ .conf file for the machine:
<literallayout class='monospaced'>
- MACHINE_EXTRA_RDEPENDS += "<wifi_driver>"
+ MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
</literallayout>
</para>
</glossdef>
@@ -1468,9 +1465,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef>
<para></para>
<para>
- 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
<filename>packagegroup-base</filename>, which does not include the
@@ -1480,23 +1477,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<para>
This variable is similar to the
<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.
In other words, the image will build if a file in this list is not found.
</para>
<para>
- 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
+ it. 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
+ <filename>kernel-module-examplewifi</filename>, you would use the
+ following in the .conf file for the machine:
<literallayout class='monospaced'>
- MACHINE_EXTRA_RRECOMMENDS += "<wifi_driver>"
+ MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
</literallayout>
</para>
</glossdef>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 04/11] documentation: poky-ref-manual: extend description of MACHINE variable
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (2 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 03/11] documentation: poky-ref-manual: improve MACHINE_* variable descriptions Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 05/11] documentation: poky-ref-manual: add PACKAGECONFIG variable Paul Eggleton
` (7 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
Extend the description of the MACHINE variable so that it mentions that
this points to a .conf file under conf/machine.
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index af1c9e1..fa2bc7f 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1346,7 +1346,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
<glossdef>
- <para>Specifies the target device.</para>
+ <para>
+ Specifies the target device. This corresponds to a file with the
+ extension .conf located in a <filename>conf/machine</filename> directory
+ within the metadata that contains the target device configuration.
+ </para>
</glossdef>
</glossentry>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 05/11] documentation: poky-ref-manual: add PACKAGECONFIG variable
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (3 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 04/11] documentation: poky-ref-manual: extend description of MACHINE variable Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 06/11] documentation: poky-ref-manual: extend DISTRO description Paul Eggleton
` (6 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
Add a description of the PACKAGECONFIG variable to the variable
glossary.
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 31 +++++++++++++++++++++++
1 file changed, 31 insertions(+)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index fa2bc7f..0bb3094 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -1577,6 +1577,37 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
</glossdef>
</glossentry>
+ <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
+ <glossdef>
+ <para>
+ Provides a means of enabling or disabling features of a recipe
+ on a per-recipe basis. The <filename>PACKAGECONFIG</filename>
+ variable itself specifies a space-separated list of the features
+ to enable, whilst the named flags set on the variable specify
+ for each feature the additional build dependencies
+ (<filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>)
+ that should be added if the feature is enabled, and any extra arguments
+ that should be added to the configure script argument list
+ (<filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename>)
+ if the feature is enabled or disabled.
+ </para>
+ <para>
+ For example, the following taken from the <filename>librsvg</filename>
+ recipe will add <filename>--with-croco</filename> to the
+ configure script arguments and <filename>libcroco</filename> to
+ <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>
+ by default; however, if "croco" is removed from <filename>PACKAGECONFIG</filename>
+ (for example, by using a bbappend in another layer) then
+ <filename>--without-croco</filename> will be added to the configure
+ script arguments instead:
+ <literallayout class='monospaced'>
+ PACKAGECONFIG ??= "croco"
+ PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
+ </literallayout>
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
<glossdef>
<para>The list of packages to be created from the recipe.
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 06/11] documentation: poky-ref-manual: extend DISTRO description
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (4 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 05/11] documentation: poky-ref-manual: add PACKAGECONFIG variable Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 07/11] documentation: poky-ref-manual: add information on *_FEATURES_BACKFILL Paul Eggleton
` (5 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
Extend the description of the DISTRO variable so that it mentions that
this points to a .conf file under conf/distro and mentions what happens
if the value is left blank.
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 0bb3094..ba81f96 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -448,7 +448,16 @@
<glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
<glossdef>
- <para>The short name of the distribution.</para>
+ <para>
+ The short name of the distribution. This corresponds to a file with the
+ extension .conf located in a <filename>conf/distro</filename> directory
+ within the metadata that contains the distribution configuration. The
+ value must not contain spaces, and is typically all lower-case.
+ </para>
+ <para>
+ If blank, a set of default configuration will be used, which is specified
+ within <filename>meta/conf/distro/defaultsetup.conf</filename>.
+ </para>
</glossdef>
</glossentry>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 07/11] documentation: poky-ref-manual: add information on *_FEATURES_BACKFILL
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (5 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 06/11] documentation: poky-ref-manual: extend DISTRO description Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 08/11] documentation: poky-ref-manual: fix description of SUMMARY variable Paul Eggleton
` (4 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
Document DISTRO_FEATURES_BACKFILL and MACHINE_FEATURES_BACKFILL. We may
wish to expand upon this in future, but at least this explains what
these variables are for and how to use them.
Also add a link from the DISTRO_FEATURES entry to the section that lists
valid DISTRO_FEATURES items.
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-features.xml | 46 +++++++++++++++++++
documentation/poky-ref-manual/ref-variables.xml | 54 ++++++++++++++++++++++-
2 files changed, 99 insertions(+), 1 deletion(-)
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
index 159d56d..81ba8e5 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -171,6 +171,52 @@
</itemizedlist>
</para>
</section>
+
+ <section id='ref-features-backfill'>
+ <title>Feature backfilling</title>
+
+ <para>
+ Sometimes, it is necessary for a new feature to be added to control existing
+ functionality that was previously enabled by default and not able to be disabled.
+ In order to ensure that the feature remains enabled for users with existing
+ configurations that upgrade to a new version of the core metadata without that
+ configuration having to be changed, whilst still allowing others who want to turn
+ the feature off to do so, the backfilling mechanism was introduced. This
+ functionality is available for <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+ and <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
+ </para>
+
+ <para>
+ An example is the "pulseaudio" distro feature. Previously, PulseAudio support
+ was enabled within the Qt and GStreamer frameworks; however some users desired
+ to be able to disable this. To allow this to be disabled without affecting
+ existing configurations in which PulseAudio support should remain enabled,
+ "pulseaudio" was added to
+ <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
+ within <filename>meta/conf/bitbake.conf</filename>; this means that "pulseaudio"
+ is automatically added to <filename>DISTRO_FEATURES</filename> without the distro
+ configuration needing to be updated to do so itself.
+ Those who do not want PulseAudio support can add "pulseaudio" to
+ <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>
+ in their distro .conf file and this will disable adding "pulseaudio" to
+ <filename>DISTRO_FEATURES</filename>.
+ </para>
+
+ <para>
+ Another example is the "rtc" machine feature. Previously, real time clock (RTC)
+ support was enabled for all target devices; however certain targets do not have
+ this capability. To allow this to be disabled by such machines without affecting
+ other machines in which RTC support should remain enabled, "rtc" was added to
+ <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
+ within <filename>meta/conf/bitbake.conf</filename>; this means that "rtc"
+ is automatically added to <filename>MACHINE_FEATURES</filename> without the
+ machine configuration needing to be updated to do so itself.
+ For machines that not need RTC support can add "rtc" to
+ <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>
+ in their machine .conf file and this will disable adding "rtc" to
+ <filename>MACHINE_FEATURES</filename>.
+ </para>
+ </section>
</chapter>
<!--
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index ba81f96..c71a959 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -471,7 +471,35 @@
<glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
<glossdef>
- <para>The features of the distribution.</para>
+ <para>The features enabled for the distribution.
+ For a list of valid features, see the
+ <link linkend='ref-features-distro'>Distro</link>
+ section.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
+ <glossdef>
+ <para>Features to be added to
+ <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+ if not also present in
+ <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+ See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
+ more information.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
+ <glossdef>
+ <para>Features from
+ <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
+ that should not be added to
+ <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>.
+ See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
+ more information.
+ </para>
</glossdef>
</glossentry>
@@ -1519,6 +1547,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
</glossdef>
</glossentry>
+ <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
+ <glossdef>
+ <para>Features to be added to
+ <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
+ if not also present in
+ <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+ See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
+ more information.
+ </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
+ <glossdef>
+ <para>Features from
+ <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
+ that should not be added to
+ <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
+ See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
+ more information.
+ </para>
+ </glossdef>
+ </glossentry>
+
<glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
<glossdef>
<para>The email address of the distribution maintainer.</para>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 08/11] documentation: poky-ref-manual: fix description of SUMMARY variable
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (6 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 07/11] documentation: poky-ref-manual: add information on *_FEATURES_BACKFILL Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 09/11] documentation: poky-ref-manual: remove references to ipkg Paul Eggleton
` (3 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
* Use correct/up-to-date names of package systems
* SUMMARY does not default to the value of DESCRIPTION, it's the other
way around (although the logic may be improved in future so that this
is the effect).
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index c71a959..ccdb0e8 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -2217,9 +2217,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
<glossdef>
<para>The short (72 characters or less) summary of the binary package for packaging
- systems such as <filename>ipkg</filename>, <filename>rpm</filename> or
- <filename>debian</filename>.
- By default, this variable inherits <filename>DESCRIPTION</filename>.</para>
+ systems such as <filename>opkg</filename>, <filename>rpm</filename> or
+ <filename>dpkg</filename>.
+ </para>
</glossdef>
</glossentry>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 09/11] documentation: poky-ref-manual: remove references to ipkg
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (7 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 08/11] documentation: poky-ref-manual: fix description of SUMMARY variable Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 15:38 ` [yocto-docs][PATCH 11/11] documentation: poky-ref-manual: update directory structure information Paul Eggleton
` (2 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
We haven't supported ipkg for some time now - it was replaced by opkg
(whilst still using the ipk package format).
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/faq.xml | 2 +-
documentation/poky-ref-manual/ref-variables.xml | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
index 943d22a..945c7f1 100644
--- a/documentation/poky-ref-manual/faq.xml
+++ b/documentation/poky-ref-manual/faq.xml
@@ -166,7 +166,7 @@
<answer>
<para>
The OpenEmbedded build system can build packages in various formats such as
- <filename>ipk</filename> for <filename>ipkg</filename>/<filename>opkg</filename>,
+ <filename>ipk</filename> for <filename>opkg</filename>,
Debian package (<filename>.deb</filename>), or RPM.
The packages can then be upgraded using the package tools on the device, much like
on a desktop distribution such as Ubuntu or Fedora.
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index ccdb0e8..dd858d3 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -114,8 +114,8 @@
<glossdef>
<para>
A list of packages not to install despite being recommended by a recipe.
- Support for this variable exists only for images that use the
- <filename>ipkg</filename> packaging system.
+ Support for this variable exists only when using the
+ <filename>ipk</filename> packaging backend.
</para>
</glossdef>
</glossentry>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 11/11] documentation: poky-ref-manual: update directory structure information
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (8 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 09/11] documentation: poky-ref-manual: remove references to ipkg Paul Eggleton
@ 2012-10-08 15:38 ` Paul Eggleton
2012-10-08 16:51 ` [yocto-docs][PATCH 10/11] documentation: poky-ref-manual: replace "package" with "recipe" where appropriate Paul Eggleton
2012-10-08 17:13 ` [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 15:38 UTC (permalink / raw)
To: Scott Rifenbark, yocto
* Add meta-yocto, meta-yocto-bsp and meta-hob
* Remove meta-rt - this was merged into OE-Core (meta)
* Remove meta-demoapps - this was dropped
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-structure.xml | 30 ++++++++++++++++-------
1 file changed, 21 insertions(+), 9 deletions(-)
diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml
index fcdf7b1..75bc2eb 100644
--- a/documentation/poky-ref-manual/ref-structure.xml
+++ b/documentation/poky-ref-manual/ref-structure.xml
@@ -93,25 +93,37 @@
<para>
This directory contains the OpenEmbedded Core metadata.
- The directory holds machine definitions, the Yocto Project distribution,
- and the packages that make up a given system.
+ The directory holds recipes, common classes, and machine
+ configuration for emulated targets (qemux86, qemuarm,
+ and so on.)
</para>
</section>
- <section id='structure-core-meta-demoapps'>
- <title><filename>meta-demoapps/</filename></title>
+ <section id='structure-core-meta-yocto'>
+ <title><filename>meta-yocto/</filename></title>
<para>
- This directory contains recipes for applications and demos that are not part of the
- OpenEmbedded core.
+ This directory contains the configuration for the Poky
+ reference distribution.
</para>
</section>
- <section id='structure-core-meta-rt'>
- <title><filename>meta-rt/</filename></title>
+ <section id='structure-core-meta-yocto-bsp'>
+ <title><filename>meta-yocto-bsp/</filename></title>
<para>
- This directory contains recipes for real-time kernels.
+ This directory contains the Yocto Project reference
+ hardware BSPs.
+ </para>
+ </section>
+
+ <section id='structure-meta-hob'>
+ <title><filename>meta-hob/</filename></title>
+
+ <para>
+ This directory contains template recipes used by the
+ <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink>
+ build UI.
</para>
</section>
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* [yocto-docs][PATCH 10/11] documentation: poky-ref-manual: replace "package" with "recipe" where appropriate
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (9 preceding siblings ...)
2012-10-08 15:38 ` [yocto-docs][PATCH 11/11] documentation: poky-ref-manual: update directory structure information Paul Eggleton
@ 2012-10-08 16:51 ` Paul Eggleton
2012-10-08 17:13 ` [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 16:51 UTC (permalink / raw)
To: yocto
We have to take care when using "package" to avoid confusion, even when
referring to variables with a historical package association (PV, PN
etc.).
Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
documentation/poky-ref-manual/ref-variables.xml | 25 ++++++++++++-----------
1 file changed, 13 insertions(+), 12 deletions(-)
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index dd858d3..7153731 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -200,14 +200,14 @@
<glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
<glossdef>
<para>Assigns the priority for recipe files in each layer.</para>
- <para>This variable is useful in situations where the same package appears in
+ <para>This variable is useful in situations where the same recipe appears in
more than one layer.
Setting this variable allows you to prioritize a
- layer against other layers that contain the same package - effectively
+ layer against other layers that contain the same recipe - effectively
letting you control the precedence for the multiple layers.
The precedence established through this variable stands regardless of a
- layer's package version (<filename>PV</filename> variable).
- For example, a layer that has a package with a higher <filename>PV</filename> value but for
+ recipe's version (<filename>PV</filename> variable).
+ For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
lower precedence.</para>
<para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
@@ -269,7 +269,7 @@
<glossentry id='var-BP'><glossterm>BP</glossterm>
<glossdef>
<para>The base recipe name and version but without any special
- package name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
+ recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
and so forth).
<filename>BP</filename> is comprised of the following:
<literallayout class="monospaced">
@@ -280,7 +280,7 @@
<glossentry id='var-BPN'><glossterm>BPN</glossterm>
<glossdef>
- <para>Bare name of package with any suffixes like -cross -native removed.</para>
+ <para>Bare name of recipe with any suffixes like -cross -native removed.</para>
</glossdef>
</glossentry>
@@ -825,7 +825,8 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
<glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
<glossdef>
- <para>Website where more info about package can be found</para>
+ <para>Website where more information about the software the recipe is building
+ can be found.</para>
</glossdef>
</glossentry>
@@ -2356,7 +2357,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<glossdef>
<para>
The pathname of the working directory in which the OpenEmbedded build system
- builds packages.
+ builds a recipe.
This directory is located within the
<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
as different packages are built.
@@ -2369,9 +2370,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
<listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
<listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
- <listitem>The package name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
- <listitem>The package version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
- <listitem>The package revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
+ <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
+ <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
+ <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
</itemizedlist>
</para>
@@ -2403,7 +2404,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
named <filename>poky</filename> and a default build directory
at <filename>poky/build</filename>.
In this case, the working directory the build system uses to build
- the <filename>acl</filename> package, which is dependent on a
+ the <filename>acl</filename> recipe, which is being built for a
MIPS-based device, is the following:
<literallayout class='monospaced'>
~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
--
1.7.9.5
^ permalink raw reply related [flat|nested] 13+ messages in thread* Re: [yocto-docs][PATCH 00/11] Documentation improvements
2012-10-08 15:38 [yocto-docs][PATCH 00/11] Documentation improvements Paul Eggleton
` (10 preceding siblings ...)
2012-10-08 16:51 ` [yocto-docs][PATCH 10/11] documentation: poky-ref-manual: replace "package" with "recipe" where appropriate Paul Eggleton
@ 2012-10-08 17:13 ` Paul Eggleton
11 siblings, 0 replies; 13+ messages in thread
From: Paul Eggleton @ 2012-10-08 17:13 UTC (permalink / raw)
To: yocto
On Monday 08 October 2012 16:38:06 Paul Eggleton wrote:
> Add some missing variables to the variable reference and improve
> the descriptions of others. Also fix references to "package" where
> we mean "recipe" and a couple of other issues I noticed at the same
> time.
>
>
> The following changes since commit 821162221818f5ce53bb903aeef57c85314f5083:
>
> documentation: dev-manual - mentioned SRC_URI in the kernel example
> (2012-10-05 11:25:03 -0700)
>
> are available in the git repository at:
>
> git://git.yoctoproject.org/poky-contrib paule/doc-fixes-5
> http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/doc-fixes-5
>
> Paul Eggleton (11):
> documentation: dev-manual: fix spelling
> documentation: poky-ref-manual: correct LICENSE_DIR -> LICENSE_PATH
> documentation: poky-ref-manual: improve MACHINE_* variable
> descriptions
> documentation: poky-ref-manual: extend description of MACHINE
> variable
> documentation: poky-ref-manual: add PACKAGECONFIG variable
> documentation: poky-ref-manual: extend DISTRO description
> documentation: poky-ref-manual: add information on
> *_FEATURES_BACKFILL
> documentation: poky-ref-manual: fix description of SUMMARY variable
> documentation: poky-ref-manual: remove references to ipkg
> documentation: poky-ref-manual: replace "package" with "recipe" where
> appropriate
> documentation: poky-ref-manual: update directory structure
> information
>
> documentation/dev-manual/dev-manual-newbie.xml | 2 +-
> documentation/poky-ref-manual/faq.xml | 2 +-
> documentation/poky-ref-manual/ref-features.xml | 46 ++++
> documentation/poky-ref-manual/ref-structure.xml | 30 ++-
> documentation/poky-ref-manual/ref-variables.xml | 267
> +++++++++++++++-------- 5 files changed, 249 insertions(+), 98 deletions(-)
Apologies if 10/11 comes through twice, there was some kind of issue with
getting the original mail through to the mailing list server so I resent it.
Cheers,
Paul
--
Paul Eggleton
Intel Open Source Technology Centre
^ permalink raw reply [flat|nested] 13+ messages in thread