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@...>
---
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

* 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@...>
---
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

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@...>
---
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

* 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@...>
---
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

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@...>
---
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

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@...>
---
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

Add a description of the PACKAGECONFIG variable to the variable
glossary.

Signed-off-by: Paul Eggleton <paul.eggleton@...>
---
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

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@...>
---
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

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@...>
---
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 += "&lt;disk_driver&gt;"
+ 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 += "&lt;mouse_driver&gt;"
- </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 += "&lt;wifi_driver&gt;"
+ 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 += "&lt;wifi_driver&gt;"
+ MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
</literallayout>
</para>
</glossdef>
--
1.7.9.5

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@...>
---
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

sence -> sense

Signed-off-by: Paul Eggleton <paul.eggleton@...>
---
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

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(-)

--
1.7.9.5

Aloha all,

If possible could someone advise on what the content of the Yocto
developr Day will be at this year's ELCE? I'm thinking of attending
but need to know what it entails and how useful it would be for me,
not just so I don't waste time, but also so that I can make the
required case to management to send me there.

I understand there will be a mix of begginer and advanced
sessions/labs but knowing the type of content in those sessions would
be useful.

Many thanks,

Andy

--
Andrew Wafaa
IRC: FunkyPenguin
GPG: 0x3A36312F

On Mon, Oct 8, 2012 at 3:58 AM, Chris Tapp <opensource@...> wrote:

On 7 Oct 2012, at 22:41, Bruce Ashfield wrote:

On Sun, Oct 7, 2012 at 6:08 PM, Chris Tapp <opensource@...> wrote:

On 7 Oct 2012, at 03:00, Saxena, Rahul wrote:

Try adding the unionfs feature (below) to your kernel:

http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.0/tree/meta/cfg/kernel-cache/features/unionfs?h=meta

create a file my_cedartrail.scc with following line:
include features/unionfs/unionfs.scc

put this file in a dir linux-yocto, the dir being created in

meta-cedartrail/recipes-kernel/linux

add following line in meta-cedartrail/recipes-kernel/Linux/linux-yocto_3.0.bbappend

SRC_URI +="file://my_cedartrail.scc"

Thanks - I thought just running 'menuconfig' would allow me to enable it (for a quick test).

However, this still doesn't seem to be working. I can see that 'my_cedartrail.scc' gets fetched in to the build area, but I still don't see CONFIG_UNION_FS if I run 'menuconfig'. There is also no 'unionfs' folder in fs/ of the build tree.

Also, if I specify an invalid feature (e.g. feature2/unionfs/unionfs.scc) I'm not seeing any diagnostic.

unionfs was never merged to the 3.0 kernel, I re-added it to the development
trees for 3.2 and the 3.4 kernel (aufs for the 3.6 tree at the moment). The meta
data is carried forward from the older kernels as a placeholder and is
documented
in the .scc file itself:

-----------------------
kconf non-hardware unionfs.cfg

# commented pending update to a newer version ported to 2.6.35+
# patch unionfs-2.5.4-integration.patch
-----------------------

So to get unionfs in the 3.0 kernel, we'd need a port .. but since
we've moved on
quite a bit past 3.0, I don't know of any pending ports myself.

Thanks Bruce.

I guess I need to ask the Intel guys if there are any plans to move Cedartrail on from 3.0 ?

It will have to happen post yocto 1.3 (as far as I know), since the
3.0 kernel will be
dropped at that point.

For the short term, it's likely easier to backport/update unionfs than
it would be to
update the BSP .. but I can't speak for the time to be spent doing it :)

Cheers,

Bruce

Cheers,

Bruce

-----Original Message-----
From: yocto-bounces@... [mailto:yocto-bounces@...] On Behalf Of Chris Tapp
Sent: Saturday, October 06, 2012 5:43 PM
To: yocto@... Project
Subject: [yocto] Meta Intel / Cedartrail / Denzil - how to get unionfs in the kernel

I' trying to enable unionfs in the 3.0.32 kernel for the cedartrail BSP under Denzil 7.0.1.

However, the CONFIG_UNION_FS config flag isn't in the .config ...

Is there something else I need to enable, or do I need to find another way?

Chris Tapp

opensource@...
www.keylevel.com



_______________________________________________
yocto mailing list
yocto@...
https://lists.yoctoproject.org/listinfo/yocto

Chris Tapp

opensource@...
www.keylevel.com



_______________________________________________
yocto mailing list
yocto@...
https://lists.yoctoproject.org/listinfo/yocto

--
"Thou shalt not follow the NULL pointer, for chaos and madness await
thee at its end"

Chris Tapp

opensource@...
www.keylevel.com

--
"Thou shalt not follow the NULL pointer, for chaos and madness await
thee at its end"

Hi Andreas,

On Monday 08 October 2012 12:54:46 Andreas Müller wrote:

as some of you might know, gumstix created an official BSP layer
[1][2]. To avoid confusion I renamed my layer from meta-gumstix to
meta-gumstix-community [3]. Users should either switch to the official
meta-gumstix layer or rename meta-gumstix to meta-gumstix-community
[3] in git configuration (users of angstrom-setup-scripts should also
change the name in layers.txt).

So what should we do with the layer index [4]? Do we list both? What is the
delta between them, and is there a hope that there will be only one layer at
some point?

Cheers,
Paul

[4] http://www.openembedded.org/wiki/LayerIndex

--

Paul Eggleton
Intel Open Source Technology Centre

Hi,

as some of you might know, gumstix created an official BSP layer
[1][2]. To avoid confusion I renamed my layer from meta-gumstix to
meta-gumstix-community [3]. Users should either switch to the official
meta-gumstix layer or rename meta-gumstix to meta-gumstix-community
[3] in git configuration (users of angstrom-setup-scripts should also
change the name in layers.txt).

Andreas

[1] http://sourceforge.net/mailarchive/message.php?msg_id=29914700
[2] https://github.com/gumstix/meta-gumstix
[3] https://gitorious.org/schnitzeltony-oe-meta/meta-gumstix-community

On 7 Oct 2012, at 22:41, Bruce Ashfield wrote:

On Sun, Oct 7, 2012 at 6:08 PM, Chris Tapp <opensource@...> wrote:

On 7 Oct 2012, at 03:00, Saxena, Rahul wrote:

Try adding the unionfs feature (below) to your kernel:

http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-3.0/tree/meta/cfg/kernel-cache/features/unionfs?h=meta

create a file my_cedartrail.scc with following line:
include features/unionfs/unionfs.scc

put this file in a dir linux-yocto, the dir being created in

meta-cedartrail/recipes-kernel/linux

add following line in meta-cedartrail/recipes-kernel/Linux/linux-yocto_3.0.bbappend

SRC_URI +="file://my_cedartrail.scc"

Thanks - I thought just running 'menuconfig' would allow me to enable it (for a quick test).

However, this still doesn't seem to be working. I can see that 'my_cedartrail.scc' gets fetched in to the build area, but I still don't see CONFIG_UNION_FS if I run 'menuconfig'. There is also no 'unionfs' folder in fs/ of the build tree.

Also, if I specify an invalid feature (e.g. feature2/unionfs/unionfs.scc) I'm not seeing any diagnostic.

unionfs was never merged to the 3.0 kernel, I re-added it to the development
trees for 3.2 and the 3.4 kernel (aufs for the 3.6 tree at the moment). The meta
data is carried forward from the older kernels as a placeholder and is
documented
in the .scc file itself:

-----------------------
kconf non-hardware unionfs.cfg

# commented pending update to a newer version ported to 2.6.35+
# patch unionfs-2.5.4-integration.patch
-----------------------

So to get unionfs in the 3.0 kernel, we'd need a port .. but since
we've moved on
quite a bit past 3.0, I don't know of any pending ports myself.

Thanks Bruce.

I guess I need to ask the Intel guys if there are any plans to move Cedartrail on from 3.0 ?

Cheers,

Bruce

-----Original Message-----
From: yocto-bounces@... [mailto:yocto-bounces@...] On Behalf Of Chris Tapp
Sent: Saturday, October 06, 2012 5:43 PM
To: yocto@... Project
Subject: [yocto] Meta Intel / Cedartrail / Denzil - how to get unionfs in the kernel

I' trying to enable unionfs in the 3.0.32 kernel for the cedartrail BSP under Denzil 7.0.1.

However, the CONFIG_UNION_FS config flag isn't in the .config ...

Is there something else I need to enable, or do I need to find another way?

Chris Tapp

opensource@...
www.keylevel.com



_______________________________________________
yocto mailing list
yocto@...
https://lists.yoctoproject.org/listinfo/yocto

Chris Tapp

opensource@...
www.keylevel.com



_______________________________________________
yocto mailing list
yocto@...
https://lists.yoctoproject.org/listinfo/yocto

--
"Thou shalt not follow the NULL pointer, for chaos and madness await
thee at its end"

Chris Tapp

opensource@...
www.keylevel.com

What is your bootargs ?  We also encountered this issue long time ago. The following bootargs line would cause this problem:
setenv bootargs 'console=tty0 console=ttyO2,115200n8 root=/dev/mmcblk0p2 rootwait rootfstype=ext3 ro'

Try to change "console=tty0 console=ttyO2,115200n8" to "console=ttyO2,115200n8 console=tty0" .
Please refer the bug 1823 (https://bugzilla.yoctoproject.org/show_bug.cgi?id=1823).


Thanks,
Yi